Simple Rick

Persistenter Speicher für KI-Coding-Agenten.

Jede Coding-Session mit einem KI-Agenten beginnt bei null. Du erklärst die Architektur erneut, rechtfertigst die Entscheidung, die du vor drei Wochen bereits getroffen hast, neu und entdeckst den Fehler wieder, den du schon einmal behoben hast. Das Transkript existiert, aber es ist eine Textwand, die niemand – weder Mensch noch Modell – noch einmal liest.

Simple Rick ist ein MCP-Server, der neben deinem Agenten sitzt und genau das behebt. Er zeichnet auf, was in einer Session tatsächlich passiert, normalisiert es in strukturierte Chunks mit Embeddings, verbindet die Chunks zu einem Graphen und reicht den relevanten Teil zu Beginn der nächsten Session zurück.

Alles läuft lokal. Eine SQLite-Datei in deinem Projekt, keine externe Datenbank, keine Telemetrie.

Status: Alpha. Es funktioniert und wird genutzt, hat aber raue Kanten – siehe Bekannte Einschränkungen. Schnittstellen können sich ändern.

So funktioniert es

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"]

Zwei Dinge speisen die Pipeline: ein Hook, der jeden Tool-Aufruf deines Agenten meldet, und ein Datei-Watcher, der Diffs mit Millisekunden-Zeitstempeln erfasst. Beide landen im Recorder, der rohe Turns absturzsicher schreibt.

Eine Hintergrundwarteschlange verarbeitet diese Turns, ohne deine Session zu blockieren. Der leichtgewichtige Normalisierer klassifiziert Absicht und Domäne kostengünstig; der tiefgehende Normalisierer fasst zusammen und erstellt Embeddings; der Kanten-Verknüpfer verbindet neue Chunks mit verwandten bestehenden. Das Ergebnis ist ein kleiner Wissensgraph, kein Transkript.

Zu Beginn der nächsten Session liest der Biefing-Dienst diesen Graphen und gibt deinem Agenten ein Biefing statt eines leeren Blatts.

Related MCP server: hive-memory

Schnellstart

Erfordert Node.js 20+.

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

1. Gib ihm einen KI-Anbieter

Simple Rick benötigt einen Anbieter für Embeddings und einen für Chat-Compietion. Er erkennt sie automatisch anhand der Umgebung, der erste Treffer gewinnt:

Anthropic hat kein Embedding-Modell, weshalb es zusätzlich Voyage benötigt.

2. Registriere es als MCP-Server

In der .mcp.json deines Projekts:

{
  "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. Installiere den Recorder-Hook

Ohne dies sieht Simple Rick nur Dateiänderungen – nicht, was dein Agent tut. Kopiere hooks/simple-rick-recorder.js an einen dauerhaften Ort und registriere es als PostToolUse-Hook in ~/.claude/settings.json:

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

Der Hook ist Fire-and-Forget: Er blockiert deinen Agenten nie und tut still nichts, wenn Simple Rick nicht läuft.

4. Verwende es

Starte eine Session und rufe einmal simple_rick_init auf, um den Projektkontext anzulegen. Öffne danach jede Session mit simple_rick_briefing und schließe sie mit simple_rick_close.

MCP-Tools

Web-UI

Der Server stellt außerdem eine lokale Flow-Visualisierung unter http://127.0.0.1:3777 bereit, die die Pipeline live und den resultierenden Graphen zeigt. Sie ist durch einen beim ersten Start generierten Bearer-Token geschützt; die URL inklusive Token wird von simple_rick_briefing ausgegeben.

REST-Endpunkte: GET /api/graph, GET /api/sessions, POST /api/record.

Wo deine Daten liegen

Alles liegt in .simple-rick/ in deinem Projekt:

.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 fügt .simple-rick/ beim ersten Start zu deiner .gitignore hinzu. Nichts wird irgendwohin gesendet, außer an den von dir konfigurierten KI-Anbieter, zur Normalisierung und für Embeddings.

Sei dir der Größe bewusst. Vollständige Aufzeichnung ist nicht billig auf der Festplatte – ein umfangreiches mehrtägiges Projekt kann eine Datenbank mit Hunderten von Megabyte erzeugen.

Entwicklung

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

Es gibt außerdem eine End-to-End-Suite in e2e/, die echte Claude-Code-CLI-Sessions gegen den Server ausführt, um jedes MCP-Tool zu testen:

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

Sie ist nicht in npm test eingebunden, weil sie echte API-Aufrufe kostet.

Feinabstimmung

Alle optional – die Standardwerte sind das, womit das Projekt monatelang lief.

Bekannte Einschränkungen

Ehrliche Liste, damit niemand überrascht ist:

• Nur gegen Claude Code getestet. Die MCP-Schnittstelle ist Standard, aber der Recorder-Hook ist für das Hook-Format von Claude Code geschrieben.

• Die Aufzeichnung ist nicht billig auf der Festplatte. Siehe Wo deine Daten liegen.

• Der Wissensgraph ist nur so gut wie das Modell dahinter. Normalisierung, Domain-Routing und Insight-Validierung sind alles LLM-Aufrufe; ein kleines oder billiges Modell erzeugt einen entsprechend vagen Graphen.

• Noch kein Pruning. Nichts altert von selbst aus der Datenbank aus.

Lizenz

MIT – siehe LICENSE.