gitmem

Dauerhaftes, überprüfbares Gedächtnis für deine KI-Agenten — in einem git-Repo, das du lesen, diffen und mit git blame nachvollziehen kannst.

Dein Coding-Agent vergisst zwischen den Sessions alles. gitmem gibt ihm ein Append-only-Ereignisprotokoll aus Fakten, Entscheidungen und Korrekturen, gespeichert als einfaches JSONL in git, aberdeterministische Projektionen: eine token-budgetierte brief zum Einfügen in den Kontext, eine Ansicht der aktuellen Fakten und eine Konfliktwarteschlange, die Widersprüche sichtbar macht, statt sie stillschweigend zu überschreiben.

Keine Vektor-DB. Keine LLM-Aufrufe. Kein Server. Ein Speichersystem, das du mit git log durchgehen kannst.

Installation

Installiere über npm:

npm install -g @josephy02/gitmem

Oder, wenn du das Claude-Code-Plugin entwickelst oder einrichtest, klone das Repository und installiere es lokal:

git clone https://github.com/josephy02/gitmem.git
cd gitmem
npm install   # builds automatically
npm link      # puts `gitmem` on your PATH

Verifiziere die Installation:

gitmem --help

Related MCP server: palinode

60-Sekunden-Schnellstart

gitmem init --root ./memory

gitmem --root ./memory append --scope team/core --kind decision \
  --body "Mobile still depends on the old auth module; do not refactor." \
  --author human:joseph

gitmem --root ./memory append --scope team/core \
  --body "The staging DB is reset every Sunday 03:00 UTC." \
  --author agent:builder-3

gitmem --root ./memory brief         # the context bootstrap, capped at 1,500 tokens
gitmem --root ./memory facts --json  # current-value view, NDJSON
gitmem --root ./memory conflicts     # contradictions, surfaced never auto-resolved
gitmem --root ./memory commit        # git commit of the log, on your cadence

Oder erkunde die gebündelte Demo – 45 realistische Ereignisse mit Korrekturen, einer Rücknahme, einer Höchstnsstufung und einem echten Konflikt:

gitmem --root /tmp/demo init
gitmem --root /tmp/demo append --json --force - < demo/events.ndjson
gitmem --root /tmp/demo brief

So funktioniert's

flowchart LR
    subgraph writers[" "]
        CLI[CLI / library]
        MCP[MCP client<br/>Claude Code etc.]
    end
    CLI -->|append| LOG
    MCP -->|memory_append| LOG
    LOG[("log/YYYY/MM/DD.jsonl<br/>append-only, in git")]
    LOG -->|pure function| PROJ[projections]
    PROJ --> BRIEF["brief.md<br/>≤1500 tokens"]
    PROJ --> FACTS["facts.json<br/>live/superseded/contested"]
    PROJ --> CONF["conflicts.json<br/>never auto-resolved"]
    LOG -.->|every read| CHOKE{{"readEvents()<br/>capability choke point"}}
    CHOKE --> BRIEF & FACTS & CONF
    GIT[git history] -->|"gitmem stale"| FACTS

1. Das log ist die alleinige Quelle der Wahrheit. Ein Ereignis pro Zeile in log/YYYY/MM/DD.jsonl. Nichts wird jemals verändert oder generationen – Korrekturen und Rücknahmen sind neue Ereignisse, die alte ersetzen, sodass die Historie/Herkunft jederzeit rekonstruierbar ist (gitmem trace <id>).

2. Projektionen sind reine Funktionen des Logs. facts.json (aktuelle Werte mit live/superseded/retracted/expired/contested-Status), brief.md (der immer eingebundene Kern, hart auf 1.500 Token begrenzt, Entscheidungen zuerst), conflicts.json, stats.json. gitmem rebuild ist byteidentisch mit einem inkrementellen Build – das ist ein Test.

3. Konflikte werden aufgedeckt, nie automatisch aufgelöst. Deterministische Heuristiken (divergente Korrekturen, Negationspaare, Abweichungen beim selben Subjekt) markieren Widersprüche; beide Seiten werden gemeinsam als contested zurückgegeben. Die Auflösung ist eine menschliche Aufgabe: Schreib eine Korrektur, die die Unterlegenen ersetzt.

4. Der Geltungsbereich wird zentral durchgesetzt. Jeder Lesepfad – Suche, point-get, brief, trace – läuft durch eine einzige Capability-geprüfte Funktion. Segmentbewusst: team/core gewährt team/core/auth, aber nie team/core-secrets. Promotion-Ereignisse ändern den effektiven Geltungsbereich eines Fakten und die Zugriffskontrolle folgt dem effektiven Geltungsbereich – eine Einschränkung schränkt also tatsächlich ein.

5. Wirklich git-nativ. gitmem init installiert einen Union-Merge-Treiber: Zwei Zweige, die an dieselbe Tagesdatei anhängen, werden automatisch zusammengeführt – die Vereinigung der Zeilen, sortiert nach ULID, immer korrekt, weil Ereignisse unveränderlich sind. gitmem verify fängt doppelte IDs aus fehlerhaften Merges ab.

Ereignisformat

Das Format ist das Produkt. Ein JSON-Objekt pro Zeile, Schema in schema/memevent.schema.json – jede Sprache kann Ereignisse schreiben, ohne diese Bibliothek zu ändern:

{"id":"01K2X9...","ts":"2026-08-15T14:03:11.000Z","scope":"team/core","author":{"kind":"human","id":"joseph"},"kind":"decision","body":"Mobile still depends on the old auth module; do not refactor.","derived_from":[],"supersedes":[],"confidence":1}

Fünf Ereignisarten: observation, decision, correction, retraction, promotion (auch eine Scope–Änderung ist ein Ereignis – Teilen bleibt nachvollziehbar).

Bibliothek

import { GitMem } from "@josephy02/gitmem";

const log = GitMem.open("./memory");
const cap = { principal: "agent:builder-3", scopes: ["team/core"], mode: "read" as const };

log.append({ scope: "team/core", kind: "observation", body: "...", author: { kind: "agent", id: "builder-3" } });
log.brief(cap);        // markdown string, reprojects lazily if the log advanced
log.facts(cap, { status: "live" });
log.conflicts(cap);
log.trace(cap, id);    // full derivation ancestry

Design-Grundsätze

• Kein LLM im Schreibpfad. Das Schreiben ist nösStil, verlustfrei und synchron.

• Keine Deduplication beim Schreiben. Widers reached auseinander wie Beinahe-Duplikate; ein Schreib-Gate würde genau die Ereignisse ablehnen, die der Konfliktdetektor sehen muss. Alles wird aufgenommen; die Auflösung erfolgt zur Projektionszeit.

• brief.override.md – eine von Menschen gepflegte Datei, die immer den oberen Platz im brief erhält.

• Mensch-zentrierter Speicher. Eine Änderung am Speicher per git diff ansehen, einen Fakt per git blame nachvollziehen, das Gedächtnis eines Agents im PR zielen.

Claude-Code-Plugin

Der schnellste Weg, Claude Code ein dauerhaftes Gedächtnis zu geben. Dieses Repository ist ein Plugin-Marketplace:

/plugin marketplace add josephy02/gitmem
/plugin install gitmem@gitmem

(Voraussetzung: Die gitmem-CLI: npm install -g @josephy02/gitmem.)

Was du bekommst:

• Memory-Brief beim Sitzungsstart – ein SessionStart-Hook injiziert gitmem brief ein, so dass jede Sitzung mit den Entscheidungen und Fakten des Projekts beginner. Kein gitmem-Root im Projekt? Der Hook ist ein stiller No-op.

• Memory-Tools über MCP – Claude kann ich Beobachtungen, Entscheidungen und Korrekturen anhängen, während es arbeitet. Der Root wird automatisch gefunden ($GITMEM_ROOT, ./.gitmem, ./memory, ./.memory) und bei der ersten Nutzung automatisch initialisiert.

• /remember <fact> – speichert eine dauerhafte Einheit oder Entscheidung, mit Korrektursemantik, wenn sie einem bestehenden Memory widrecht. /remember ohne Argumente druckt die aktuelle Konversation zusammen.

• /memory-review – die Konfliktwarteschlange und veraltete Anker durchgehen und über das Logger auflösen.

MCP-Server

Gib jedem MCP-Client (Claude Code, Claude Desktop, allem, was MCP spricht) mit einer Zeile dauerhaftes Gedächtnis:

{
  "mcpServers": {
    "gitmem": { "command": "gitmem", "args": ["--root", "/path/to/memory", "serve"] }
  }
}

Macht über stdio fünf Tools verfügbar: memory_append, memory_brief, memory_facts, memory_conflicts, memory_trace. Appends werden standardmäßig agent:mcp zugeordnet (--author zum Ändern); Lesezugriffe laufen durch denselben Capability-prüfpunkt wie alles andere.

Git-verankerte Veraltung

Ein Fakt kann sich über meta.source_uri selbst im Code verankern (z. B. "src/auth.ts#validateToken"). Da das Log in git direkt neben dem Code liegt, ist die Erkennung von Veraltung einfach ein git log:

gitmem stale            # lists live facts whose anchored file changed since the fact was written

[stale?] validateToken always returns true in dev mode
  anchor: src/auth.ts#validateToken
  changed by:
    e1faa27 flip validateToken default

Keine Embeddings, kein LLM, kein zu wartender Index – dieselbe Eigenschaft, die den Speicher überprüfbar macht, macht ihn auch selbstinvalidierend.

Entwicklung

npm install
npm run build
npm test        # 16 tests incl. property-based scope isolation and a real git-branch merge

Leistung: Ein vollständiges Projektion eines Logs mit 10k-Ereignissen läuft in ~50ms.

Lizenz

MIT