Cortex

El problema

Tu agente de codificación resuelve un error molesto el martes. El miércoles abre una ventana de contexto nuevo y no tiene ni idea de que ese error haya existido alguna vez. Le vuelves a copiar la misma explicación.

Cortex le da al agente una memoria que el propio agente escribe y lee por sí solo, a través de MCP: memorias estructuradas (bug_fix, decision, discovery, pattern, preference, ...), limitadas por proyecto, ordenadas por relevancia, con decadencia en el tiempo, y que vuelven a aparecer cuando vuelve el mismo síntoma.

Todo vive en un único archivo SQLite en tu máquina (~/.memoria/memoria.db). No hay cuenta, ni API key, ni telemetría.

Related MCP server: exocortex

Qué incluye

• 20 herramientas MCP — save / search / context / recall / hint / feedback / sessions / reflections / forget (lista completa).

• Recuperación híbrida — búsqueda por palabras clave con SQLite FTS5 combinada con KNN vectorial mediante Reciprocal Rank Fusion. Los embeddings son opcionales y se ejecutan localmente (@xenova/transformers, 384-dim MiniLM, ~22 MB, CPU).

• Confianza según resultados — el agente informa si una memoria sugerida ayudó, estaba obsoleta o lo desvió (memoria_feedback); los niveles de confianza reclasifican los resultados futuros.

• Pistas proactivas — memoria_hint toma la próxima llamada de herramienta / prompt / ruta de archivo y devuelve hasta 3 pistas breves para inyectar antes de actuar.

• Reflexiones — un pase de agrupación solo en CPU agrupa memorias relacionadas; el LLM de tu agente sintetiza la meta-lección (Cortex nunca llama a un LLM por sí mismo).

• Decaimiento y olvido — la relevancia decae, memoria_forget muestra una vista previa (sin efectos por defecto) y borra de forma suave el suelo.

• Privacidad por defecto — API keys, PATs, JWTs, claves SSH y bloques <private>...</private> se eliminan antes de escribir nada en el disco.

• Lista para producción — logs JSON estructurados, métricas Prometheus en /api/metrics, cuotas, bearer auth opcional y espacios de trabajo multi-tenant.

Inicio rápido (2 minutos)

Requisitos: Node >= 20 (verificado en 22 y 26) y git. better-sqlite3 se compila o descarga un binario precompilado al instalar; no ninguna otra dependencia del sistema.

git clone https://github.com/gonzalonicolasr/cortexmem.git
cd cortexmem
npm install
npm test          # optional: 216 tests, ~1s

O instálalo sin necesidad de clonar: tienes un comando cortexmem en tu PATH:

npm install -g github:gonzalonicolasr/cortexmem
cortexmem --version

Pruébalo rápidamente como una CLI normal:

node bin/memoria.mjs save "Fix hydration bug" \
  --type bug_fix --what "moved the fetch out of useEffect" \
  --project demo --learned "SSR/CSR mismatch, not a race condition"

node bin/memoria.mjs search hydration --project demo
node bin/memoria.mjs stats

Eso es todo: la base de datos se crea en ~/.memoria/memoria.db en la primera escritura.

Conéctalo a tu agente

Cortex habla MCP por stdio. Si instalaste globalmente, el comando es cortexmem mcp; desde un clon, usa node con la ruta absoluta a bin/memoria.mjs.

claude mcp add cortex -- node /absolute/path/to/cortexmem/bin/memoria.mjs mcp
claude mcp list | grep cortex     # → ✓ Connected

[mcp_servers.cortex]
command = "node"
args = ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]

{
  "mcpServers": {
    "cortex": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/cortexmem/bin/memoria.mjs", "mcp"]
    }
  }
}

Instala una extensión MCP para pi y hazla apuntar al mismo par comando/argumentos que el ejemplo JSON de arriba. Para el transporte HTTP, ver docs/self-hosting.md.

Reinicia el cliente después de editar su configuración: Codex y Claude Code no releen el archivo en caliente.

Enseña al agente a usarlo de verdad

No basta con las herramientas: el agente tiene que saber cuándo escribir. Copia CLAUDE.md (el protocolo de memoria) en el archivo de instrucciones de tu agente (CLAUDE.md, AGENTS.md, .cursorrules, el AGENTS.md de pi, ...). Son ~40 líneas y le dicen al agente que guarde automáticamente después de arreglar bugs, decisiones, descubrimientos y cambios de configuración, y que llame a memoria_context al inicio de la sesión.

CLI

memoria mcp                    Start the MCP server (stdio)
memoria serve [port]           Start the HTTP API (default 7437, loopback-only)
memoria save <title> [flags]   Save a memory
memoria search <query>         Full-text search
memoria context [project]      Print the project context block
memoria recent [flags]         Recent memories
memoria stats                  Counts by type / project
memoria projects               List projects
memoria decay                  Apply relevance decay

Flags: --project --type --limit --what --why --where --learned --topic.

Modo servidor

¿Quieres una única memoria compartida por todas las máquinas / agentes de tu homelab? Ejecuta la API HTTP y ponla detrás de un proxy inverso:

MEMORIA_HOST=127.0.0.1 MEMORIA_AUTH_TOKEN=$(openssl rand -hex 24) \
  node bin/memoria.mjs serve 7437
curl -s localhost:7437/api/health

Referencia de endpoints: docs/http-api.md. Unidad de systemd, autenticación bearer, recarga de embeddings, reflexiones con cron y copias de seguridad: docs/self-hosting.md.

⚠️ El servidor HTTP confía en la cabecera X-Workspace-Id (diseño multi-tenant: un proxy intermedio valida al usuario y la inyecta). No lo expongas nunca en una interfaz pública sin MEMORIA_AUTH_TOKEN + un proxy delante.

Búsqueda semántica (opcional)

npm install @xenova/transformers          # already an optionalDependency
export MEMORIA_SEMANTIC_SEARCH=1
node bin/backfill-embeddings.mjs          # embed existing memories

El modelo se descarga una sola vez (~22 MB) y se ejecuta en la CPU. Con el flag activo, memoria_search y memoria_recall pasan a ser híbridos (FTS5 + KNN fusionados con RRF); sin el flag, todo sigue funcionando como búsqueda por palabras clave. Para memorias en otro idioma: pon MEMORIA_EMBEDDING_MODEL=Xenova/paraphrase-multilingual-MiniLM-L12-v2 antes de la carga retroactiva (mismas 384 dims) — ver búsqueda semántica.

Variables de entorno

Cuotas

Los límites por defecto están pensados para el despliegue multi-tenant: 1 000 memorias activas, 10 MB de texto lógico, 50 proyectos, 5 sesiones activas, 32 KB por memoria. Para una instalación local personal, súbelos:

export MEMORIA_UNLIMITED_WORKSPACES=1   # workspace 1 = the CLI/stdio default

Herramientas MCP

Los nombres de las herramientas mantienen el prefijo memoria_ (el nombre original del proyecto) por compatibilidad con instalaciones existentes.

Datos, privacidad y copias de seguridad

• Un único archivo SQLite (modo WAL). Haz una copia con sqlite3 ~/.memoria/memoria.db ".backup out.db".

• Los secretos se eliminan antes de escribir la fila: claves de AWS, PATs de GitHub/GitLab, claves de OpenAI/Anthropic/Slack/Google/Stripe/Cloudflare, JWTs, claves privadas SSH y todo lo que envuelvas en <private>...</private>. Es una red de seguridad, no una licencia para pegar secretos.

• nada sale de tu máquina a menos que tú ejecutes el servidor HTTP y lo expongas.

Desarrollo

npm test          # vitest, 216 tests
npm run test:watch

Los tests de embeddings multilingües están bloqueados tras MEMORIA_TEST_MULTILINGUAL=1 para que la suite normal nunca descargue un modelo. Registro de Cambios: CHANGELOG.md.

Versión alojada (opcional)

Si prefieres no correr nada, el mismo motor está alojado en cortexmem.com: regístrate, copia la API key cc_... del panel, y apunta tu cliente al endpoint HTTP en lugar del comando local:

claude mcp add cortex https://cortexmem.com/api/cortex/mcp \
  --transport http --header "Authorization: Bearer cc_YOUR_KEY"

# ~/.codex/config.toml
[mcp_servers.cortex]
url = "https://cortexmem.com/api/cortex/mcp"

[mcp_servers.cortex.http_headers]
Authorization = "Bearer cc_YOUR_KEY"

Self-hosting sigue siendo completo — el tier alojado añade la interfaz web y el grafo de asociaciones, no la memoria en sí.

Licencia

MIT © Gonzalo Rocca — ver LICENSE.