memory-mcp

Memoria personal transversal entre herramientas: un archivo episódico consultable de sesiones de IA de todos los dispositivos, además de una capa de hechos semánticos curada y de alta confianza, expuesta a través de un servidor MCP. Diseñado para un servidor arm64 autoalojado y de solo uso mediante WG. Consulta el diseño completo en docs/mcp/memory-mcp-spec.md.

Estructura

Related MCP server: Memorium

Dos capas, dos niveles de confianza

• Archivo episódico (Qdrant memory_archive): cada fragmento (chunk) de cada sesión. Vectores densos (bge-m3, 1024) + dispersos (TF modificado por IDF), búsqueda híbrida fusionada con RRF. Solo se consulta bajo demanda (search_archive).

• Hechos semánticos (Postgres): declaraciones curadas con procedencia. Superficie de lectura por defecto (search_memory). Escritas por remember (fuente user) y por destilación aprobada por humanos (fuente distilled); nada destilado se activa sin memoryctl review.

Superficie MCP

Herramientas: remember, search_memory, search_archive, forget (destructivo, en dos fases por consulta). Recursos: memory://stats, memory://facts/recent, memory://facts/{id}.

Desarrollo

pnpm install
pnpm build        # all packages
pnpm test         # core + server suites (stores are mocked; nothing external touched)
pnpm eval         # golden-set retrieval harness (needs live stores + ingested data)

La configuración se maneja por entorno a través de packages/core/src/config.ts (loadConfig); consulta deploy/.env.example para conocer todas las variables.

Operaciones

cd deploy && cp .env.example .env   # fill in POSTGRES_PASSWORD, STATIC_BEARER, keys
docker compose -f compose.prod.yaml up -d --build
docker compose -f compose.prod.yaml exec memory-mcp memoryctl init
docker compose -f compose.prod.yaml exec memory-mcp memoryctl verify

compose.prod.yaml presupone que Qdrant y una pasarela LLM compatible con OpenAI ya se ejecutan como contenedores externos en tu host; edita los campos name: de la sección networks: para que coincidan con los nombres de tus redes de Docker.

La ingesta y destilación diarias, así como las copias de seguridad nocturnas, son temporizadores de systemd (deploy/systemd/). Las copias de seguridad caducan a los 14 días, de modo que un forget se propaga fuera de las copias de seguridad en ese plazo.

Postura de seguridad

• Enlace solo WG (bind), bearer estático (v1); el JWT de pasarela es un método de autenticación futura planificado (Paso 8), a la espera de una pasarela OIDC/JWT compatible delante del servidor.

• El saneamiento (gitleaks + regex personalizadas) es fail-closed y se ejecuta antes de que cualquier cosa sea incrustada o almacenada. La entrada no analizable pone en cuarentena todo el archivo (registrado en el ledger); los fallos transitorios de infraestructura (embedder, Qdrant o gitleaks no disponibles) revierten limpio, no registran nada y el archivo se reintenta en la siguiente ejecución.

• forget es un borrado permanente en ambos almacenes.

• Los fragmentos del archivo se devuelven dentro de delimitadores de datos no confiables; las transcripciones históricas pueden contener texto similar a instrucciones y deben tratarse como datos.

Consulta SECURITY.md para reportar una vulnerabilidad.

Contribuciones

Las incidencias y los PRs son bienvenidos. Consulta CONTRIBUTING.md para la configuración de desarrollo y las convenciones del proyecto, y CHANGELOG.md para el historial. Este proyecto sigue el Código de Conducta.

Licencia

MIT