📜 Litopys

Eine lebendige Chronik für deine KI.

Persistenter graphbasierter Speicher, der Sitzungen und Clients überdauert. Entwickelt für Claude Code, Claude Desktop und jeden MCP-kompatiblen Agenten.

litopys-dev.github.io/litopys — Installation, Screenshots und Schnellstart

🇺🇦 Читати українською

Warum Litopys?

Speichersysteme für KI-Agenten erzwingen heute einen Kompromiss: entweder schwerfällige Vektordatenbanken mit Subprozess-Lecks und ca. 500 MB RAM-Verbrauch oder einfache Markdown-Dateien, die bei mehr als ein paar Dutzend Notizen nicht mehr skalieren.

Litopys wählt einen dritten Weg: einen typisierten Wissensgraph, der in einfachem Markdown gespeichert ist, über eine schlanke MCP-Schicht (~75 MB RAM) bereitgestellt wird, manuell bearbeitbar ist und sowohl nach Schlüsselwörtern als auch nach Struktur abgefragt werden kann. Litopys bedeutet auf Ukrainisch „Chronik“ – denn genau das sollte das Gedächtnis deiner KI sein: eine lebendige Aufzeichnung dessen, was sie über dich gelernt hat, wann und warum.

Related MCP server: auxly-memory-cli

Funktionen

• 🧠 Typisierter Graph — 6 Knotentypen (Person, Projekt, System, Konzept, Ereignis, Lektion) mit 11 erstklassigen Beziehungen

• 🔌 MCP-nativ — funktioniert mit Claude Code, Claude Desktop, Cursor, Cline oder jedem MCP-Client (siehe docs/integrations)

• 📝 Markdown-First — jeder Knoten ist eine einfache .md-Datei mit YAML-Frontmatter. Manuell bearbeitbar, durchsuchbar mit grep, git-versioniert

• 🤖 Modell-agnostischer Extraktor — Anthropic, OpenAI oder lokales Ollama. Wähle nach deinem Ressourcen-/Kostenbudget (siehe Ressourcenverbrauch unten). Fakten fließen durch eine Quarantäne, damit nichts ungeprüft landet

• 🌐 Web-Dashboard — durchsuche, finde, bearbeite, visualisiere den Graphen und überprüfe die Quarantäne unter http://localhost:3999

• 🔐 Bleibt lokal — der Graph liegt als Dateien in ~/.litopys/graph/; der Server bindet standardmäßig an 127.0.0.1; keine Telemetrie

Dashboard

Screenshots wurden mit einem synthetischen Demo-Graphen erstellt, der in docs/screenshots/ enthalten ist — nicht mit den persönlichen Notizen des Autors.

Status

v0.1.2 ist veröffentlicht — vorgefertigte Binärdateien für Linux / macOS / Windows (x64 + arm64), mit SHA-256-Prüfsummen, die durch install.sh verifiziert werden. Sicherheits-Release auf Basis der stabilen Linie v0.1.1 — siehe CHANGELOG. Öffentliche Schnittstellen (MCP-Tools, CLI, JSON-Export schemaVersion: 1, Markdown-Layout auf der Festplatte) sind eingefroren; Breaking Changes werden als 0.2.x veröffentlicht.

Der Kerngraph, MCP-Server (5 Tools, stdio + HTTP/SSE), Extraktor + Quarantäne + wöchentliche Zusammenfassung, Timer-Daemon, Dashboard (Lesen + Schreiben + Graph-Visualisierung + Quarantäne-Überprüfung), Identitätsauflösungs-Leitplanken, Single-Binary-Build, Einzeilen-Installer, client-spezifische Integrationsdokumentationen — alles ausgeliefert. Siehe Was kommt als Nächstes für die geplanten Erweiterungen.

Ressourcenverbrauch

Ehrliche Zahlen aus der eigenen Installation des Autors (Ubuntu, Bun 1.x). Der MCP-Server ist günstig; der Extraktor ist der Punkt, an dem Kosten entstehen, und das hängt davon ab, welchen Adapter du wählst.

Die minimalen laufenden Kosten betragen also ca. 75 MB für den MCP-Server. Die Extraktion ist optional — du kannst Litopys nur lesend/schreibend von deinem Agenten aus nutzen, ohne jemals den Daemon zu starten. Wenn du die Extraktion aktivierst, tauscht der lokale Ollama-Weg Geld gegen RAM; der Anthropic/OpenAI-Weg tauscht RAM gegen Cent-Beträge pro Sitzung. Ollamas keep_alive bedeutet, dass die 3B/7B-Werte nur vorübergehend sind — das Modell wird einige Minuten nach Abschluss des Ticks aus dem RAM entfernt.

Schnellstart

Einzeilige Installation (Linux / macOS):

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | sh

Dies lädt eine einzelne ~100 MB große Binärdatei nach ~/.local/bin/litopys herunter, initialisiert ~/.litopys/graph/ mit den erforderlichen Unterverzeichnissen und gibt Hinweise zur MCP-Registrierung aus.

Fixiere eine bestimmte Version, indem du die Zuweisung nach dem Pipe-Symbol platzierst — Umgebungsvariablen, die vor curl gesetzt werden, gelten nur für curl selbst, nicht für die gepipte Shell:

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | LITOPYS_VERSION=v0.1.2 sh

Registriere dann den MCP-Server bei deinem Client:

# Claude Code
claude mcp add litopys -- ~/.local/bin/litopys mcp stdio

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "litopys": {
      "command": "/home/you/.local/bin/litopys",
      "args": ["mcp", "stdio"]
    }
  }
}

Starte den Client neu. Die Ressource litopys://startup-context lädt bei jeder neuen Sitzung automatisch das Eigentümerprofil, aktive Projekte, aktuelle Ereignisse und wichtige Lektionen. Der Agent liest/schreibt über fünf MCP-Tools: litopys_search, litopys_get, litopys_related, litopys_create, litopys_link.

Vollständige client-spezifische Anleitungen findest du unter docs/integrations/ — Claude Code, Claude Desktop, Cursor, Cline, ChatGPT Connectors, Gemini.

Remote-Modus (HTTP/SSE)

Für Remote-Clients (Claude Desktop Connectors, browserbasierte MCP-Hosts):

LITOPYS_MCP_TOKEN=your-secret litopys mcp http
# listens on 127.0.0.1:7777 by default
# set LITOPYS_MCP_BIND_ADDR=0.0.0.0 + TLS proxy for remote exposure
# set LITOPYS_MCP_CORS_ORIGIN=https://your-client to enable CORS

Entwickler-Installation (aus dem Quellcode)

git clone https://github.com/litopys-dev/litopys.git
cd litopys
bun install
bun run build:binary       # produces dist/litopys

Optional — Daemon für lang laufende Transkripte

cp packages/daemon/systemd/litopys-daemon.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-daemon.timer

Optional — Web-Dashboard-Autostart

Das Dashboard (litopys viewer) kann als systemd-Benutzerdienst ausgeführt werden, sodass es nach jedem Neustart wieder verfügbar ist.

litopys viewer install        # generates token, writes unit, enables service
litopys viewer install --lan  # same + binds to 0.0.0.0 for LAN access
systemctl --user status litopys-viewer

# Remove:
litopys viewer uninstall

Zugriffstoken. viewer install generiert automatisch ein zufälliges Token und speichert es unter ~/.litopys/viewer.token. Die Installationsausgabe druckt eine sofort einsatzbereite URL mit eingebettetem Token:

✓ litopys-viewer installed

  Open dashboard:    http://localhost:3999/?token=<token>
  Share with others: http://192.168.1.x:3999/?token=<token>   # --lan only

  Opening the link once saves the token — no re-entry needed.
  Retrieve token later: cat ~/.litopys/viewer.token

Das einmalige Öffnen der URL speichert das Token im localStorage — keine weiteren Abfragen. Um Schreibzugriff mit jemandem zu teilen, sende ihm die URL, die ?token=… enthält. Um das Token jederzeit abzurufen: cat ~/.litopys/viewer.token.

GET-Endpunkte (Durchsuchen, Suchen, Graph-Ansicht) sind immer offen. Ändernde Endpunkte (Knoten erstellen / bearbeiten / löschen, Quarantäne akzeptieren oder ablehnen) erfordern das Token.

Oder setze LITOPYS_ENABLE_VIEWER=1 beim Ausführen von install.sh, um es als Teil der Einzeilen-Installation zu aktivieren. Erfordert loginctl enable-linger $USER, wenn das Dashboard auch nach dem Abmelden aktiv bleiben soll.

Integritätsprüfung

litopys check           # human-readable report, grouped by error kind
litopys check --json    # { nodeCount, edgeCount, errorCount, errors[] } for CI

Lädt und löst den gesamten Graphen auf, markiert dann defekte Referenzen, doppelte IDs, falsch typisierte Beziehungen sowie Analyse-/Validierungsfehler. Beendet den Prozess mit einem Fehlercode ungleich Null, wenn Probleme gefunden werden — füge dies in einen Git-Pre-Push-Hook oder CI-Schritt ein, damit Abweichungen niemals unbemerkt bleiben.

Sichern deines Graphen

Litopys speichert alles als einfaches Markdown in ~/.litopys/graph/, daher funktioniert jedes Tool, das Dateien versioniert. Zwei gängige Ansätze:

Git + privates Remote (inkrementelle Historie, extern, kostenlos):

cd ~/.litopys
git init
git add graph/ .gitignore README.md
git commit -m "baseline"
gh repo create my-litopys-graph --private --source=. --push

Von da an lässt jeder Sitzungs-End-Hook oder jede manuelle Bestätigung deinen Arbeitsbaum als "dirty" zurück — führe regelmäßig git add -A && git commit -m "sync" && git push aus, um das Backup aktuell zu halten. Dein Graph enthält persönliche Fakten, also halte das Remote-Repository privat.

JSON-Snapshot (portabel, diffbar, tool-freundlich):

litopys export > graph.json              # compact
litopys export --pretty > graph.json     # indented, VCS-friendly
litopys export --no-body > meta.json     # metadata only, strip markdown bodies

Der Dump enthält meta (exportedAt, counts, schemaVersion) sowie alle Knoten sortiert nach ID und Kanten sortiert nach (from, relation, to) — deterministisch über verschiedene Läufe hinweg, sodass diff graph-yesterday.json graph-today.json dir genau sagt, was der LLM/Daemon hinzugefügt hat. Füttere es in Analysetools, migriere zwischen Hosts oder committe es zusammen mit dem Code.

Wiederherstellung aus einem Snapshot auf einem neuen Host (oder nach einer Neuinstallation):

litopys import graph.json --dry-run   # preview the plan
litopys import graph.json             # create new nodes, skip existing ones
litopys import graph.json --force     # also overwrite existing ids

Der Standard ist konservativ — bestehende Knoten werden niemals berührt, es sei denn, du übergibst --force. Jeder Knoten wird vorab gegen das Schema validiert, sodass ein korrupter Snapshot abbricht, bevor etwas auf der Festplatte landet.

Release-Historie

Siehe CHANGELOG.md. Zukünftige Arbeiten werden durch echtes Benutzerfeedback vorangetrieben — öffne ein Issue, wenn etwas nicht passt.

Designprinzipien

• Agenten-agnostisch. Keine harte Abhängigkeit von einem LLM-Anbieter oder Client. MCP ist der einzige Integrationspunkt. Ollama ist der Standard-Extraktor; Anthropic/OpenAI sind optionale Adapter.

• Portable Daten. Der Graph ist einfaches Markdown + YAML-Frontmatter auf der Festplatte. Lesbar in jedem Editor, versionierbar in Git, durchsuchbar über die Shell.

• Leichte Laufzeit. ~75 MB RAM für den MCP-Server. Der Extraktor läuft außerhalb des Prozesses und nach deinem Zeitplan, nicht bei jeder Anfrage — siehe Ressourcenverbrauch für die vollständige Kostenaufschlüsselung über Adapter hinweg.

• Optionale Integrationen. Client-spezifische Helfer (Hooks, Konfigurations-Snippets) befinden sich in docs/integrations/ — du kannst Litopys ohne diese verwenden.

Lizenz

MIT © 2026 Denis Blashchytsia und Litopys-Mitwirkende.