Vollständige Dokumentation -- Anleitungen, Tool-Referenz, Architektur und Wartung unter cachorro.space

mcp-memory

Ein Drop-in-Ersatz für Anthropics MCP Memory Server -- mit SQLite-Persistenz, Vektor-Embeddings, semantischer Suche und Limbic Scoring für dynamisches Ranking.

Warum? Der ursprüngliche Server schreibt bei jedem Vorgang den gesamten Wissensgraphen in eine JSONL-Datei, ohne Sperren oder atomare Schreibvorgänge. Bei gleichzeitigem Zugriff (mehrere MCP-Clients) führt dies zu Datenbeschädigungen. Dieser Server ersetzt dies durch eine ordnungsgemäße SQLite-Datenbank.

Funktionen

• Drop-in-kompatibel mit den 8 MCP-Tools von Anthropic (gleiche API, gleiches Verhalten)

• SQLite + WAL -- sicherer gleichzeitiger Zugriff, keine beschädigten JSONL-Dateien mehr

• Semantische Suche via sqlite-vec + ONNX-Embeddings (94+ Sprachen)

• Hybride Suche (FTS5 + KNN) -- kombiniert Volltext-BM25 und semantische Vektorsuche mittels Reciprocal Rank Fusion. Findet Entitäten durch exakte Begriffe oder semantische Ähnlichkeit -- oder beides gleichzeitig.

• Limbic Scoring -- dynamisches Re-Ranking mit Salienz, zeitlichem Zerfall, Ko-Auftretenssignalen und hybriden Such-Scores. Transparent für die API.

• Semantische Deduplizierung -- automatischer similarity_flag bei neuen Beobachtungen, wenn die Kosinus-Ähnlichkeit >= 0,85 ist (mit Containment-Scoring für asymmetrische Textlängen)

• Konsolidierungsberichte -- schreibgeschützte Gesundheitschecks für Split-Kandidaten, markierte Beobachtungen, veraltete Entitäten und große Entitäten

• Verbesserter Aktualitätszerfall -- entity_access_log-Tracking mit ALPHA_CONS=0.2 Mehrtages-Konsolidierungssignal

• Containment-Fix -- korrekte Handhabung asymmetrischer Textlängen (Verhältnis >= 2.0) beim Deduplizierungs-Scoring

• Beobachtungsarten -- semantische Klassifizierung von Beobachtungen (hallazgo, decision, estado, spec, metrica, metadata, generic)

• Beobachtungs-Ablösung -- explizite Ersetzungskette: neue Beobachtungen können alte ablösen, die dann als abgelöst markiert werden

• Entitätsstatus -- Lebenszyklus-Tracking: activo, pausado, completado, archivado (mit statusbewusster Such-De-Boostung)

• Beziehungskontext + Gültigkeit -- Beziehungen tragen optionalen Kontext, active/ended_at-Felder für zeitliche Gültigkeit

• Automatische inverse Beziehungen -- contains/parte_de-Paare werden automatisch erstellt

• Reflektionen -- unabhängige narrative Ebene: freier Text, der an Entitäten/Sitzungen/Beziehungen/global angehängt ist, mit Autor- und Stimmungs-Metadaten, durchsuchbar via semantischer + FTS5-Hybridsuche

• Leichtgewichtig -- ~500 MB gesamt gegenüber ~1,4 GB bei ähnlichen Lösungen

• Migration -- Ein-Klick-Import aus dem JSONL-Format von Anthropic

• Zero-Config -- funktioniert sofort, optionaler Modell-Download für semantische Suche

Schnellstart

1. Zur MCP-Konfiguration hinzufügen

{
  "mcpServers": {
    "memory": {
      "command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

Oder lokal klonen und ausführen:

{
  "mcpServers": {
    "memory": {
      "command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
    }
  }
}

2. Semantische Suche aktivieren (optional)

cd /path/to/mcp-memory
uv run python scripts/download_model.py

Dies lädt ein mehrsprachiges Satzmodell (~465 MB) nach ~/.cache/mcp-memory-v2/models/ herunter. Ohne dieses funktionieren alle Tools einwandfrei -- nur search_semantic ist nicht verfügbar.

3. Bestehende Daten migrieren (optional)

Wenn Sie eine JSONL-Datei von Anthropic MCP Memory haben, verwenden Sie das migrate-Tool oder rufen Sie es direkt auf:

uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"

MCP-Tools

Kern (Anthropic-kompatibel)

Suche & Analyse

Entitätsverwaltung

Reflektionen

Entitätstypen

8 kanonische Typen:

Beobachtungsarten

Semantische Klassifizierung für Beobachtungen:

Beziehungstypen

4 Kategorien:

Inverse Beziehungen werden automatisch für contiene/parte_de-Paare erstellt.

Architektur

server.py (FastMCP)  <--  storage.py (SQLite + sqlite-vec + FTS5)
                               |
                         embeddings.py (ONNX Runtime)
                               |
                         sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
                         (384d, multilingual, cosine similarity)
                               |
                         scoring.py (Limbic Scoring + RRF)
                         salience . temporal decay . co-occurrence

• Speicher: SQLite mit WAL-Journaling, 5-Sekunden-Busy-Timeout, CASCADE-Löschungen

• Embeddings: Singleton-ONNX-Modell, das einmal beim Start geladen wird, L2-normalisierte Kosinus-Suche

• Limbic Scoring: Re-ranked hybride (KNN + FTS5) Kandidaten unter Verwendung von Wichtigkeitssignalen, zeitlichem Zerfall, Ko-Auftretensmustern und RRF-Scores -- transparent für die API

• Nebenläufigkeit: SQLite verwaltet Sperren intern -- kein fcntl, keine fs-Konflikte

• Reflektionen: Parallele FTS5 (reflection_fts) und Vektor (reflection_embeddings) Indizes für die narrative Ebene, durchsucht über dieselbe RRF-Hybrid-Pipeline

Funktionsweise

Jede Entität erhält einen Embedding-Vektor, der aus ihrem Text mittels einer Head+Tail+Diversity-Auswahlstrategie generiert wird (Budget: 480 Token):

"{name} ({entity_type}) | {obs1} | {obs2} | ... | Rel: type -> target; ..."

Wenn Sie search_semantic aufrufen, läuft die Pipeline parallel:

1. Semantisch (KNN) -- die Abfrage wird kodiert und mittels sqlite-vec mit Entitätsvektoren verglichen

2. Volltext (FTS5) -- die Abfrage wird gegen einen BM25-Index durchsucht, der Namen, Typen und Beobachtungsinhalte abdeckt

3. Zusammenführung (RRF) -- Ergebnisse aus beiden Zweigen werden mittels Reciprocal Rank Fusion kombiniert (score(d) = Sum 1/(k + rank))

Die zusammengeführten Kandidaten werden dann von der Limbic Scoring-Engine neu bewertet, die Folgendes berücksichtigt:

• Salienz -- häufig aufgerufene und gut vernetzte Entitäten werden höher bewertet

• Zeitlicher Zerfall -- kürzlich verwendete Entitäten bleiben aktuell; unberührte Entitäten verblassen

• Ko-Auftreten -- Entitäten, die oft zusammen erscheinen, verstärken sich gegenseitig

Die Ausgabe enthält limbic_score, scoring (Aufschlüsselung nach Wichtigkeit/Zeit/Ko-Auftreten) und optional rrf_score, wenn FTS5 Ergebnisse beisteuert.

Für vollständige technische Details, siehe DOCUMENTATION.md -- enthält die Scoring-Formel, RRF-Konstanten, Schema-DDL und Architekturdiagramme.

Tests

uv run pytest tests/ -v

285+ Tests in 15 Testdateien, die alle Tools, Embeddings, Scoring und Grenzfälle abdecken. Null Regressionen.

Anforderungen

• Python >= 3.12

• uv (Paketmanager)

Abhängigkeiten

Lizenz

MIT