Thoth-Mem

Permanenter Speicher für KI-Codierungsagenten

Gib Codierungsagenten dauerhaften Projektspeicher über Sitzungen, Kompaktierungen und Kontextzurücksetzungen hinweg.

Thoth-Mem ist ein lokaler MCP-Server auf Basis von SQLite und FTS5. Er bewahrt nützliche Entscheidungen, Fehlerbehebungen, Konventionen und Sitzungskontinuität auf und ruft dann nur die Beweise ab, die ein Agent benötigt. Dieselbe Installation bietet außerdem eine CLI, eine optionale HTTP-API und native Lebenszyklus-Integrationen für unterstützte Codierungs-Harnesses.

Der globale Geltungsbereich verwaltet die Harness-Konfiguration des aktuellen Benutzers; der Projekt-Geltungsbereich ist explizit und auf das ausgewählte Projekt und seinen Belegbaum beschränkt. Engram, thoth-agents oder eine andere Speicherintegration können sich überschneiden; betrachten Sie dies nur als Warnung: thoth-mem bearbeitet, deaktiviert oder entfernt keine externen Repositorys und schreibt nicht in sie.

Schnellstart

Erfordert Node.js 18 oder neuer. Das native Setup ist optional: Eine manuelle MCP-Verbindung benötigt nur den Befehl mcp.

Das veröffentlichte Paket ausführen

Starten Sie den neuesten veröffentlichten MCP-Server, ohne einen globalen Befehl zu installieren:

npx -y thoth-mem@latest mcp

Dies startet den MCP-Server und seine lokale HTTP-Brücke. Fügen Sie --no-http hinzu, wenn nur der MCP-Transport gewünscht ist. Neue Client-Konfigurationen sollten den expliziten Unterbefehl mcp verwenden.

Native Integrationen rufen nach dem Setup den persistenten Befehl thoth-mem auf. Installieren oder aktualisieren Sie diesen Befehl daher global, bevor Sie eine Harness konfigurieren. Verwenden Sie npx, um die Setup-Implementierung aus dem neuesten veröffentlichten Paket auszuführen, prüfen Sie ihren Plan ohne Schreibvorgänge und wenden Sie ihn dann an:

npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

Ersetzen Sie codex durch opencode oder claude für eine andere unterstützte Harness und starten Sie diese Harness dann neu. Die alleinige Ausführung von setup installiert oder aktualisiert das npm-Paket nicht.

Dieses Repository installieren

Verwenden Sie den Repository-Ablauf, um Commits zu testen, die noch nicht veröffentlicht wurden:

pnpm install
pnpm run build
pnpm add -g .
thoth-mem version
thoth-mem setup codex --scope global --plan --json
thoth-mem setup codex --scope global --json

thoth-mem@latest enthält nur die neueste veröffentlichte Version. Bauen Sie neu und führen Sie pnpm add -g . erneut aus, nachdem Sie neuere unveröffentlichte Commits gezogen haben.

Eine bestehende Installation aktualisieren

Aktualisieren Sie zuerst das Paket. Wenn eine native Integration installiert ist, führen Sie deren Setup erneut aus, damit kopierte Assets, Skills, Hooks und verwaltete Deklarationen mit der neuen Paketversion konvergieren:

pnpm add -g thoth-mem@latest
npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

Starten Sie dann die Harness oder den MCP-Prozess neu. Manuelle MCP-Benutzer benötigen kein setup; ein Neustart von npx -y thoth-mem@latest mcp genügt.

Das Setup bewahrt die Speicherdatenbank und die benutzereigene Konfiguration. Beim Start können fehlende Konfigurationsfelder nachgefüllt werden, aber explizite Werte wie ein LM-Studio-Modell bleiben ausgewählt. Das Konfigurationsformat bleibt "version": 1. Aktualisieren Sie bei einer veröffentlichten Installation eine ältere $schema-URL manuell auf diese Release-Version für aktuelle Editor-Validierung und Autovervollständigung. Ein unveröffentlichter Checkout muss config.schema.json dieses Repositorys für passende Validierung verwenden, da unpkg die Änderung vor der Veröffentlichung nicht bereitstellen kann. Die Schema-URL steuert keine Laufzeit-Migration.

Das Ändern eines Embedding-Modells ist ein Konfigurationsvorgang, kein Setup-Vorgang. Bearbeiten Sie embedding.provider, model, baseUrl und native dimensions nach Bedarf; profile: "auto" löst unterstützte Modellfamilien auf. Starten Sie thoth-mem neu und lassen Sie die geänderte Embedding-Abstammung den idempotenten Neuaufbau des semantischen Index in die Warteschlange stellen.

Related MCP server: LumenCore

Die Speicherschleife

Ein nützlicher Agenten-Workflow ist klein und wiederholbar:

1. Die dauerhafte Lektion speichern. Verwenden Sie mem_save für eine Entscheidung, Grundursache, Konvention oder andere nicht offensichtliche Tatsache, die den aktuellen Kontext überleben soll.

2. Eng abrufen. Beginnen Sie mit mem_recall(mode="compact"), erweitern Sie starke Kandidaten mit mode="context" und rufen Sie einen vollständigen ausgewählten Datensatz mit mem_get ab.

3. Mit Identität fortfahren. Behalten Sie dieselbe stabile session_id und dasselbe project; verwenden Sie mem_context für aktuelle Kontinuität und mem_session für Root-eigene Lebenszyklus-Ereignisse.

Beispiel-Beobachtung:

{
  "kind": "observation",
  "title": "Retry SQLite writes in a new transaction",
  "type": "bugfix",
  "project": "my-project",
  "topic_key": "sqlite/busy-retry",
  "content": "**What**: Roll back after SQLITE_BUSY and retry in a new transaction.\n**Why**: Retrying inside the failed transaction repeats the failure.\n**Where**: write transaction helper.\n**Learned**: Use bounded backoff before opening the new transaction."
}

Entfernen Sie Inhalte innerhalb von <private>...</private> vor der Persistierung. Speichern Sie keine Anmeldeinformationen, vollständigen Transkripte, generierten Agenten-Prompts als Benutzerabsicht oder Rohprotokolle ohne eine wiederverwendbare Lektion.

Sechs MCP-Tools

Setup-, Synchronisierungs-, Migrations-, Neuaufbau- und Wartungsbefehle sind CLI/HTTP-Verwaltung, keine zusätzlichen MCP-Tools.

Graph-Communities untersuchen

Communities sind begrenzte Zusammenfassungen, die aus dem Wissensgraph eines Projekts abgeleitet werden. Ein Operator erstellt oder aktualisiert die festgeschriebenen Zusammenfassungen über die CLI:

thoth-mem rebuild-communities --project my-project

Ein Agent erhält sie dann über mem_project:

{
  "action": "graph",
  "project": "my-project",
  "navigation": "community",
  "limit": 5,
  "max_chars": 2000
}

Die Antwort meldet Community-Zustand und Aktualität, dann Einträge wie community=<id>, Graph-Abdeckung, Konfidenz, Degradationszustand, eine begrenzte Zusammenfassung und sources=obs:<id>. Die Community-Untersuchung erfordert ein Projekt, aber keinen Fokus-Knoten oder Beobachtungs-ID. Wenn keine festgeschriebenen Zusammenfassungen existieren, wird dies mitgeteilt, anstatt eine globale Antwort zu synthetisieren.

Um Beweise hinter einer Community zu untersuchen, nehmen Sie ein obs:<id> aus deren sources-Feld und rufen Sie mem_get(kind="observation", id=<id>) auf. Beobachtungs-IDs erscheinen auch in Abrufergebnissen. Für eine begrenzte Graph-Nachbarschaft verwenden Sie eine als focus_node_id="obs:<id>" mit navigation="neighborhood" erneut.

Native Harness-Integrationen

Das native Setup installiert die gepackte MCP-Deklaration, den Speicher-Skill und Lebenszyklus-Hooks, wo die Harness diese unterstützt. Prüfen Sie zuerst den Plan ohne Schreibvorgänge und führen Sie ihn dann ohne --plan erneut aus, um ihn anzuwenden:

Der Standard-Setup-Befehl für OpenCode ist thoth-mem setup opencode; fügen Sie thoth-mem setup opencode --scope project --project /path/to/project --force hinzu, wenn Sie explizit ein Projekt ansprechen, oder verwenden Sie thoth-mem setup codex --rollback /path/to/receipt.json für ein belegbezogenes Rollback.

Setup-Status und Prozess-Exit-Codes sind stabil:

Projektlokales Setup ist explizit:

thoth-mem setup opencode --scope project --project /path/to/project --plan --json

Prüfen Sie erkannte Konflikte vor dem Anwenden. Verwenden Sie --force nur für konfliktbehaftete Speicherorte, deren thoth-mem-Eigentum bereits nachgewiesen ist. Codex 0.144.x, 0.146.x und 0.147.x gehören zum getesteten Kompatibilitätssatz und erfordern kein --force. Für andere Codex-Versionen darf --force nur die Testversions-Sperre überschreiben, wenn der ausgewählte Geltungsbereich weiterhin vollständige, unabhängig überprüfbare Plugin-Manager-Fähigkeiten bereitstellt; das Setup gibt eine Warnung aus, wenn es diese Überschreibung verwendet. Es umgeht keine Zustandsprüfung, Eigentums-, Eindämmungs-, Abgleich- oder Bereinigungsschutzmaßnahmen und gewährt keine Autorität über unzusammenhängende Konfiguration.

Claude Code unterstützt auch seinen nativen Marketplace-Ablauf:

claude plugin marketplace add EremesNG/thoth-mem
claude plugin install thoth-mem

Die native Integration ist optional. Bestehende Speicher und der MCP-Server mit sechs Tools funktionieren weiterhin mit einer manuellen Verbindung.

Manueller MCP-Fallback

Native Hooks sind optional. Behalten Sie eine einfache MCP-Verbindung mit sechs Tools bei, wenn Sie kein verwaltetes Setup oder natives Plugin wünschen; bestehende Speicher bleiben verfügbar.

Übergang zur nativen Harness-Integration

Das native Setup ist optional: Prüfen Sie den Plan ohne Schreibvorgänge, überprüfen Sie Konflikte und wenden Sie dann den passenden Harness-Befehl an. Öffnen Sie für Codex /plugins, installieren Sie thoth-mem von EremesNG/thoth-mem und verifizieren Sie den Marketplace- und Plugin-Zustand. Die externe Codex-Registrierung ist nicht atomar umkehrbar. Bestätigen Sie daher den externen Zustand, bevor Sie das lokale Setup erneut versuchen oder zurückrollen.

Vertrag für verwaltetes Setup: Der Planmodus führt keine Schreibvorgänge aus und mutiert nur an thoth-mem-verwalteten Speicherorten. Backups werden vor der ersten Mutation erstellt; OpenCode akzeptiert opencode.json oder opencode.jsonc. Jeder mutierende Versuch schreibt einen HMAC-geschützten Beleg mit Status in_progress vor Änderungen:

• globale Belege: <thoth-data-dir>/setup/receipts/<receipt-id>/receipt.json

• Projekt-Belege: <project>/.thoth/setup/receipts/<receipt-id>/receipt.json

Fehlende oder manipulierte Belege schlagen sicher fehl. Ein verifiziertes Rollback bewahrt unzusammenhängende Einstellungen, während Abweichungen oder nicht verfügbare Fähigkeiten requires_user_action zurückgeben. Wiederholtes Setup und wiederholtes abgeschlossenes Rollback sind No-Ops, wenn der verifizierte Zustand bereits übereinstimmt.

Gemini CLI: manuelles MCP

Gemini CLI ist ein manueller MCP-Client-Pfad, keine verwaltete native thoth-mem-Integration. Fügen Sie diesen Eintrag zu ~/.gemini/settings.json hinzu:

{
  "mcpServers": {
    "thoth": {
      "command": "npx",
      "args": ["-y", "thoth-mem@latest", "mcp"]
    }
  }
}

Abruf- und Graph-Qualität bewerten

Das Repository enthält deterministische Bewertungsbefehle:

pnpm run eval:retrieval
pnpm run eval:kg
pnpm run eval:embedding-models -- --help

eval:retrieval setzt Signal-Beobachtungen plus Distraktoren und misst, ob der erwartete Speicher nahe der Spitze rangiert. Lesen Sie seinen Bericht als Sammlung von Signalen:

• Recall und Rang zeigen, ob die richtigen Beweise gefunden wurden und wie früh.

• Rauschen und Fallmischung zeigen Robustheit über direkte, umformulierte und repository-abgeleitete Beispiele.

• Kompression zeigt, wie viele Beweise vor der Kontextzustellung entfernt wurden; es ist ein Effizienzsignal, kein Beweis, dass der verbleibende Text korrekt ist.

• Spur- und Fallback-Beweise zeigen lexikalische, semantische Roh-/HyDE- und KG-Beteiligung, einschließlich ausstehendem oder degradiertem semantischem Verhalten.

• Abstammung und Herkunft zeigen, ob zurückgegebene Beweise ihrer Quelle zuordenbar bleiben.

eval:kg misst erwarteten Subjekt-Relation-Objekt-Recall, verbotene Tripel-Leckage, deterministisches Extraktionsverhalten und validierte optionale LLM-Anreicherung. Fehlende erwartete Fakten weisen auf Abdeckungslücken hin; verbotene Treffer weisen auf unsichere Graph-Erfindung hin.

Diese Bewertungen sind deterministische Entwicklungs-Gates über kuratierte und synthetische Fixtures. Sie sagen nicht jeden Produktionskorpus voraus, ersetzen keine menschliche Überprüfung, beweisen keine native Harness-Integration oder rechtfertigen für sich genommen die Aktivierung optionaler Community-Lesepfade. Vergleichen Sie die einzelnen Fälle und Fehlermeldungen, anstatt eine aggregierte Zahl als universelle Qualität zu behandeln.

Embedding-Profile und Modellvergleich

Semantische Embedding-Eingaben werden von einem versionierten Modellprofil formatiert. auto erkennt Nomic-, EmbeddingGemma- und Qwen3-Embedding-Modellfamilien-Aliase; unbekannte Modelle verwenden raw und erhalten keine abgeleitete asymmetrische Formatierung. Die öffentliche Konfiguration hat absichtlich kein globales task-Feld: Abrufabsicht und Abfrage-/Dokumentrolle werden intern für jede Eingabe zugewiesen, einschließlich HyDE-Antworten in Dokumentrolle.

{
  "embedding": {
    "provider": "lmstudio",
    "model": "text-embedding-embeddinggemma-300m",
    "baseUrl": "http://127.0.0.1:1234",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

Unterstützte Profilwerte sind auto, nomic, embeddinggemma, qwen3 und raw. THOTH_EMBEDDING_PROFILE und THOTH_EMBEDDING_NORMALIZE überschreiben gespeicherte Werte. Die aufgelöste Profilversion und das Normalisierungsflag sind Teil der Abstammung des semantischen Index. Eine Änderung dieser Werte markiert daher frühere Vektoren als veraltet und nutzt die bestehende idempotente Neuaufbau-Warteschlange.

Lokale Transformers.js-Inferenz kann sich für ein bestimmtes ONNX-Ausführungsgerät entscheiden:

{
  "embedding": {
    "provider": "transformers_local",
    "model": "onnx-community/embeddinggemma-300m-ONNX",
    "device": "dml",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

Unterstützte Gerätewerte sind auto, cpu, dml, cuda und coreml; cpu ist die Standardeinstellung. THOTH_EMBEDDING_DEVICE überschreibt den gespeicherten Wert von embedding.device. Mit der von Transformers.js verwendeten vorgefertigten Node-ONNX-Runtime zielt dml auf DirectML unter Windows, cuda auf unterstützte Linux-x64-CUDA-Installationen und coreml auf macOS. Ein explizit nicht verfügbares Gerät führt zu einem Fehler bei der Modellinitialisierung, anstatt stillschweigend auf CPU umzuschalten. auto delegiert die plattformspezifische Provider-Reihenfolge und das Fallback an Transformers.js, sodass sich das effektive Backend je nach Host oder Abhängigkeitsversion ändern kann.

Die Geräteauswahl betrifft nur transformers_local; Remote-Anfragen an Ollama und LM Studio ignorieren sie. GPU-Backends können einen deutlich langsameren Kaltstart haben und sind daher am nützlichsten für persistente MCP-Prozesse oder größere Embedding-Stapel. Das Gerät ist bewusst von der Abstammung des semantischen Index ausgeschlossen: Eine Änderung nur von embedding.device markiert vorhandene Vektoren nicht als veraltet und stellt keinen Neuaufbau in die Warteschlange.

Beispiele für Provider-Modelle:

Die lokale Ausführung von EmbeddingGemma verwendet sentence_embedding. Die lokale Qwen-Ausführung wendet die Retrieval-Anweisung nur auf Abfragen an und verwendet das zuletzt beachtete Hidden-State-Token für das Pooling. Alle Provider lehnen unvollständige, nicht endliche, Null- oder dimensional inkonsistente Stapel ab. LM-Studio-Antwortindizes werden validiert, und gültige, nicht in Reihenfolge befindliche Zeilen werden in die Eingabereihenfolge zurückversetzt; fehlende, doppelte oder ungültige Indizes werden abgelehnt. Während des Abrufs stufen diese Fehler die semantische Suche explizit herab, während lexikalische und KG-Suche fortgesetzt werden.

Führen Sie das Qualitätsgate für drei Modelle mit expliziten Modell-IDs und einem dauerhaften Ausgabepfad aus:

pnpm run eval:embedding-models -- --provider lmstudio --base-url http://127.0.0.1:1234 --nomic-model <nomic-id> --embeddinggemma-model <gemma-id> --qwen3-model <qwen-id> --output <result.json>

Das Gate erfordert, dass alle drei Ausführungen abgeschlossen werden und mindestens ein Kandidat die Recall@1/Recall@5/MRR-Schwellenwerte erfüllt, ohne eine Nomic-Metrik zu verschlechtern. Nomic ist der relative Vergleichsmaßstab, kein Kandidat, der den absoluten Schwellenwerten unterliegt. Wenn beide Kandidaten qualifiziert sind, wählen ein expliziter Qualitätswert und eine stabile Tie-Break-Reihenfolge den Gewinner. Ein fehlendes Modell, ein ungültiger Vektor, kein geeigneter Kandidat oder ein Fehler beim Schreiben des Berichts führt zu einem Exit-Code ungleich Null und behält die aktuelle Standardeinstellung bei.

Der aufgezeichnete LM-Studio-Lauf vom 2026-08-08 wählte EmbeddingGemma als ausgelieferten lokalen Standard. EmbeddingGemma und Qwen3 wurden beide mit Recall@1 1.00, Recall@5 1.00 und MRR 1.00 abgeschlossen, gegenüber Nomic mit 0.50, 1.00 und 0.7167; beide Kandidaten waren geeignet, und EmbeddingGemma gewann den exakten Qualitätsgleichstand durch die stabile lexikalische Profil-ID-Regel. Die mittlere Latenz im gespeicherten Entscheidungslauf betrug 190.5 ms für Nomic, 195 ms für EmbeddingGemma und 320.5 ms für Qwen3.

Die Dateigrößen von Qwen3 hängen vom Laufzeit-Artefakt ab:

Das Qwen3-Q8-Modell ist in Transformers.js 304.069.133 Bytes größer als EmbeddingGemma Q8 und in LM Studio 305.559.648 Bytes größer. Es verwendet außerdem native 1024-dimensionale Vektoren anstelle der 768 Dimensionen von EmbeddingGemma. Der Runner installiert oder erkennt keine Provider-Modelle im Namen des Betreibers.

Skalieren Sie das Retrieval-Rauschen, wenn Sie einen anspruchsvolleren lokalen Lauf wünschen:

$env:THOTH_RETRIEVAL_EVAL_NOISE='250'
pnpm run eval:retrieval

Erweiterte Operationen

• Führen Sie thoth-mem help aus, um die vollständige Liste der CLI-Befehle und Optionen zu erhalten.

• Öffnen Sie das lokale Dashboard unter http://localhost:7438/ und die OpenAPI-Dokumentation unter http://localhost:7438/docs.

• Verwenden Sie thoth-mem sync --dir=.thoth-sync und thoth-mem sync-import --dir=.thoth-sync für Git-freundliche Portabilität.

• repair-sync-journal (--project <name> | --all) --apply zeigt eine Vorschau an und bindet seinen Reparaturstapel intern. Das optionale --expected-fingerprint bleibt verfügbar, wenn ein externer Workflow bereits eine Vorschau-Bindung hat.

• prune-operation-traces (--project <name> | --all) --apply bindet ebenfalls einen Aufbewahrungsstapel intern. Fügen Sie --until-complete hinzu, um den anfänglich begrenzten Rückstand mit einem festen effektiven Zeitpunkt und neuen späteren Fingerabdrücken zu verarbeiten. Eine extern bereitgestellte Bindung muss sowohl --expected-fingerprint als auch --effective-now enthalten.

• compact-database [--data-dir <path>] führt eine schreibgeschützte Vorschau durch. Fügen Sie --apply erst hinzu, nachdem Sie die Schätzungen zu wiedergewinnbarem Speicherplatz und Kapazität geprüft haben. --apply kann das Doppelte der größeren der physischen und logischen Datenbankgrößen erfordern, kann durch andere SQLite-Clients blockiert werden und meldet Erfolg erst nach Integritäts-, Fremdschlüssel-, Schema-, Dauerzähl- und WAL-Prüfungen. Es verwendet den von SQLite verwalteten Checkpoint und VACUUM; es verspricht kein Rollback nach einer festgeschriebenen Komprimierung.

• Die Komprimierung erfolgt niemals automatisch. Die Ausführung gegen Live-Daten erfordert eine separate Autorisierung des Betreibers; Repository-Tests verwenden nur Wegwerf-Datenbanken.

• Prüfen Sie config.schema.json für gespeicherte Konfiguration und umgebungsgestützte Einstellungen.

• Daten liegen standardmäßig in ~/.thoth/thoth.db; überschreiben Sie das Datenverzeichnis mit THOTH_DATA_DIR oder --data-dir.

Die semantische Indizierung ist nicht blockierend. Wenn Embeddings oder sqlite-vec nicht verfügbar sind, bleibt der Abruf über unterstützte lexikalische und grafische Evidenz nutzbar und meldet den herabgestuften Pfad, anstatt stillschweigend semantischen Erfolg zu behaupten.

Entwicklung

pnpm install
pnpm run integration:verify
pnpm run build
pnpm test

Lizenz

MIT