diff --git a/.env.example b/.env.example index 6682104..d9eee0f 100644 --- a/.env.example +++ b/.env.example @@ -13,8 +13,9 @@ GRAPH_BACKEND=sqlite # ENGRAMA_DB_PATH=~/.engrama/engrama.db # default; uncomment to override -# === Profile (used by `engrama init`) === -ENGRAMA_PROFILE=developer +# === Profile === +# The schema profile is selected with the `--profile` flag at init time +# (e.g. `engrama init --profile developer`), not via an env var. # === Obsidian vault sync (optional) === # Required for engrama_sync_note / engrama_sync_vault / @@ -46,11 +47,16 @@ OLLAMA_URL=http://localhost:11434 # OPENAI_BASE_URL=https://api.openai.com/v1 # OPENAI_API_KEY= -# === Hybrid search (DDR-003 Phase C) === -# Alpha controls fulltext vs vector weight (0.0 = all fulltext, 1.0 = all vector) -HYBRID_ALPHA=0.6 -# Beta is the graph topology boost weight -HYBRID_GRAPH_BETA=0.15 +# === Hybrid search ranking (DDR-003 Phase C, Spec 002) === +# Relevance base: rrf (default) or linear (legacy blend). +# ENGRAMA_FUSION_MODE=rrf +# RRF constant k — larger flattens the top-rank advantage. +# ENGRAMA_RRF_K=60 +# Graph node-distance rerank stage (rrf mode) and its hop budget. +# ENGRAMA_GRAPH_RERANK=true +# ENGRAMA_GRAPH_HOPS=2 +# One-flag revert to the legacy linear blend. +# ENGRAMA_RANKING_LEGACY=false # ============================================================ diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 8cae1af..b7c9ad0 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -54,8 +54,8 @@ body: label: Steps to reproduce description: Minimal commands or code that trigger the bug. Smaller is better. placeholder: | - 1. `engrama init` - 2. `engrama remember "..."` + 1. `engrama init --profile developer` + 2. `engrama search "..."` 3. Observed: ... validations: required: true diff --git a/README.md b/README.md index 4d0e468..a7b5b7c 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ sensitive data. The full policy lives in change the default password and enable TLS before any networked use. - **Embedding providers.** Endpoints reached via `OPENAI_BASE_URL` should use HTTPS unless they are on localhost or a trusted network. With - `EMBEDDING_PROVIDER=null` no text is sent anywhere; search degrades to + `EMBEDDING_PROVIDER=none` no text is sent anywhere; search degrades to fulltext-only. - **Tenant isolation.** Since 0.13.0 every node and relation is owned by an `(org_id, user_id)` identity and reads are **fail-closed**. A single diff --git a/docs/architecture.es.md b/docs/architecture.es.md index 28020c8..31ed186 100644 --- a/docs/architecture.es.md +++ b/docs/architecture.es.md @@ -608,7 +608,7 @@ correspondiente. Toda la lógica de almacenamiento reside en `*AsyncStore`; los handlers de herramientas MCP se encargan solo de orquestación, validación, E/S del vault y formateo de respuestas. -Trece herramientas: +Catorce herramientas: - `engrama_status` — introspección de solo lectura: ruta del vault, backend, embedder, modo de búsqueda, versión y `admin_tools` (las @@ -638,6 +638,9 @@ Trece herramientas: - `engrama_approve_insight` — el humano aprueba o descarta un Insight - `engrama_write_insight_to_vault` — añadir Insight aprobado a una nota de Obsidian +- `engrama_gdpr_forget` — borrar permanentemente la memoria del propio + llamante (derecho de supresión RGPD); `mode='dry-run'` previsualiza, + `mode='apply'` elimina ### Forma de respuesta de `engrama_status` @@ -647,7 +650,7 @@ agente puede hacer `if "path" in payload["vault"]:` de forma fiable. ```json { - "version": "0.13.0", + "version": "0.15.0", "backend": { "name": "sqlite", "ok": true, @@ -726,7 +729,6 @@ genera módulos personalizados mediante una entrevista conversacional. | `NEO4J_USERNAME` | `neo4j` | Nombre de usuario de Neo4j | | `NEO4J_PASSWORD` | — | Contraseña de Neo4j (requerida cuando `GRAPH_BACKEND=neo4j`) | | `NEO4J_DATABASE` | `neo4j` | Nombre de la base de datos Neo4j | -| `ENGRAMA_PROFILE` | `developer` | Nombre de perfil para la generación del esquema | | `VAULT_PATH` | `~/Documents/vault` | Ruta raíz del vault de Obsidian | | `EMBEDDING_PROVIDER` | `none` | `none`, `ollama` u `openai` | | `EMBEDDING_MODEL` | `nomic-embed-text` | Nombre del modelo de embedding | @@ -734,8 +736,11 @@ genera módulos personalizados mediante una entrevista conversacional. | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | Endpoint OpenAI-compatible | | `OPENAI_API_KEY` | — | Clave API (cuando sea necesaria) | | `OLLAMA_URL` | `http://localhost:11434` | Endpoint de la API de Ollama (proveedor legacy) | -| `HYBRID_ALPHA` | `0.6` | Peso vectorial vs fulltext | -| `HYBRID_GRAPH_BETA` | `0.15` | Peso del boost por topología del grafo | +| `ENGRAMA_FUSION_MODE` | `rrf` | Base de relevancia: `rrf` (por defecto) o `linear` (mezcla legacy) | +| `ENGRAMA_RRF_K` | `60` | Constante `k` de RRF — mayor aplana la ventaja del primer rango | +| `ENGRAMA_GRAPH_RERANK` | `true` | Activa la etapa de rerank por distancia en el grafo (modo rrf) | +| `ENGRAMA_GRAPH_HOPS` | `2` | Saltos máximos para cohesión + distancia al ancla | +| `ENGRAMA_RANKING_LEGACY` | `false` | Revierte con un flag a la mezcla lineal legacy | | `ENGRAMA_ORG_ID` | — | Org propietaria en standalone (Spec 001); sin fijar → identidad standalone derivada | | `ENGRAMA_USER_ID` | — | Usuario propietario en standalone (Spec 001); sin fijar → identidad standalone derivada | | `ENGRAMA_LOCAL_SUB` | — | Semilla de la identidad standalone derivada cuando org/user no están fijados | diff --git a/docs/architecture.md b/docs/architecture.md index 1964846..468732a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -592,7 +592,7 @@ Native MCP server built with FastMCP and the matching async store. All storage logic lives in `*AsyncStore`; the MCP tool handlers handle orchestration, validation, vault I/O, and response formatting only. -Thirteen tools: +Fourteen tools: - `engrama_status` — read-only introspection: vault path, backend, embedder, search mode, version, and `admin_tools` (the not-tenant-isolated @@ -616,6 +616,8 @@ Thirteen tools: - `engrama_surface_insights` — read pending Insights for agent presentation - `engrama_approve_insight` — human approves or dismisses an Insight - `engrama_write_insight_to_vault` — append approved Insight to Obsidian note +- `engrama_gdpr_forget` — permanently erase the caller's own memory + (GDPR right-to-erasure); `mode='dry-run'` previews, `mode='apply'` deletes ### `engrama_status` response shape @@ -625,7 +627,7 @@ payload["vault"]:` reliably. ```json { - "version": "0.13.0", + "version": "0.15.0", "backend": { "name": "sqlite", "ok": true, @@ -702,7 +704,6 @@ through a conversational interview. | `NEO4J_USERNAME` | `neo4j` | Neo4j username | | `NEO4J_PASSWORD` | — | Neo4j password (required when `GRAPH_BACKEND=neo4j`) | | `NEO4J_DATABASE` | `neo4j` | Neo4j database name | -| `ENGRAMA_PROFILE` | `developer` | Profile name for schema generation | | `VAULT_PATH` | `~/Documents/vault` | Obsidian vault root path | | `EMBEDDING_PROVIDER` | `none` | `none`, `ollama`, or `openai` | | `EMBEDDING_MODEL` | `nomic-embed-text` | Embedding model name | @@ -710,8 +711,11 @@ through a conversational interview. | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compat endpoint | | `OPENAI_API_KEY` | — | API key (when needed) | | `OLLAMA_URL` | `http://localhost:11434` | Ollama API endpoint (legacy provider) | -| `HYBRID_ALPHA` | `0.6` | Vector vs fulltext weight | -| `HYBRID_GRAPH_BETA` | `0.15` | Graph topology boost weight | +| `ENGRAMA_FUSION_MODE` | `rrf` | Relevance base: `rrf` (default) or `linear` (legacy blend) | +| `ENGRAMA_RRF_K` | `60` | RRF constant `k` — larger flattens the top-rank advantage | +| `ENGRAMA_GRAPH_RERANK` | `true` | Toggle the graph node-distance rerank stage (rrf mode) | +| `ENGRAMA_GRAPH_HOPS` | `2` | Max hops for cohesion + anchor distance | +| `ENGRAMA_RANKING_LEGACY` | `false` | One-flag revert to the legacy linear blend | | `ENGRAMA_ORG_ID` | — | Standalone owning org (Spec 001); unset → derived standalone identity | | `ENGRAMA_USER_ID` | — | Standalone owning user (Spec 001); unset → derived standalone identity | | `ENGRAMA_LOCAL_SUB` | — | Seed for the derived standalone identity when org/user are unset | diff --git a/docs/backends.es.md b/docs/backends.es.md index 41367ab..e5716b1 100644 --- a/docs/backends.es.md +++ b/docs/backends.es.md @@ -61,9 +61,7 @@ En la práctica, la primera rama cubre ~90 % de los usuarios. ## Cuándo elegir SQLite - **Estás empezando.** Cero fricción de instalación, sin Docker, sin JVM. - `git clone … && uv sync && uv run engrama init` y ya puedes consultar - el grafo (Engrama aún no está en PyPI; instalación desde fuente por - ahora). + `pip install engrama && engrama init` y ya puedes consultar el grafo. - **Configuraciones de un solo agente.** Un Claude Desktop, un cliente MCP, un script de larga ejecución. SQLite lo gestiona perfectamente. - **Ejecuciones en CI y tests.** Sin servicios externos que levantar — @@ -156,7 +154,7 @@ Los skills, el servidor MCP, la CLI y el SDK de Python están escritos contra los protocolos — no saben qué backend hay debajo. Por eso el cambio se reduce a una sola variable. -Consulta [architecture.md](architecture.md#capa-de-protocolo-y-backends) +Consulta [architecture.md](architecture.md#capa-de-protocolos-y-backends) para el diagrama completo de capas, y [DDR-004](ddr-004.md) para la justificación de diseño del backend portable. @@ -170,7 +168,7 @@ Diferentes procesos pueden apuntar a backends distintos — útil para pruebas o migraciones. **¿SQLite soporta todas las características de Neo4j?** -Para la API pública de Engrama (las 12 herramientas MCP, el SDK, la +Para la API pública de Engrama (las 14 herramientas MCP, el SDK, la CLI), sí — son funcionalmente equivalentes y se prueban con la misma suite de tests de contrato parametrizados. Lo único que SQLite no puede hacer es ejecutar patrones Cypher en crudo; en su lugar usa consultas diff --git a/docs/backends.md b/docs/backends.md index ac8e192..906bf6d 100644 --- a/docs/backends.md +++ b/docs/backends.md @@ -61,8 +61,7 @@ In practice the first branch covers ~90% of users. ## When to pick SQLite - **You're getting started.** Zero install friction, no Docker, no JVM. - `git clone … && uv sync && uv run engrama init` and you're querying - the graph (Engrama is not yet on PyPI; install from source for now). + `pip install engrama && engrama init` and you're querying the graph. - **Single-agent setups.** One Claude Desktop, one MCP client, one long-running script. SQLite handles this perfectly. - **CI runs and tests.** No external service to spin up — `pytest` works @@ -164,7 +163,7 @@ You can, but a single Engrama process binds to one. Different processes can target different backends — useful for testing or migrations. **Does SQLite support all the features Neo4j has?** -For the public Engrama API (the 12 MCP tools, the SDK, the CLI), yes — +For the public Engrama API (the 14 MCP tools, the SDK, the CLI), yes — they're feature-equivalent and exercised by the same parameterised contract suite. The only thing SQLite cannot do is execute raw Cypher patterns; it uses pre-translated SQL queries instead. If a future diff --git a/docs/ddr-003.es.md b/docs/ddr-003.es.md index 5635f05..102db97 100644 --- a/docs/ddr-003.es.md +++ b/docs/ddr-003.es.md @@ -243,7 +243,7 @@ VECTOR_BACKEND=neo4j # neo4j | chroma | pgvector | none # Neo4j (when GRAPH_BACKEND=neo4j or VECTOR_BACKEND=neo4j) NEO4J_URI=bolt://localhost:7687 -NEO4J_USER=neo4j +NEO4J_USERNAME=neo4j NEO4J_PASSWORD=changeme # ChromaDB (when VECTOR_BACKEND=chroma) @@ -748,7 +748,7 @@ VECTOR_BACKEND=neo4j # === Neo4j === NEO4J_URI=bolt://localhost:7687 -NEO4J_USER=neo4j +NEO4J_USERNAME=neo4j NEO4J_PASSWORD=CHANGE_ME_BEFORE_FIRST_RUN # === Embeddings === diff --git a/docs/ddr-003.md b/docs/ddr-003.md index a1c5e9e..aa69534 100644 --- a/docs/ddr-003.md +++ b/docs/ddr-003.md @@ -238,7 +238,7 @@ VECTOR_BACKEND=neo4j # neo4j | chroma | pgvector | none # Neo4j (when GRAPH_BACKEND=neo4j or VECTOR_BACKEND=neo4j) NEO4J_URI=bolt://localhost:7687 -NEO4J_USER=neo4j +NEO4J_USERNAME=neo4j NEO4J_PASSWORD=changeme # ChromaDB (when VECTOR_BACKEND=chroma) @@ -733,7 +733,7 @@ VECTOR_BACKEND=neo4j # === Neo4j === NEO4J_URI=bolt://localhost:7687 -NEO4J_USER=neo4j +NEO4J_USERNAME=neo4j NEO4J_PASSWORD=CHANGE_ME_BEFORE_FIRST_RUN # === Embeddings === diff --git a/docs/index.es.md b/docs/index.es.md index 66491b3..53e2b7f 100644 --- a/docs/index.es.md +++ b/docs/index.es.md @@ -19,8 +19,7 @@ conocimiento acumulado. Hay dos backends de primera clase: - **SQLite + `sqlite-vec`** (por defecto desde la 0.9) — un único - archivo, sin servicios externos, `git clone` + `uv sync` y a - correr (Engrama aún no está en PyPI; instalación desde fuente). + archivo, sin servicios externos, `pip install engrama` y a correr. - **Neo4j 5.26 LTS** (opcional) — para producción multiproceso, índices vectoriales muy grandes o equipos que ya usan Cypher. @@ -541,7 +540,7 @@ coincidencia exacta de palabras clave. **Cómo activar la búsqueda híbrida:** 1. Establece `EMBEDDING_PROVIDER` en `.env` (ver - [Configuración de embeddings](#configuración-de-embeddings-opcional)). + [Configuración de embeddings](#configuracion-de-embeddings-opcional)). 2. Ejecuta `uv run engrama reindex` para generar embeddings de nodos existentes. 3. Los nodos nuevos reciben embeddings automáticamente al crearse. @@ -570,7 +569,7 @@ Valores por defecto: `β` (grafo) = 0.15, `γ` (temporal) = 0.1, RRF `k` = 60, saltos de grafo = 2, decaimiento de cohesión = 0.5. La mezcla lineal heredada (con el `graph_boost` por grado) se conserva para revertir con un solo flag vía `ENGRAMA_RANKING_LEGACY=1`. Consulta la [referencia de -configuración](#referencia-de-configuración) para todos los knobs. +configuración](#referencia-de-configuracion) para todos los knobs. --- @@ -699,7 +698,6 @@ freelance. | `NEO4J_USERNAME` | `neo4j` | Usuario Neo4j | | `NEO4J_PASSWORD` | — | Contraseña Neo4j (requerida con `GRAPH_BACKEND=neo4j`) | | `NEO4J_DATABASE` | `neo4j` | Nombre de base de datos Neo4j | -| `ENGRAMA_PROFILE` | `developer` | Perfil para generar el esquema | | `VAULT_PATH` | `~/Documents/vault` | Raíz del vault de Obsidian | | `EMBEDDING_PROVIDER` | `none` | `none`, `ollama` u `openai` | | `EMBEDDING_MODEL` | `nomic-embed-text` | Nombre del modelo | diff --git a/docs/index.md b/docs/index.md index 7654a2a..fe44263 100644 --- a/docs/index.md +++ b/docs/index.md @@ -128,7 +128,7 @@ Expected output: `backend=sqlite, ok=true, ...` Three ways: -**A) From Claude Desktop** — see [MCP integration](#mcp-integration-claude-desktop) below. +**A) From Claude Desktop or Codex** — see [MCP integration](#mcp-integration) below. **B) From Python:** @@ -356,12 +356,14 @@ context. For shorter inputs and tighter latency, use --- -## MCP integration (Claude Desktop) +## MCP integration Engrama acts as an abstraction layer between the AI agent and the -storage backend. Claude Desktop connects to the Engrama MCP server — it +storage backend. The MCP client connects to the Engrama MCP server — it never sees database credentials, connection strings, or raw queries. +### Claude Desktop + **1. Find your Claude Desktop config file:** - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` @@ -403,6 +405,43 @@ the server reads them from `.env` when running against Neo4j. **3. Restart Claude Desktop** completely (quit and reopen). +### Codex + +Codex supports local MCP servers over `stdio`, so you can register +Engrama straight from the CLI: + +```bash +codex mcp add engrama -- uv run --directory C:\Proyectos\engrama --extra mcp engrama-mcp --backend sqlite +``` + +For Neo4j, swap `--backend sqlite` for `--backend neo4j` and add the +extra too: + +```bash +codex mcp add engrama -- uv run --directory C:\Proyectos\engrama --extra mcp --extra neo4j engrama-mcp --backend neo4j +``` + +Then confirm it registered: + +```bash +codex mcp list +``` + +As with Claude Desktop, change `C:\Proyectos\engrama` to the actual path +where you cloned the repo. + +### ChatGPT Desktop + +ChatGPT does **not** use this local `stdio` configuration directly. +OpenAI's current docs describe ChatGPT's custom MCP connectors as +**remote** MCP servers imported from `Settings -> Connectors`, over +HTTP/SSE rather than a local command. + +That means `engrama-mcp` fits Claude Desktop and Codex well, but **not +yet** as a direct ChatGPT Desktop integration. To use Engrama from +ChatGPT you would expose a remote MCP endpoint and package it as a +custom ChatGPT connector. + You should now see the fourteen Engrama tools: | Tool | Description | @@ -733,7 +772,6 @@ creative. | `NEO4J_USERNAME` | `neo4j` | Neo4j user | | `NEO4J_PASSWORD` | — | Neo4j password (required when `GRAPH_BACKEND=neo4j`) | | `NEO4J_DATABASE` | `neo4j` | Neo4j database name | -| `ENGRAMA_PROFILE` | `developer` | Profile for schema generation | | `VAULT_PATH` | `~/Documents/vault` | Obsidian vault root path | | `EMBEDDING_PROVIDER` | `none` | `none`, `ollama`, or `openai` | | `EMBEDDING_MODEL` | `nomic-embed-text` | Model name | diff --git a/docs/roadmap.es.md b/docs/roadmap.es.md index 9e47fdf..f8eee9c 100644 --- a/docs/roadmap.es.md +++ b/docs/roadmap.es.md @@ -28,7 +28,7 @@ > Objetivo: usar el grafo desde Claude Desktop vía MCP sin escribir Cypher manualmente. - [x] `engrama/adapters/mcp/server.py` — servidor MCP nativo vía FastMCP + driver asíncrono de Neo4j -- [x] Diez herramientas MCP: search, remember, relate, context, sync_note, sync_vault, reflect, surface_insights, approve_insight, write_insight_to_vault (el conjunto ha crecido desde entonces a doce — `engrama_ingest` llegó en la Fase 9 y `engrama_status` en #52; véase architecture.md para la lista actual) +- [x] Diez herramientas MCP: search, remember, relate, context, sync_note, sync_vault, reflect, surface_insights, approve_insight, write_insight_to_vault (el conjunto ha crecido desde entonces a catorce — `engrama_ingest` llegó en la Fase 9, `engrama_status` en #52, y `engrama_reindex` / `engrama_gdpr_forget` después; véase architecture.md para la lista actual) - [x] `examples/claude_desktop/config.json` — configuración lista para copiar y pegar - [x] `examples/claude_desktop/system-prompt.md` — system prompt de memoria - [ ] Test extremo a extremo: Claude Desktop → MCP → Neo4j → respuesta (verificación manual hecha, test automatizado pendiente) diff --git a/docs/roadmap.md b/docs/roadmap.md index 37172d5..2150ba5 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -28,7 +28,7 @@ > Goal: use the graph from Claude Desktop via MCP without writing Cypher manually. - [x] `engrama/adapters/mcp/server.py` — native MCP server via FastMCP + async Neo4j driver -- [x] Ten MCP tools: search, remember, relate, context, sync_note, sync_vault, reflect, surface_insights, approve_insight, write_insight_to_vault (the set has since grown to twelve — `engrama_ingest` landed in Phase 9 and `engrama_status` in #52; see architecture.md for the current list) +- [x] Ten MCP tools: search, remember, relate, context, sync_note, sync_vault, reflect, surface_insights, approve_insight, write_insight_to_vault (the set has since grown to fourteen — `engrama_ingest` landed in Phase 9, `engrama_status` in #52, and `engrama_reindex` / `engrama_gdpr_forget` later; see architecture.md for the current list) - [x] `examples/claude_desktop/config.json` — ready-to-paste config - [x] `examples/claude_desktop/system-prompt.md` — memory system prompt - [ ] End-to-end test: Claude Desktop → MCP → Neo4j → response (manual verification done, automated test pending) diff --git a/docs/vision.es.md b/docs/vision.es.md index ece079b..a652c82 100644 --- a/docs/vision.es.md +++ b/docs/vision.es.md @@ -10,7 +10,7 @@ Karpathy construyó su segundo cerebro en Markdown y wikis — eso funciona para **Engrama** es un framework Python plug-and-play que proporciona a cualquier agente de IA una memoria persistente y estructurada respaldada por un grafo de conocimiento. El agente puede recordar, asociar, olvidar y razonar sobre el conocimiento acumulado — exactamente como lo haría un humano con buena memoria. -El grafo funciona sobre **SQLite + sqlite-vec** (por defecto desde la 0.9 — un único archivo, sin servicios externos, `git clone` + `uv sync` y a correr; Engrama aún no está en PyPI) o **Neo4j 5.26 LTS** (opcional para producción multiproceso, índices vectoriales grandes o equipos que ya usan Cypher). Ambos exponen el mismo modelo de datos y las mismas doce herramientas MCP — consulta [backends.md](backends.md) para la guía de elección. +El grafo funciona sobre **SQLite + sqlite-vec** (por defecto desde la 0.9 — un único archivo, sin servicios externos, `pip install engrama` y a correr) o **Neo4j 5.26 LTS** (opcional para producción multiproceso, índices vectoriales grandes o equipos que ya usan Cypher). Ambos exponen el mismo modelo de datos y las mismas catorce herramientas MCP — consulta [backends.md](backends.md) para la guía de elección. ## Qué lo diferencia diff --git a/docs/vision.md b/docs/vision.md index 45a4676..3149f4d 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -10,7 +10,7 @@ Karpathy built his second brain in Markdown and wikis — that works for humans **Engrama** is a plug-and-play Python framework that gives any AI agent persistent, structured memory backed by a knowledge graph. The agent can remember, associate, forget, and reason about its accumulated knowledge — exactly as a human with good memory would. -The graph runs on either **SQLite + sqlite-vec** (default since 0.9 — single file, zero external services, `git clone` + `uv sync` and you're running; Engrama is not yet on PyPI) or **Neo4j 5.26 LTS** (opt-in for multi-process production, large vector indexes, or teams already invested in Cypher). Both expose the same data model and the same twelve MCP tools — see [backends.md](backends.md) for the decision guide. +The graph runs on either **SQLite + sqlite-vec** (default since 0.9 — single file, zero external services, `pip install engrama` and you're running) or **Neo4j 5.26 LTS** (opt-in for multi-process production, large vector indexes, or teams already invested in Cypher). Both expose the same data model and the same fourteen MCP tools — see [backends.md](backends.md) for the decision guide. ## What makes it different diff --git a/engrama/adapters/mcp/server.py b/engrama/adapters/mcp/server.py index 649b007..1eb05b2 100644 --- a/engrama/adapters/mcp/server.py +++ b/engrama/adapters/mcp/server.py @@ -1,8 +1,9 @@ """ Engrama MCP server — high-level memory tools for AI agents. -Exposes eleven tools via the Model Context Protocol: +Exposes fourteen tools via the Model Context Protocol: +* **engrama_status** — runtime introspection of the running server. * **engrama_search** — fulltext search across the memory graph. * **engrama_remember** — create or update a node (always MERGE). * **engrama_relate** — create a relationship between two nodes. @@ -14,6 +15,8 @@ * **engrama_surface_insights** — read pending Insights for agent presentation. * **engrama_approve_insight** — human approves or dismisses an Insight. * **engrama_write_insight_to_vault** — append approved Insight to Obsidian note. +* **engrama_reindex** — find and repair nodes missing their vector embedding. +* **engrama_gdpr_forget** — permanently erase the caller's own memory (GDPR). All writes use ``MERGE`` with automatic timestamps. All queries use Cypher parameters — never string formatting. diff --git a/examples/claude_desktop/system-prompt.md b/examples/claude_desktop/system-prompt.md index 5394969..889195b 100644 --- a/examples/claude_desktop/system-prompt.md +++ b/examples/claude_desktop/system-prompt.md @@ -5,7 +5,7 @@ Add this to your Claude Desktop project instructions. --- You have access to a persistent knowledge graph via the **engrama** MCP -server. It provides twelve tools — use them proactively to remember, +server. It provides fourteen tools — use them proactively to remember, retrieve, and reflect on information across sessions. When another Obsidian-capable MCP (e.g. `obsidian-mcp`) is connected in parallel, call `engrama_status` at session start to identify Engrama's own