linksee-memory

MCP de memoria para agentes con prioridad local. Un cerebro compartido entre agentes para Claude Code, Cursor y ChatGPT Desktop, con una caché de diff de archivos que ahorra tokens, algo que nadie más ofrece.

Qué hace

La mayoría de los servicios de "memoria de agente" (Mem0, Letta, Zep) guardan una lista plana de hechos. Luego, el agente ve "editó el archivo X 30 veces" y no tiene idea de por qué. linksee-memory guarda el PORQUÉ.

Es un servidor de Model Context Protocol (MCP) que otorga a cualquier agente de IA cuatro superpoderes:

Tres pilares

1. Ahorro de tokens mediante read_smart — sha256 + fragmentación por AST/encabezado/sangría. Las relecturas devuelven solo los diffs. Medido un 86% de ahorro en una edición típica de archivo TS, 99% de ahorro en relecturas sin cambios.

2. Portabilidad entre agentes — archivo SQLite único en ~/.linksee-memory/memory.db. El mismo cerebro para Claude Code, Cursor y ChatGPT Desktop.

3. Memoria estructurada basada en el PORQUÉ — seis capas explícitas (objetivo / contexto / emoción / implementación / advertencia / aprendizaje). Resuelve el problema de que "la memoria de hechos plana es inútil sin objetivos".

Instalación

npm install -g linksee-memory
linksee-memory-import --help   # bundled importer for Claude Code session history

O usa npx de forma puntual:

npx linksee-memory             # starts the MCP server on stdio

La base de datos predeterminada se encuentra en ~/.linksee-memory/memory.db. Puedes sobrescribirla con la variable de entorno LINKSEE_MEMORY_DIR.

Registrar en Claude Code

claude mcp add -s user linksee -- npx -y linksee-memory

Reinicia Claude Code. Las herramientas aparecerán como mcp__linksee__remember, mcp__linksee__recall, mcp__linksee__recall_file, mcp__linksee__read_smart, mcp__linksee__forget, mcp__linksee__consolidate.

Opcional: captura automática de cada sesión (Hook de parada)

Añádelo a ~/.claude/settings.json para registrar automáticamente cada sesión de Claude Code en tu cerebro local:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-sync" }
        ]
      }
    ]
  }
}

Cada final de turno toma ~100 ms. Los fallos son silenciosos (Claude Code nunca se bloquea). Los registros están en ~/.linksee-memory/hook.log.

Herramientas

Las 6 capas de memoria

Cada entidad (persona / empresa / proyecto / archivo / concepto) puede tener memorias en seis capas. La capa codifica el significado, no la categoría:

{
  "goal":    { "primary": "...", "sub_tasks": [], "deadline": "..." },
  "context": { "why_now": "...", "triggering_event": "...", "when": "..." },
  "emotion": { "temperature": "hot|warm|cold", "user_tone": "..." },
  "implementation": {
    "success": [{ "what": "...", "evidence": "..." }],
    "failure": [{ "what": "...", "why_failed": "..." }]
  },
  "caveat":  [{ "rule": "...", "reason": "...", "from_incident": "..." }],
  "learning":[{ "at": "...", "learned": "...", "prior_belief": "..." }]
}

• Las memorias de advertencia están protegidas automáticamente contra el olvido (lecciones dolorosas, nunca se pierden).

• Las memorias de objetivo evitan la degradación mientras el objetivo esté activo.

Arquitectura

Un único archivo SQLite (better-sqlite3 + tokenizador de trigramas FTS5 para JP/EN) contiene cinco capas:

• Capa 1 — entidades (hechos: personas / empresas / proyectos / conceptos / archivos)

• Capa 2 — bordes (asociaciones, adyacencia de grafos)

• Capa 3 — memorias (significados estructurados de 6 capas por entidad)

• Capa 4 — eventos (registro de series temporales para el cálculo de calor / impulso)

• Capa 5 — instantáneas_de_archivo + ediciones_de_archivo_de_sesión (caché de diff + enlace conversación↔archivo)

El enlace conversación↔archivo es la clave. Cada edición de archivo capturada por el hook de parada se almacena junto con el mensaje del usuario que impulsó la edición. Por lo tanto, recall_file("server.ts") devuelve "este archivo fue editado 30 veces en 3 días, y aquí están las instrucciones reales del usuario que motivaron cada cambio".

Por qué estas decisiones de diseño

• Prioridad local — tu historial de conversaciones es privado. Nada sale de tu máquina.

• Archivo único — memory.db es un artefacto portátil. Copia de seguridad = copia de archivo.

• MCP stdio — funciona con cada agente que habla MCP, sin plugins por host.

• Reutiliza esquemas probados — heat_score / momentum_score portados de una base de código de inteligencia de ventas en producción. Basado en reglas, sin dependencia de LLM en la ruta crítica.

Hoja de ruta

• ✅ 6 herramientas MCP principales (remember / recall / recall_file / forget / consolidate / read_smart)

• ✅ Captura automática con hook de parada para Claude Code

• ✅ FTS5 de trigramas JP/EN

• 🚧 Hook PreToolUse para interceptar automáticamente Read (ahorro de tokens sin configuración)

• 🚧 Adaptadores para Cursor + ChatGPT Desktop

• 🔮 Búsqueda vectorial mediante sqlite-vec una vez que se elija un backend de incrustación (Ollama / API / etc.)

• 🔮 Telemetría anonimizada opcional → capa de inteligencia de calidad MCP

Comparación con la memoria automática de Claude Code

Claude Code incluye una función de memoria integrada en ~/.claude/projects/<path>/memory/*.md — notas markdown planas para preferencias de usuario. linksee-memory lo complementa:

• memoria automática = tu bloc de notas de "recuerda que prefiero X"

• linksee-memory = cerebro estructurado entre agentes con caché de diff de archivos y PORQUÉ por edición

Usa ambos.

Telemetría (opcional, desactivada por defecto)

linksee-memory incluye telemetría anónima opcional que nos ayuda a entender qué servidores MCP y flujos de trabajo funcionan realmente en la práctica. No se envía nada a menos que lo habilites explícitamente. Sin contenido de conversación, sin contenido de archivo, sin nombres de entidades, sin rutas de proyecto, nunca.

Habilitar

export LINKSEE_TELEMETRY=basic     # opt in
export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)

Qué se envía exactamente (Contrato de Nivel 1)

Después de que finaliza cada sesión de Claude Code, el hook de parada envía un POST a https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee que contiene solo estos campos:

Lo que NUNCA se envía:

• ❌ Mensajes de conversación (usuario o asistente)

• ❌ Contenidos de archivos

• ❌ Nombres de entidades, nombres de proyectos, rutas de archivos, URLs

• ❌ Texto de la capa de memoria (objetivo / contexto / emoción / impl / advertencia / aprendizaje)

• ❌ Tokens de autenticación, claves API, secretos

• ❌ Tu dirección IP (solo un hash unidireccional para detección de abusos)

Por qué lo pedimos

Los datos agregados de uso de MCP ayudan al proyecto KanseiLink a clasificar qué integraciones de agentes funcionan realmente para desarrolladores reales. Si estás dispuesto a contribuir, LINKSEE_TELEMETRY=basic toma 1 segundo en configurarse y ayuda a mejorar todo el ecosistema MCP.

El esquema completo de carga útil y la lógica de validación son de código abierto — lee src/lib/telemetry.ts si quieres verificar exactamente qué sale de tu máquina.

Licencia

MIT — Synapse Arrows PTE. LTD.