Simple Rick

Memoria persistente para agentes de codificación con IA.

Cada sesión de codificación con un agente de IA empieza desde cero. Vuelves a explicar la arquitectura, vuelves a justificar la decisión que ya tomaste hace tres semanas y vuelves a descubrir el error que ya corregiste una vez. La transcripción existe, pero es un muro de texto que nadie —ni humano ni modelo— vuelve a leer.

Simple Rick es un servidor MCP que se sitúa junto a tu agente y lo soluciona. Registra lo que ocurre realmente en una sesión, lo normaliza en fragmentos estructurados con embeddings, conecta los fragmentos en un grafo y devuelve la parte relevante al inicio de la siguiente sesión.

Todo se ejecuta en local. Un archivo SQLite en tu proyecto, sin base de datos externa ni telemetría.

Estado: alpha. Funciona y se usa, pero tiene aristas sin pulir: consulta Limitaciones conocidas. Las interfaces pueden cambiar.

Cómo funciona

flowchart LR
    A["Claude Code<br/>PostToolUse hook"] -->|POST /api/record| B[Recorder]
    W["File watcher<br/>(chokidar)"] --> B
    B --> Q[Norm queue]
    Q --> L["Lightweight<br/>normalizer"]
    L --> D["Deep<br/>normalizer"]
    D --> E[Edge wirer]
    E --> G[("SQLite<br/>+ sqlite-vec")]
    G --> BR[Briefer]
    G --> S[Semantic search]
    G --> I[Insight engine]
    BR --> M["MCP tools<br/>→ your agent"]
    S --> M
    I --> M
    G --> U["Web UI<br/>:3777"]

Dos cosas alimentan el pipeline: un hook que notifica cada llamada a herramientas que hace tu agente y un file watcher que captura los diffs con marcas de tiempo de milisegundos. Ambas llegan al grabador, que escribe los turnos en bruto de forma segura ante caídas.

Una cola en segundo plano drena esos turnos sin bloquear tu sesión. El normalizador ligero clasifica la intención y el dominio de forma económica; el normalizador profundo resume y genera embeddings; el conectador de aristas enlaza los fragmentos nuevos con los relacionados ya existentes. El resultado es un pequeño grafo de conocimiento, no una transcripción.

Al inicio de la siguiente sesión, el briefer lee ese grafo y le da a tu agente un informe en lugar de una pizarra en blanco.

Related MCP server: hive-memory

Inicio rápido

Requiere Node.js 20+.

git clone https://github.com/good-v1be/simple-rick.git
cd simple-rick
npm install
npm run build

1. Dale un proveedor de IA

Simple Rick necesita un proveedor para los embeddings y otro para la finalización de chat. Lo detecta automáticamente a partir del entorno; la primera coincidencia gana:

Anthropic no tiene modelo de embeddings, por eso necesita Voyage junto a él.

2. Regístralo como servidor MCP

En el .mcp.json de tu proyecto:

{
  "mcpServers": {
    "simple-rick": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/simple-rick/src/server/index.ts"],
      "env": {
        "PROJECT_PATH": ".",
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    }
  }
}

3. Instala el hook del grabador

Sin esto, Simple Rick solo ve los cambios de archivos, no lo que tu agente hizo realmente. Copia hooks/simple-rick-recorder.js a una ubicación permanente y regístralo como hook PostToolUse en ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit",
        "hooks": [
          { "type": "command", "command": "node /path/to/simple-rick-recorder.js" }
        ]
      }
    ]
  }
}

El hook es de tipo «dispara y olvida»: nunca bloquea a tu agente y, cuando Simple Rick no está en ejecución, no hace nada en silencio.

4. Úsalo

Inicia una sesión y llama a simple_rick_init una vez para sembrar el contexto del proyecto. A partir de entonces, abre cada sesión con simple_rick_briefing y ciérrala con simple_rick_close.

Herramientas MCP

Interfaz web

El servidor también expone una visualización local del flujo en http://127.0.0.1:3777, que muestra el pipeline en directo y el grafo resultante. Está protegida por un token de portador generado en la primera ejecución; simple_rick_briefing imprime la URL con el token incluido.

Endpoints REST: GET /api/graph, GET /api/sessions, POST /api/record.

Dónde se guardan tus datos

Todo se encuentra en .simple-rick/ dentro de tu proyecto:

.simple-rick/
  simple-rick.db   SQLite: sessions, turns, chunks, edges, embeddings (sqlite-vec)
  .token           bearer token for the local HTTP server (mode 0600)

Simple Rick añade .simple-rick/ a tu .gitignore en la primera ejecución. No se envía nada a ninguna parte salvo al proveedor de IA que hayas configurado, para la normalización y los embeddings.

Ten en cuenta el tamaño. La grabación completa no es barata en disco: un proyecto intenso de varios días puede generar una base de datos de cientos de megabytes.

Desarrollo

npm run dev     # tsx watch
npm run build   # compile to dist/
npm run lint    # tsc --noEmit
npm test        # vitest (11 unit + integration tests)

También hay una suite de extremo a extremo en e2e/ que lanza sesiones reales de Claude Code CLI contra el servidor para poner a prueba cada herramienta MCP:

python3 e2e/test_mcp_e2e.py        # requires the `claude` CLI and a configured provider

No está integrada en npm test porque consume llamadas reales a la API.

Ajustes

Todo es opcional: los valores predeterminados son con los que el proyecto ha funcionado durante meses.

Limitaciones conocidas

Lista honesta, para que nadie se lleve una sorpresa:

• Solo probado con Claude Code. La interfaz MCP es estándar, pero el hook del grabador está escrito para el formato de hooks de Claude Code.

• La grabación no es barata en disco. Consulta Dónde se guardan tus datos.

• El grafo de conocimiento solo es tan bueno como el modelo que hay detrás. La normalización, el enrutamiento de dominios y la validación de insights son llamadas a LLM; un modelo pequeño o barato produce un grafo igualmente vago.

• Todavía no hay poda. Nada envejece y se elimina de la base de datos por sí solo.

Licencia

MIT — consulta LICENSE.