Engraphy

Memoria asociativa para agentes de IA, modelada según la mente humana.

El nombre proviene de engraphy, un término antiguo de la ciencia de la memoria para el proceso de asentar un engrama, la huella que una memoria deja en el cerebro. Engraphy hace eso por los agentes: comprueba cada nueva memoria contra lo que ya sabe antes de que se realice la escritura, fusionando reformulaciones, enlazando hechos genuinamente nuevos y nunca sobrescribiendo en silencio. Nada se elimina, por lo que el historial sigue siendo recorrible.

Engraphy es autoalojado. Almacena lo que un agente aprende como un grafo de conocimiento tipado en Postgres + pgvector: las escrituras se deduplican contra la memoria existente, la recuperación fusiona la búsqueda semántica y léxica, el aislamiento entre usuarios lo impone la base de datos, y la forma completa de la memoria se declara por aplicación como un pack.

Existe para reemplazar el modelo de JSON plano, de un solo usuario y stdio del servidor de memoria MCP de referencia por algo que sobrevive a la concurrencia, la paráfrasis, los duplicados y años de memoria acumulada. Habla el Model Context Protocol, por lo que cualquier cliente MCP (una extensión de VS Code, una aplicación de escritorio, otro agente) puede usarlo a través de HTTP.

Código fuente disponible. Licenciado bajo la Business Source License 1.1: léela, ejecútala, construye sobre ella y úsala en producción para tu propio producto. Ofrecer Engraphy en sí mismo como un servicio alojado o gestionado a terceros está reservado al Licenciante hasta la Fecha de Cambio, cuando se convierte a Apache-2.0. Ver Licencia.

Qué hace

• Un grafo de memoria tipado. Las memorias son nodos tipados (fact, decision, person, event, …) unidos por aristas tipadas (involves, references, supersedes, …). Los tipos, sus esquemas de atributos y las reglas sobre qué aristas pueden conectar qué tipos se declaran por espacio en un pack y se aplican en Postgres.

• Escrituras que se deduplican solas. Cada escritura se incrusta y se agrupa contra la memoria existente. Una reformulación casi literal se fusiona automáticamente; un hecho genuinamente nuevo pero relacionado se mantiene como su propio nodo buscable y se une mediante una arista (nada se absorbe en silencio); un caso límite se aparca como un veredicto pendiente de comprobación de duplicados para que el llamador lo resuelva. Cada escritura devuelve un informe de resonancia de lo que tocó.

• Recuperación híbrida. search fusiona una rama vectorial (coseno sobre embeddings) y una rama léxica (texto completo de Postgres) con Reciprocal Rank Fusion, y traverse recorre las aristas. Los valores de atributos se integran en la superficie buscable, por lo que un hecho almacenado solo en un atributo tipado sigue siendo localizable.

• Aislamiento que impone la base de datos. Múltiples espacios, y múltiples principales dentro de un espacio, se separan mediante la seguridad a nivel de fila de Postgres que se ejecuta bajo un rol no superusuario, no mediante comprobaciones de aplicación que pueden olvidarse. El servidor se conecta como un rol NOBYPASSRLS.

• Enrutamiento de ámbitos diseñado para LLMs. Cada ámbito lleva una descripción de lo que gobierna; la herramienta de solo lectura scope_guide devuelve ese manifiesto de enrutamiento para que un agente pueda decidir dónde pertenece una nueva memoria antes de escribirla.

• Una CLI de operador y una superficie de herramientas MCP para todo, desde arrancar un espacio hasta acuñar tokens, importar datos, aplicar packs y verificar restauraciones.

Related MCP server: gbrain

Cómo funciona

flowchart LR
    C[MCP client<br/>VS Code · desktop · agent] -->|HTTP + bearer token| S[Engraphy server<br/>FastMCP]
    S --> E[Embedding<br/>nomic-embed-text-v1.5]
    S --> DB[(Postgres 16 + pgvector<br/>nodes · edges · scopes<br/>RLS · schema enforcement)]
    P[Pack<br/>types · edges · briefing] -.declares.-> DB

Una escritura se incrusta, se agrupa por similitud en fusionar / fusionar-enlazar / pendiente / nuevo, y se confirma bajo la identidad del llamador. Una lectura (search, get, traverse, briefing) se ejecuta bajo RLS para que un llamador solo vea los ámbitos que se le concedieron. Un pack declara los tipos de nodo, tipos de arista, esquemas de atributos y el informe de inicio de sesión para un espacio, de modo que un motor sirve a muchas aplicaciones de memoria con formas diferentes. La visión general de la arquitectura recorre las rutas completas de escritura y lectura.

Inicio rápido

Requisitos: Docker (con Compose). El perfil de nube levanta Postgres, ejecuta migraciones, aprovisiona el rol de la aplicación e inicia el servidor con un solo comando.

# 1. Configure secrets (never committed)
cp deploy/.env.example .env   # then edit, or:
printf 'POSTGRES_PASSWORD=%s\nENGRAPHY_APP_ROLE_PASSWORD=%s\n' \
  "$(openssl rand -hex 16)" "$(openssl rand -hex 16)" > .env

# 2. Bring up Postgres + migrate + provision + serve
docker compose up -d          # first boot downloads the ~523 MB embedding model

# 3. Create a space, apply the starter pack, mint a client token
docker compose --profile admin run --rm admin \
  engraphy-admin space create --id personal --display-name "My Memory" --principal me
docker compose --profile admin run --rm admin \
  engraphy-admin pack apply packs/starter/pack.yaml --space personal
docker compose --profile admin run --rm admin \
  engraphy-admin token create --space personal --principal me \
    --client-name my-editor --role readwrite

El servidor está ahora en 127.0.0.1:8000 (pon un proxy inverso que termine TLS delante para exponerlo). Apunta cualquier cliente MCP a él con el token de portador. La guía de configuración también cubre la ruta local sin Docker.

O deja que los scripts lo hagan

up.sh y provision.sh (con up.ps1 / provision.ps1 como equivalentes de Windows) envuelven exactamente la secuencia anterior y añaden la espera que un inicio rápido de copiar y pegar no puede:

./up.sh          # writes .env with random passwords, starts the stack,
                 # then blocks until /healthz returns 200
./provision.sh   # creates the space, applies the starter pack, mints a token,
                 # and prints the client settings to paste in

up.sh consulta /healthz en lugar del estado de salud de compose, porque en el primer arranque compose informa starting durante el tiempo que tarda en sembrarse la caché del modelo, lo que desde fuera parece idéntico a un bucle de caída. Un 200 es la señal real.

Ambos scripts son seguros de volver a ejecutar: un .env existente nunca se sobrescribe, y un espacio existente o un pack ya aplicado se omite en lugar de tratarse como un error, por lo que una re-ejecución sigue acuñando un token nuevo.

Todo está parametrizado, con valores predeterminados que funcionan sin cambios:

El token se imprime una vez y los scripts nunca lo escriben en disco; el servidor almacena solo su SHA-256. Si lo pierdes, vuelve a ejecutar provision.sh para obtener uno nuevo.

Usándolo desde un cliente

Engraphy es un servidor MCP, por lo que un cliente se conecta y llama a herramientas:

Consulta la referencia de herramientas para parámetros, retornos y un ejemplo por herramienta. Una extensión de VS Code de primera parte vive en vscode-extension/.

Documentación

• docs/: documentación para desarrolladores, arquitectura, configuración, packs, referencia de herramientas, despliegue y un tutorial de extremo a extremo.

• design/: el conjunto de diseño, el modelo de datos, la recuperación y deduplicación, la autenticación y el arrendamiento, las operaciones, el sistema de packs/ontología y el banco de pruebas. Aquí es donde vive el razonamiento de ingeniería.

• skills/: orientación concisa que un agente LLM puede cargar para usar Engraphy bien (escritura y deduplicación, recuperación, ámbitos y visibilidad, disciplina de respuesta).

Requisitos

• Postgres 16 con pgvector (la imagen pgvector/pgvector:pg16 incluye ambos).

• Python ≥ 3.12.

• dbmate para migraciones (incluido en el contenedor de administración; solo se necesita en PATH para la ruta sin Docker).

• El modelo de embeddings nomic-ai/nomic-embed-text-v1.5 (384-dim, ~523 MB, descargado y almacenado en caché en el primer arranque).

Estado del proyecto

v0.1.0. El esquema y el núcleo de aplicación, los comportamientos del motor (deduplicación, recuperación híbrida, recorrido de grafos, informes), el servidor MCP con autenticación y administración, y la CLI de operador están implementados y cubiertos por una suite de pruebas con Postgres en vivo más un trabajo de CI que ejercita los artefactos de despliegue incluidos de extremo a extremo. Un banco de pruebas (bench/, design/09) ejecuta el motor contra conjuntos de datos públicos de memoria a largo plazo; es una herramienta para medir cambios, no una fuente de números de marketing.

Licencia

Engraphy está licenciado bajo la Business Source License 1.1 (ver LICENSE).

• Puedes leer, modificar, redistribuir, autoalojar y usar Engraphy en producción como la capa de memoria para tus propias aplicaciones y agentes.

• No puedes ofrecer Engraphy en sí mismo a terceros como un servicio alojado o gestionado antes de la Fecha de Cambio.

• Fecha de Cambio: 2026-08-22 + 4 años (2030-08-22), en la que la licencia se convierte a la Apache License, Version 2.0.

Copyright (c) 2026 Devon Clark.