Engraphis

Engraphis

https://engraphis.com/

https://discord.com/invite/Wfr2ejBmY

Dale a tus agentes de IA una memoria. Mírala, búscala y mantenla, todo en una hermosa interfaz web en tu propia máquina.

^{Grafo de conocimiento · ejecuta engraphis-dashboard para verlo en vivo}

Fundamentado, no adivinado. Memoria con recibos. Local por defecto.

Límite de núcleo abierto: este repositorio contiene el motor local gratuito, el panel de control, el servidor MCP y los clientes del lado del cliente. La sincronización alojada, la analítica, la automatización y los servicios de equipo se ejecutan en el servicio alojado oficial; sus implementaciones de servidor no se distribuyen aquí.

Apoya el desarrollo continuo de Engraphis con Pro. Comienza una prueba Pro de 7 días o suscríbete a Pro.

Ahorro medido de tokens y contexto

Estimador en tiempo de ejecución

Las vistas de Resumen y Auditoría/Recibos del panel también muestran una estimación respaldada por recibos de las entregas de contexto reales. Compara el historial del host o la línea base de fuentes recuperadas con el contexto que Engraphis realmente emitió, mantiene los contadores de tokens y las versiones de lanzamiento separados, y etiqueta las reducciones adaptativas de historial por separado de los ahorros de empaquetado. Los recibos sin metadatos de estimador permanecen históricos/sin clasificar. Esto mide la reducción estimada del contexto de indicaciones; no mide la facturación del proveedor. La API /context-savings y la herramienta MCP engraphis_context_savings agregan el historial completo en todos los espacios de trabajo visibles de forma predeterminada, o aceptan un espacio de trabajo explícito más filtros opcionales de from_ts, to_ts y release_version.

^{Menos historial repetido significa más espacio para la tarea, las herramientas y la evidencia útil.}

python -m eval.grounded
python -m eval.chunking_eval --dataset eval/datasets/longdoc.jsonl --k 5
python -m eval.performance --dataset eval/datasets/codemem.jsonl --k 5 --iterations 10 --json

Instalación completa de Engraphis: pip install "engraphis[all]"

La instalación completa de engraphis[all] es la forma predeterminada de usar Engraphis: incluye el panel local, el servidor Smart MCP, documentos, el cliente de Cloud Sync y las integraciones opcionales compatibles. Se requiere Python 3.10+.

pip install "engraphis[all]"
engraphis-dashboard

El panel se abre en http://127.0.0.1:8700. La memoria local no necesita cuenta ni clave API.

Opciones de instalación más pequeñas

Usa un paquete más pequeño solo cuando necesites intencionalmente una superficie limitada. El núcleo solo NumPy continúa soportando Python 3.9+.

Para clientes MCP que no sean Codex, configura un servidor stdio cuyo comando sea engraphis-mcp; consulta la guía de conexión de agentes.

Actualización

Usa engraphis-update para actualizar la instalación usando su método de instalación detectado. Los metadatos del paquete no registran qué extras se seleccionaron, por lo que el actualizador usa por defecto el superconjunto seguro engraphis[all] en lugar de eliminar silenciosamente una superficie opcional. Para una selección deliberada, establece ENGRAPHIS_UPDATE_EXTRAS a una lista separada por comas (por ejemplo server,mcp), o establécelo a none solo para el paquete base.

Actualización a 1.4: engraphis-mcp ahora expone la puerta de enlace Smart de nueve herramientas. Las integraciones que requieren los 35 nombres de herramientas directos anteriores deben ejecutar engraphis-mcp-classic. El esquema SQLite en la versión 1.4.0 era la versión 9. Las bases de datos existentes de v7 a v8 ya contienen confidence y pinned_at/unpinned_at; v9 agrega la columna/tabla de alcance de repositorio memory_tombstones y realiza una reparación de canonicalización de entidades de una sola vez, luego migra automáticamente en la primera apertura. Una tumba con un repo_id conocido es terminal solo en ese repositorio; las tumbas heredadas sin repositorio permanecen globales. Consulta las notas de la versión 1.4.0.

Actualización a 1.5: el esquema 10 limita el estado de retención heredado y el esquema 11 rellena la aprobación explícita solo para memorias locales previas a la revisión elegibles. La evidencia pendiente y en cuarentena permanece bloqueada. Las bases de datos 1.4.x existentes migran automáticamente cuando Engraphis 1.5 las abre; consulta las notas de la versión 1.5.

Actualización a 1.6: las bases de datos 1.5 existentes migran automáticamente a través del esquema 12, que clasifica los marcadores de borrado sin contenido antes de la sincronización: los marcadores existentes se vuelven never_export solo locales, mientras que los borrados seguros nuevos se vuelven remote_erasure solo para registros workspace/repo no secretos ya elegibles para compartir. El esquema 13 agrega relojes lógicos híbridos por memoria para la sincronización determinista de estado descriptivo y una prueba duradera sin contenido de que una memoria cruzó un límite de sincronización. El esquema 14 agrega la colección de Obsidian y los manifiestos de importación; el esquema 15 los generaliza a documentos locales neutrales a la fuente, preserva el linaje temporal de la fuente a través de reimportaciones, vincula adaptadores y alcances objetivo, y retiene solo metadatos de formato/resultado por trabajo limitados y sin contenido. La migración del esquema 16 persiste el objetivo de sesión opcional de cada trabajo de importación y requiere que el linaje de la fuente y los adjuntos de elementos del trabajo permanezcan en esa sesión exacta. Consulta las notas de la versión 1.6.

Qué le da Engraphis a un agente

Un agente no debería tener que reconstruir un proyecto a partir de historiales de chat dispersos en cada tarea. Engraphis convierte el conocimiento local del proyecto en memoria con alcance y consciente del tiempo; recupera la evidencia que respalda la pregunta actual; y devuelve un paquete de contexto acotado y atribuible.

La tarea central es la continuidad: recuperar la decisión actual y respaldada del proyecto sin arrastrar todo el historial a la siguiente indicación. Consulta ahorro medido de tokens y contexto para la versión corta de cuánto menos historial tiene que llevar un agente.

Panel de control e interfaz local

El panel de Engraphis se abre http://127.0.0.1:8700. La memoria local no necesita cuenta en la nube, registro ni clave API, y permanece en un archivo SQLite en tu máquina.

Ledger es la interfaz local principal para recuperación, recuerdos, exploración de grafos, procedencia, espacios de trabajo y consolidación manual. Classic conserva el conjunto completo de herramientas anterior; ambos usan los mismos datos locales. Cambia en Manage → Settings → Interface (Ledger) o Settings → Appearance & Engine (Classic).

Inícialo en cada plataforma

En un checkout de código fuente, scripts/launch_dashboard.ps1 es solo un envoltorio de conveniencia para Windows. Delega la configuración, el estado de salud de inicio, la apertura del navegador y el ciclo de vida del proceso al mismo punto de entrada engraphis-dashboard en lugar de mantener una segunda ruta de comportamiento.

Inspección accesible primero, integrada

Inspecciona recuerdos, diferencias de supersesión, puntuaciones de recuperación, líneas de tiempo, enlaces, consolidación y registros de auditoría en el panel. El renderizador de grafos offline está incluido, y la interfaz es navegable por teclado con temas claro y oscuro. La exploración de grafos ofrece una vista enfocada de Alta calidad y una vista explícita de Cada nodo respaldada por trabajadores para proyecciones completas de entidades de hasta 20,000 nodos y 200,000 relaciones; consulta los perfiles de rendimiento de grafos.

Cómo funciona

Engraphis brinda a los agentes conocimiento de proyecto duradero, con ámbito y explicable. El motor local combina decaimiento de Ebbinghaus, hechos bi-temporales y recuperación híbrida vectorial/léxica/de grafos; funciona offline con SQLite, incrustaciones locales y solo numpy.

• Fundamentado y gobernado: resolución determinista de conflictos, respuestas citadas o abstención, corrección/promoción/olvido explícitos e historial completo.
• Listo para agentes: herramientas MCP, paquetes de contexto con presupuesto duro, traspasos y recuperación consciente del código.
• Auditable: cadenas de recibos sin contenido, procedencia y relaciones temporales/entidad/código.
• Práctico: ingesta local de archivos y código, PDF/OCR/transcripción opcionales y SQLCipher en reposo.

Proveedores LLM opcionales

El motor de memoria, las incrustaciones, la resolución de conflictos y la recuperación permanecen locales sin un LLM. Un proveedor configurado explícitamente añade extracción estructurada, síntesis citada, consolidación y supervisión de retención. Configúralo en Settings → Connect an LLM. La vista de actividad registra resultados, nunca claves, prompts ni respuestas crudas del proveedor. Consulta la guía de proveedores LLM para opciones de configuración y privacidad.

Límite de privacidad: el texto enviado a un proveedor seleccionado explícitamente sale del proceso local bajo los términos de ese proveedor. Usa ENGRAPHIS_RETENTION_SUPERVISOR=none (el predeterminado) y el extractor offline chunk cuando la ingesta deba permanecer completamente local.

Elige y configura un LLM externo con la guía de proveedores LLM, incluyendo OpenAI, Anthropic, Google, OpenRouter, Ollama, Cohere Command, Command Code Provider, y otros endpoints compatibles. La guía también cubre conexiones MCP de suscripción Codex.

Instalación

pip install "engraphis[all]"        # self-hosted dashboard, MCP, code graph, documents, transcription, PostgreSQL, and Cloud Sync
pip install "engraphis[server]"     # dashboard + REST API
pip install "engraphis[mcp]"        # MCP server only
pip install "engraphis[documents]"  # PDF + image OCR bindings
pip install "engraphis[transcription]" # faster-whisper audio/video
pip install "engraphis[postgres]"   # PostgreSQL schema introspection
pip install "engraphis[code]"       # tree-sitter code graph indexing
pip install "engraphis[vector]"     # native sqlite-vec exact-KNN acceleration
pip install "engraphis[cloud-sync]" # Cloud Sync client crypto/runtime
pip install "engraphis[encryption]" # SQLCipher encryption-at-rest extra
pip install engraphis               # core library: numpy only, fully offline

La imagen oficial de Docker incluye el ejecutable local de Tesseract para OCR de imágenes. Fuera de Docker, el extra documents instala sus enlaces de Python; instala también Tesseract a través de tu sistema operativo si habilitas OCR de imágenes.

La biblioteca principal solo con NumPy soporta Python 3.9+. Las versiones parcheadas actuales de la pila WebUI, el SDK MCP, el analizador de imágenes y el cliente Cloud Sync requieren Python 3.10+, así que usa Python 3.10 o más reciente para las rutas de instalación server, mcp, documents, cloud-sync o all.

El NumpyVectorIndex predeterminado realiza un escaneo completo exacto. No hay un límite universal de recuento de memoria porque la latencia depende del tamaño del vector, el hardware, los filtros y el resto de la canalización de recuperación. Mide tu máquina con python -m eval.vector_scale --backend numpy, luego ejecuta python -m eval.performance en un corpus representativo. Si los escaneos exactos no alcanzan tu objetivo de latencia, instala engraphis[vector], crea el motor con vector_backend="sqlite-vec" y vuelve a medir. El backend estable sqlite-vec vec0 ejecuta KNN exacto en código nativo; es aceleración, no una afirmación de escalado ANN sublineal. Consulta BENCHMARKS.md para los comandos reproducibles y los límites de informes.

Los puntos de entrada del panel, REST y MCP usan por defecto ENGRAPHIS_VECTOR_BACKEND=auto: usan sqlite-vec cuando el extra vector está instalado y es compatible, luego recurren de forma segura a NumPy. Los MemoryEngine.create() y MemoryService.create() programáticos conservan el predeterminado determinista numpy a menos que se solicite un backend explícitamente. Usa python -m eval.vector_scale --backend sqlite-vec para una comparación de búsqueda directa con entrada idéntica; el tiempo de configuración/construcción del índice se excluye explícitamente del envoltorio de búsqueda cronometrado.

Los vectores persistentes fallan de forma cerrada a menos que el incrustador pueda publicar una huella de espacio duradera, sin secretos y sin secretos. Los Sentence Transformers usan el commit de Hub cargado o un manifiesto de artefactos locales; cuando la identidad inmutable de un modelo remoto no se puede resolver, la recuperación de vectores persistentes permanece restringida en lugar de mezclar espacios. Para incrustaciones programáticas compatibles con OpenAI, construye ApiEmbedder con un space_version de operador/proveedor; sin él, el adaptador permanece utilizable solo para incrustación efímera. Su base_url puede ser una raíz de proveedor o una raíz /v1 y se normaliza a exactamente un endpoint /v1/embeddings.

sqlcipher3-binary publica ruedas CPython manylinux x86-64. En ese objetivo, engraphis[encryption] instala el controlador. El extra multiplataforma all deliberadamente lo omite para que all siga siendo resoluble en macOS, Windows, Linux ARM y musl; en esos objetivos, aprovisiona un controlador SQLCipher compatible por separado antes de habilitar una clave de base de datos. El núcleo programático permanece en texto plano a menos que se configure una clave de base de datos. Para una base de datos nueva, engraphis-init habilita SQLCipher automáticamente cuando hay un controlador compatible disponible, crea un sidecar de clave privada y se puede anular con --no-encryption.

Linux / macOS: si pip install falla con error: externally-managed-environment, tu Python del sistema está marcado como de solo lectura (PEP 668). Instala en un entorno virtual en su lugar. Ejecuta python3 -m venv venv && source venv/bin/activate && pip install "engraphis[server]" Alternativamente, usa Docker (docker compose up). pipx install "engraphis[server]" también funciona.

La primera ejecución descarga all-MiniLM-L6-v2 (~80 MB). Sin él, el motor recurre al hash de características determinista para que siempre funcione offline. Ese respaldo captura superposición léxica, no significado: la recuperación y las respuestas MCP fundamentadas establecen degraded_mode=true y semantic_support=false, y deshabilitan la recuperación vectorial más la evidencia de coseno semántico. Instala un modelo de incrustación declarado para la recuperación semántica.

Para requerir un modelo que ya esté local, establece ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path o local:<cached-model-id>. Esta ruta nunca descarga un modelo. Si no está disponible, Engraphis entra explícitamente en modo degradado léxico en lugar de presentar puntuaciones de hash-vector como semánticas.

Inicio rápido: panel de control

pip install "engraphis[server]"
engraphis-dashboard                   # → http://127.0.0.1:8700
engraphis-dashboard --install-shortcuts   # → Desktop + Start Menu icons

Primera ejecución offline: el primer lanzamiento descarga el modelo de incrustación all-MiniLM-L6-v2 (~80 MB), luego funciona completamente offline. Para permanecer solo offline, establece ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path (nunca descarga; los modelos locales desconocidos entran en modo degradado léxico en lugar de falsificar puntuaciones semánticas). La extracción usa por defecto ENGRAPHIS_EXTRACTOR=none (escrituras verbatim), el backend de vectores usa por defecto auto (aceleración nativa cuando está instalada, de lo contrario NumPy), y la recuperación sin un espacio semántico utilizable informa degraded_mode=true con recuperación léxica/de grafos. Ejecuta engraphis-init --check para verificar la instalación, los extras y la capacidad de escritura de la base de datos.

Docker

docker compose up                     # → http://127.0.0.1:8700

Para la persistencia de Docker Compose y la configuración del puerto de bucle local, consulta la guía de despliegue de Docker. engraphis-server y engraphis server son alias de compatibilidad sin interfaz para este mismo servicio v2, por lo que cada superficie pública tiene el mismo modelo de recuperación y retención con ámbito.

Para exposición LAN opcional, configuración de tokens y configuración MCP HTTP, consulta la guía de despliegue de Docker.

Establece ENGRAPHIS_API_TOKEN para requerir autenticación API y ENGRAPHIS_DB_KEY para cifrar la base de datos local en reposo. Las credenciales del plan alojado configuran clientes de clientes; no instalan implementaciones de servidor premium en esta imagen. Consulta docker-compose.yml para opciones.

Inicio rápido: servidor MCP (para agentes de codificación)

pip install "engraphis[mcp]"
engraphis-init                     # writes ~/.engraphis/config.env + prints config snippets
claude mcp add engraphis -- engraphis-mcp
codex mcp add engraphis -- engraphis-mcp  # Codex subscription

Primera ejecución offline: la primera llamada a herramienta carga de forma diferida el modelo de incrustación all-MiniLM-L6-v2 (~80 MB, misma descarga que el panel), luego la memoria funciona completamente offline sin clave API. Para permanecer solo offline, establece ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path (nunca descarga); la extracción usa por defecto ENGRAPHIS_EXTRACTOR=none, el backend de vectores auto recurre a NumPy sin el extra vector, y la recuperación sin un espacio semántico utilizable informa degraded_mode=true con recuperación léxica/de grafos. Ejecuta engraphis-init --check para verificar la instalación y la ruta de la base de datos antes de registrar el servidor.

Para la configuración y verificación de la suscripción Codex, consulta la guía de conexión de agentes y la guía de proveedores LLM.

engraphis-mcp es Smart MCP de configuración cero: los agentes comienzan con nueve herramientas compactas para sesiones, recuperación lista para prompts, memoria duradera, lectura/actualización de registros gobernados, revisión de conflictos, descubrimiento de acciones y ejecución segura. Para grafos de código, gobernanza, auditoría u otro trabajo avanzado, el agente llama a engraphis_discover_actions y luego al ejecutor de lectura o acción indicado; no se requiere selección de perfil. La puerta de enlace valida la capacidad descubierta nuevamente antes de ejecutarla, y los clientes siguen siendo responsables de su límite normal de aprobación de acciones destructivas.

Los clientes existentes que usan herramientas nombradas pueden usar engraphis-mcp-classic (o engraphis-mcp-http --classic). El inventario clásico completo, incluyendo engraphis_check_update, está en la referencia de herramientas MCP.

Elige dónde pertenecen las memorias del agente

Usa la configuración de conexión del agente en el panel para elegir un espacio de trabajo, guardar una asignación de repositorio a espacio de trabajo y copiar instrucciones de agente específicas del proyecto. Las llamadas MCP rutinarias con un espacio de trabajo omitido pueden heredar la sesión suministrada o la asignación de repositorio guardada. Los valores explícitos de espacio de trabajo, incluido "default", tienen prioridad; actualiza instrucciones o hooks antiguos que los tengan codificados. Los tipos de memoria describen el tipo de memoria, no su destino. Consulta organización del espacio de trabajo para la configuración, la prioridad de enrutamiento y la vista previa de movimientos de memorias existentes.

Extensión Pi

Para instalación, configuración, comandos del ciclo de vida y el límite de confianza local, consulta la guía de la extensión Pi.

Hook de sesión de Command Code SessionStart

integrations/commandcode/ incluye un hook de SessionStart que prepara una nueva sesión con contexto acotado y recuperado de la puerta de enlace local de Engraphis. Falla abierto en tiempo de espera y se instala mediante python scripts/install_cc_hook.py. El hook envía el nombre de la raíz de Git más cercana como repo y permite que el servidor aplique una asignación de espacio de trabajo guardada. Establece ENGRAPHIS_HOOK_WORKSPACE solo para una anulación explícita; una anulación anterior de default debe borrarse para usar la asignación. Su encabezado de contexto muestra el espacio de trabajo resuelto. Las versiones anteriores usaban por defecto un espacio de trabajo con el nombre de la carpeta del proyecto; guarda esa asignación para seguir recuperando esas memorias al inicio de la sesión.

Flota prime-agent

integrations/prime_agent/ incluye un paquete de Python de primera parte para PrimeIntellect prime-agent que expone las mismas nueve herramientas Smart MCP, con un PrimeAgentFleet de ocho subagentes nombrados (researcher, planner, coder, reviewer, tester, documenter, monitor, integrator) que comparten un engraphis-mcp stdio subproceso. Instala mediante pip install ./integrations/prime_agent y registra con python scripts/install_prime_agent.py. Consulta la guía de integración de prime-agent.

Qué es la integración. Un PrimeAgentFleet es una capa delgada de Python alrededor del mismo engraphis-mcp Smart gateway que usa cualquier otro host. En tiempo de ejecución, la flota mantiene un EngraphisMcpClient compartido, que posee un engraphis-mcp subproceso sobre JSON-RPC stdio. Cada uno de los ocho subagentes nombrados obtiene su propia sesión de Engraphis (iniciada de forma diferida en el primer uso de la herramienta) y su propio alcance predeterminado de repo, por lo que la memoria por rol está aislada mientras la puerta de enlace local sigue siendo de un solo proceso. Los ocho nombres de subagentes (researcher, planner, coder, reviewer, tester, documenter, monitor, integrator) son el valor predeterminado fijo; pasa agent_names=[...] a PrimeAgentFleet(...) para un conjunto personalizado. Las llamadas de herramientas concurrentes se serializan en la capa de marco JSON-RPC a través de un asyncio.Lock, por lo que el paralelismo a nivel de marco (ocho subagentes razonando a la vez) se conserva mientras que el transporte MCP subyacente sigue siendo un flujo ordenado. La única superficie de integración es EngraphisPrimeAgent.register() en integrations/prime_agent/src/engraphis_prime_agent/agent.py: ese es el punto de adaptador único para anular si la API de registro de herramientas de prime-agent difiere del contrato asumido de target.register_tool(name, fn, schema=...).

El diseño (ocho subagentes nombrados, un subproceso stdio compartido, arranque de sesión por agente y reenvío de entorno solo con ENGRAPHIS_* a la puerta de enlace) está registrado en ~/.commandcode/plans/prime-agent-integration.md en el host donde se desarrolló la integración. Cuando ese plan de host no está disponible (otras máquinas de colaboradores, CI), el mismo diseño se resume en la descripción del PR que introdujo la integración y en la guía de integración de prime-agent (secciones "Arquitectura" y "Modelo de concurrencia").

Inicio rápido: gráfico de repositorio

pip install "engraphis[code]"
engraphis-graph index -w acme -r api --root .
engraphis-graph search -w acme -r api "UserService"
# `query`/`explain` blend code search with your stored memories: query matches symbol
# and file NAMES (a full question sentence won't match anything), and explain's answer
# is drawn from memories recorded against the repo; both are empty on a fresh index.
engraphis-graph query -w acme -r api "UserService"
engraphis-graph explain -w acme -r api "why does deploy depend on approval?"
engraphis-graph path -w acme -r api UserService DatabasePool
engraphis-graph impact -w acme -r api --root . --git-range origin/main...HEAD
engraphis-graph prs -w acme -r api --base main --head HEAD
engraphis-graph export -w acme -r api -o engraphis-graph-out
engraphis-graph install-merge-driver --root .

La exportación contiene graph.json, un graph.html autocontenido y GRAPH_REPORT.md. La indexación admite Python, JavaScript, TypeScript, Go, Rust, Java, C#, C, C++, SQL y Terraform. Tree-sitter se usa cuando está disponible; el backend de regex sin dependencias sigue siendo un respaldo funcional. Se indexan definiciones, métodos, llamadas, importaciones, propiedad, variables, herencia/implementación y docstrings/comentarios. La indexación es incremental por hash de contenido, respeta .engraphisignore y no sigue enlaces simbólicos de archivos fuera de la raíz del repositorio. Los bordes de llamadas se basan en nombres y son de mejor esfuerzo en lugar de resueltos por tipo. El controlador de fusión de Git opcional valida JSON de gráfico acotado y une de forma determinista nodos y bordes en lugar de elegir un lado de la exportación.

Para una API de recuperación y gráfico de solo lectura que se pueda compartir sin exponer operaciones de escritura:

pip install "engraphis[server]"
engraphis-graph-server                 # API at http://127.0.0.1:8720; schema at /openapi.json

Un enlace que no sea de bucle local falla cerrado a menos que ENGRAPHIS_GRAPH_TOKEN (o ENGRAPHIS_API_TOKEN) esté establecido. Consulta el documento de arquitectura/diseño v3.

Inicio rápido: biblioteca de Python

from engraphis.service import MemoryService

mem = MemoryService.create("engraphis.db")
mem.remember("Auth migrated from JWT to PASETO.", workspace="acme", repo="api")
hit = mem.recall("why did we change auth?", workspace="acme", repo="api")
print(hit["context"])

El mismo MemoryService respalda el panel y el servidor MCP. La raíz del paquete también expone intencionalmente la fachada del motor de bajo nivel (MemoryEngine, create_memory_engine) para composición avanzada, mientras que MemoryService sigue siendo la API de servicio de alto nivel.

Las nuevas escrituras admiten visibilidad de session, repo y workspace. scope="user" está reservado y rechazado hasta que los registros lleven una identidad de propietario inmutable; no debe tratarse como memoria privada por persona. Las filas históricas de alcance de usuario permanecen vinculadas al espacio de trabajo por compatibilidad.

Después de una actualización, stats() informa recuentos de elegibilidad de avisos y cobertura activa del espacio de incrustación. La recuperación de cero resultados identifica un alcance con revisión de puerta en lugar de parecer vacío silenciosamente, y engraphis-cli review list|approve proporciona un flujo de trabajo local masivo con prueba previa. Los cambios de modelo de incrustación desencadenan una reconstrucción protegida; la recuperación de vectores permanece deshabilitada hasta que cada vector almacenado coincida con la nueva huella digital. Consulta recuperación de recuerdos.

Los hosts de agentes pueden evitar la recuperación cuando su historial existente ya encaja:

decision = mem.adaptive_context(
    "what should the agent do next?",
    current_history,
    workspace="acme",
    repo="api",
    max_context_tokens=8_192,
    retrieval_token_budget=1_024,
)
prompt_context = decision["context"]

La decisión es history_bypass cuando el historial encaja, retrieval cuando la evidencia compacta es fuerte, y history_fallback cuando la recuperación débil debería ampliarse de nuevo al historial crudo reciente.

Para un aviso de agente, prefiere engraphis_recall_context: devuelve un context empaquetado con presupuesto duro más sources compacto, contabilidad determinista de usage (budget_tokens, context_tokens, source_tokens, saved_tokens, savings_ratio, packed_count, omitted_count y token_counter), y diagnósticos opcionales. La contabilidad es exacta para el contador nombrado; inyecta el tokenizador del lector cuando se requiere paridad de tokens del modelo lector. engraphis_recall sigue siendo la superficie de recuperación completa compatible; usa response_mode="compact" cuando el contexto empaquetado es suficiente y los cuerpos de memoria completos lo duplicarían. Para la configuración avanzada de planificación de consultas, consulta la guía de arquitectura.

Las alternativas impulsadas por benchmarks son opcionales: packing_mode="coverage" mantiene unidades de evidencia completas de más memorias fuente, mientras que retrieval_recipe="conversation" y retrieval_recipe="long_session" seleccionan los puntos de partida medidos de profundidad/presupuesto. Los ajustes históricos de legacy/default permanecen sin cambios. Para un valor que debe sobrevivir a una edición de archivo o llamada de herramienta exactamente, las API de escritura Smart y Classic engraphis_remember y las de Python/servicio aceptan exact_value vinculado a la fuente más su exact_value_type. MCP remember requiere una ocurrencia única; las escrituras de Python/servicio pueden seleccionar una ocurrencia repetida con exact_value_span. Los metadatos de vinculación empaquetados requieren la fuente de memoria completa, preservando condiciones en cualquier idioma. El espacio en blanco límite fuera del valor vinculado puede recortarse. La cobertura retiene un grupo vinculado que no puede caber; el legado mantiene su texto seleccionado pero omite la vinculación incompleta. Las correcciones y revisiones de contenido borran la vinculación anterior cuando el contenido cambia; pasa exact_value para vincular explícitamente el reemplazo, con exact_value_span=[start,end] para una ocurrencia repetida, o clear_exact_value=true para eliminar una vinculación. El contenido sin cambios y las revisiones solo de título preservan las vinculaciones válidas. El historial preserva el registro original. El recorte de respuesta MCP elimina los metadatos de vinculación siempre que se omita su contexto de soporte. Para lecturas bi-temporales, valid_at selecciona lo que era verdadero en una marca de tiempo Unix y known_at selecciona lo que Engraphis había aprendido entonces. as_of sigue siendo un alias de compatibilidad para valid_at; proporcionar ambos solo está permitido cuando coinciden.

Para una afirmación mutable, pasa un subject_key estable y un claim_kind opcional, como subject_key="api.rate_limit", claim_kind="configured_value". La resolución de conflictos sin conexión añade, refuerza, relaciona o reemplaza registros de manera determinista mientras preserva el historial temporal; no necesita un LLM. Las identidades de afirmación coincidentes le permiten reemplazar hechos mutables sustancialmente reformulados. Sin ellas, el incrustador léxico sin dependencias no puede inferir de manera fiable que una paráfrasis es una contradicción, así que conserva ambos registros o usa una operación explícita de correct.

Gobernar memorias sin perder historial

Engraphis separa la resolución automática de escrituras de la gobernanza humana explícita:

La fusión manual N→1 está disponible a través de MemoryService.merge() y POST /api/merge:

a = mem.remember("Deploys happen Friday at 3pm.", workspace="acme")
b = mem.remember("We deploy Fridays around 15:00.", workspace="acme")

merged = mem.merge(
    [a["id"], b["id"]],
    "Deploys ship every Friday at approximately 15:00.",
    workspace="acme",
    reason="deduplicate the deployment schedule",
)
print(merged["compaction"])

retire no es intencionadamente una eliminación: preserva el historial temporal, FTS y evidencia vectorial para lecturas históricas. Si se capturó una credencial, las nuevas escrituras se bloquean antes del almacenamiento; para una fuga heredada usa el MemoryService.secure_erase() explícitamente destructivo o POST /api/secure-erase/engraphis_secure_erase. Ese flujo elimina la memoria y las filas locales de FTS/índice vectorial y de grafo/enlaces derivados, ejecuta el borrado seguro de SQLite, el checkpoint WAL y VACUUM, y escanea las copias de seguridad locales reconocidas de recuperación de SQLite. No puede borrar exportaciones, instantáneas del sistema de archivos, pares remotos, copias de seguridad desconocidas o información que un agente en ejecución/comprometido ya haya leído; rota la credencial. Consulta límites de borrado seguro. forget sigue siendo un alias de compatibilidad obsoleto para retire.

Todas las fuentes deben pertenecer al espacio de trabajo nombrado. El resultado hereda la sensibilidad de fuente más estricta, permanece no confiable si alguna fuente no era confiable y permanece fijado si alguna fuente estaba fijada. La cadena completa de múltiples predecesores permanece visible a través de inspección, Why y Timeline.

Gratis para siempre vs. planes alojados

El motor principal, el panel local, el servidor MCP y la consolidación manual son Apache-2.0 y gratuitos. Pro y Team son servicios que proporcionan acceso opcional al servicio alojado oficial; sus módulos de plano de control, facturación, retransmisión, cómputo e identidad de Team viven en un repositorio privado. No limitan el núcleo local. Consulta planes alojados, licencias y Cloud Sync para límites de servicio, ciclo de vida y precios.

Suscríbete a Pro para apoyar el proyecto y añadir servicios alojados.

Compara planes alojados cuando estés listo para evaluar el límite de servicio y las opciones de facturación.

Herramientas MCP

Engraphis expone una puerta de enlace Smart MCP de configuración cero más un servidor de compatibilidad Clásico de 39 herramientas en memoria, recuerdo, grafos de código, gobernanza, sesiones y recibos de auditoría seguros para la privacidad. La referencia de herramientas MCP enfocada es la fuente para el inventario completo y los parámetros.

engraphis_decide proporciona decisiones tipadas de asesoría en MCP Clásico; Smart MCP expone la misma acción de decisión a través de descubrimiento y engraphis_execute_action. Las decisiones permanecen locales por defecto. Para usar la asignación incluida de Pro o Team cuando el servicio en la nube la habilita, conecta tu instalación a través del flujo de cuenta en la nube ordinario y establece ENGRAPHIS_DECISION_BACKEND=managed. El portal de cuenta informa disponibilidad y uso. Para una clave personal TypeSafe, selecciona explícitamente byok y proporciona TYPESAFE_API_KEY a través de la configuración confiable a continuación; pueden aplicarse cargos directos del proveedor.

Cada llamada remota también requiere los booleanos literales allow_remote=true y data_classification="public" o "internal" para el texto proporcionado. offline_mode=true previene solicitudes remotas. Las comprobaciones de comandos siempre devuelven allow_auto=false, incluidos los resultados remotos. Las decisiones siguen siendo de asesoría y no autorizan ejecución ni cambios de memoria. Consulta los detalles del plan Jev y consentimiento.

Grafos y recibos seguros para la privacidad

Las relaciones de memoria, entidad y código viven en un solo grafo local. Engraphis también proporciona recibos de operación sin contenido para evidencia de auditoría inspeccionable. Consulta la arquitectura, la referencia de herramientas MCP y la política de seguridad para el modelo de datos, herramientas y garantías.

Sincronización en la nube

Cloud Sync es un servicio alojado opcional de Pro/Team. El paquete público incluye el cliente y la implementación de fusión determinista; el retransmisor alojado y las operaciones de cuenta son separados. Consulta Cloud Sync para configuración, cifrado, comportamiento de fusión e intercambio de carpetas local.

El paquete público incluye el mismo cliente de sincronización como script de consola y verbo CLI: engraphis-sync (punto de entrada instalado), engraphis sync ... y python -m scripts.sync --status para estado solo local sin actividad de red. Consulta Cloud Sync para banderas, cifrado, comportamiento de fusión e intercambio de carpetas local.

Límites de seguridad y confianza

Engraphis es local-primero y se vincula a loopback por defecto. Lee la política de seguridad antes del despliegue remoto o de integrar recursos externos; cubre versiones compatibles, protecciones de datos, modelo de amenazas e informes de vulnerabilidades.

Cifrado en reposo

Establece ENGRAPHIS_DB_KEY (o ENGRAPHIS_DB_KEY_FILE) e instala el extra:

pip install "engraphis[encryption]"

Todo el archivo de base de datos de memoria principal se cifra de forma transparente con AES-256 mediante SQLCipher; la búsqueda de texto completo, el grafo y cada consulta siguen funcionando sin cambios. La autenticación del cliente y el estado del servicio gestionado usan sus respectivas protecciones de despliegue. Cuando se establece una clave para la base de datos principal, Engraphis falla cerrado con un error en lugar de volver silenciosamente a texto plano. Genera una clave fuerte:

python -c "import secrets; print(secrets.token_hex(32))"

Al usar ENGRAPHIS_DB_KEY_FILE, provisiona un archivo secreto regular legible solo por la identidad del servicio. Engraphis rechaza enlaces, puntos de reanálisis, enlaces duros, texto malformado y archivos de clave sobredimensionados en lugar de seguir un objeto del sistema de archivos inesperado.

Una base de datos de texto plano existente no se puede abrir con una clave: migrarla (volcado → importación en una base de datos nueva con clave). Consulta .env.example para todas las opciones de cifrado.

Importar archivos y carpetas

El núcleo universal sin dependencias escanea Markdown, texto plano, RST, HTML, JSON/JSONL, CSV/TSV, texto de configuración/XML, código fuente, RTF, DOCX/ODT, XLSX/ODS, PPTX/ODP y EPUB en la ruta normal de memoria v2. Los adaptadores de recursos locales instalados añaden texto PDF, OCR de imágenes y transcripción de audio/vídeo explícitamente con modelos locales. Comienza con una vista previa de cero escrituras, luego confirma la misma colección de fuentes explícitamente:

engraphis import documents /path/to/collection --workspace acme --dry-run
engraphis import documents /path/to/collection --workspace acme --repo product --yes

El CLI nunca descarga un modelo de incrustación durante la importación. Usa un modelo que ya esté en caché, establece ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path o establece explícitamente ENGRAPHIS_EMBED_MODEL a un valor vacío para usar hashing determinista sin dependencias en modo degradado léxico.

El flujo Importar documentos locales del panel ofrece la misma vista previa, alcance objetivo, etiqueta de fuente, política de conflictos, cancelación y progreso reanudable. Las reimportaciones son idempotentes, preservan el historial temporal e informan eliminaciones de fuentes sin borrar memorias de forma permanente. Obsidian sigue siendo el adaptador Markdown enriquecido para frontmatter, alias, wikilinks y referencias de adjuntos:

engraphis import obsidian /path/to/vault --workspace acme --dry-run

Consulta la guía de importación de documentos para formatos compatibles, seguridad de fuentes, comportamiento de reanudación y conflictos, adaptadores opcionales y limitaciones; consulta la guía del adaptador Obsidian para el comportamiento específico de Markdown.

Consolidación y automatización

La consolidación manual es gratuita, local y de simulación por defecto; usa el panel, SDK, CLI o MCP. La automatización alojada de Pro y Team es cómputo gestionado opcional que produce propuestas revisables en lugar de cambiar datos locales silenciosamente. Consulta planes alojados, licencias y la referencia de herramientas MCP para alcance y uso.

Configuración

Los valores provienen del entorno del proceso. Engraphis también carga el ~/.engraphis/config.env privado del propietario; ENGRAPHIS_ENV_FILE puede seleccionar otro archivo regular privado del propietario con ruta absoluta. Nunca busca en el directorio de trabajo .env, y las variables de proceso explícitas ganan.

El reranker cross-encoder opcional depende del modelo y del hardware. Trate su calidad y latencia como específicas de la implementación hasta que una identidad de modelo versionada, una configuración exacta y un artefacto de evaluación reproducible estén disponibles para la comparación que se informa.

Consulte .env.example para el inventario completo de variables. Proporcione esos valores a través del entorno del proceso o del archivo de configuración de confianza anterior; copiarlo a un ./.env arbitrario no hace que Engraphis lo cargue.

Fixture de ablación: python -m eval.ablation es una verificación determinista sin conexión que imprime comparaciones de recall@5 para recuperación solo vectorial e híbrida, brazos de grafo de múltiples saltos y políticas de recuperación, además de verificaciones de edad de recuperación ordinaria y confianza semántica. No produce resultados de MRR, hit@5 o ms/consulta. Use python -m eval.reinforcement para trayectorias de retención y registre evidencia antes de citar cualquier resultado de referencia.

Estructura del proyecto

engraphis/
├── engraphis/
│   ├── core/                # v2 engine: interfaces, store, recall, scoring, schema, sync
│   ├── backends/            # pluggable embedder / vector index / reranker / codegraph / sync transports / encryption
│   ├── factory.py           # outer v2 composition root; selects and injects concrete backends
│   ├── service.py           # validated MemoryService facade
│   ├── mcp_server.py        # Smart MCP gateway + 39-tool Classic compatibility server
│   ├── dashboard_app.py     # dashboard WebUI (FastAPI)
│   ├── dashboard_assets/    # primary Ledger interface + graph engine
│   ├── classic_assets/      # selectable full operator dashboard backup
│   ├── read_only_api.py     # token-protected recall/repository-graph HTTP surface
│   ├── hosted_client.py     # hosted URLs, plan labels, and endpoint validation only
│   ├── licensing.py         # compatibility facade for hosted presentation metadata
│   ├── cloud_session.py     # rotating hosted customer-session client
│   ├── cloud_features.py    # consented managed-feature protocol client
│   ├── config.py / app.py   # env settings / REST server
│   └── static/              # compatibility dashboard asset paths
├── eval/                    # offline retrieval eval harness + datasets
├── tests/                   # offline-first pytest suite and release/security contracts
├── scripts/                 # dashboard, server, graph, CLI, connect, update, consolidation, sync
├── docs/                    # product, API, hosting, sync, and provider guides
├── Dockerfile / docker-compose.yml
└── pyproject.toml

La nueva capacidad pertenece a la ruta v2 (engraphis/core/, engraphis/backends/ y MemoryService) detrás de las interfaces en core/interfaces.py. Los módulos de algoritmos en core/ permanecen agnósticos al backend; engraphis/factory.py es la raíz de composición externa utilizada por engraphis.create_memory_engine() y el punto de entrada de compatibilidad MemoryEngine.create(), luego inyecta los colaboradores seleccionados en core/engine.py. El servidor v1 de espacio de nombres plano bajo engraphis/app.py, routes/, stores/ y engines/ permanece como una superficie de compatibilidad/referencia; engraphis-dashboard, el servidor MCP y el inicio rápido de Python anterior usan v2.

Licencia

Apache-2.0. Consulte LICENSE y NOTICE. "Engraphis" es una marca comercial del proyecto Engraphis; la licencia no otorga derechos de marca comercial. El código ya distribuido bajo Apache-2.0 conserva esa concesión; las versiones posteriores no pueden retirarla retroactivamente. El plano de control alojado oficial, sus credenciales y registros de producción, las operaciones administradas, el soporte y los módulos comerciales entregados por separado en el futuro están fuera de la concesión de código fuente público. Consulte docs/LICENSING.md para el límite completo.

Candidato de implementación de confiabilidad

El código fuente actual usa el esquema 18 para la reparación duradera del índice vectorial sin contenido y recibos atómicos de comandos de memoria. Las actualizaciones usan la ruta de migración de respaldo verificado existente. El registro de ejecución de rework registra los hallazgos actuales, decisiones de compatibilidad, evidencia de aceptación, trabajo restante y procedimiento de recuperación. Consulte el programa de confiabilidad para la implementación exacta, validación, migración y límites de lanzamiento. El procesamiento administrado ahora requiere aprobación explícita del espacio de trabajo en Configuración. Las instalaciones existentes comienzan con cargas legibles en pausa hasta que se confirme; conectar una cuenta no otorga aprobación.

Para diagnósticos de configuración use engraphis-init --check --json. Las nuevas configuraciones obtienen un token de API local privado del propietario. Las configuraciones existentes se conservan. Registre las capacidades de instalación seleccionadas con engraphis-init --extras server,mcp o --extras none; las actualizaciones futuras conservan esa elección. ENGRAPHIS_UPDATE_EXTRAS sigue siendo una anulación explícita.