origin-memorycore

English | 简体中文

MemoryCore ist eine Speicher-Governance-Ebene für LLM-Agenten.

Agenten sammeln schnell speicher an – Präferenzen, Fakten, Entscheidungen – und Speicher, der nicht gepflegt wird, verschlechtert sich leise: Duplikate häufen sich, veraltete Fakten bleiben bestehen, die Hot-Ebene füllt sich und lehnt irgendwann Schreibzugriffe ab. MemoryCore verhindert genau das.

Es funktioniert als zweistufiges Speichersystem:

• Hot-Ebene – häufig verwendetes Verhaltenswissen (Präferenzen, Regeln, Korrekturen) in einer schnellen lokalen Datei, jederzeit im Kontext.

• Cold-Ebene – selten verwendete Fakten, automatisch ausgelagert und in einer prozessinternen SQLite-Engine gespeichert (oder in einem entfernten Speicherdienst, sofern einer konfiguriert ist).

Zwischen beiden hält ein Governance-Kern den Speicher gesund:

• Deduplizierung beim Schreiben – ähnliche Fakten werden vor der Speicherung zusammengeführt, nicht dupliziert.

• Kapazitätskontrolle – weiche/harte Schwellenwerte lösen einen Overflow aus, bevor die Hot-Ebene voll ist, sodass sie nie Schreibzugriffe ablehnt.

• Governance der Cold-Ebene – periodische Dedup-/Bereinigungsläufe halten die Cold-Ebene auffindbar, während sie wächst.

• Papierkorb – gelöschte Einträge erhalten eine 30-tägige Gnadenfrist; ein wiedergeholter Eintrag aus dem Papierkorb wird wiederhergestellt.

Das Ergebnis: Die Hot-Ebene bleicht im Budget, die Cold-Ebene bleibt auffindbar, und der Speicher bleibt wartbar, egal wie viel der Agent ansammelt.

Basierend auf dem MCP (Model Context Protocol) streamable-http / stdio-Standard. Funktioniert mit jedem MCP-Client, getestet mit Hermes Agent.

Features

• Speicher-Governance (das Kernstück) – drei Schutzschichten für die Datenintegrität der Cold-Ebene:

  • Cold-Schreibender: Vor dem Schreiben in die Cold-Ebene prüft ein semantischer Recall plus LLM-Richter nach Duplikatet und aktualisiert vorhandene Einträge, anstatt neue redundante anzulegen.

  • Kapazitäts-Hard-Gate: Die Cold-Ebene setzt ein Soft-Limit (6000 Einträge, löst einen Wartungslauf aus) und ein Hard Law (10000 Einträge, erzwingt Wartungsschleifen) – das verhindert unbegrenztes Wachstum.

  • Papierkorb (trash_store.py): Gelöschte Einträge der Cold-Ebene werden mit 30 Tagen Ablaufzeit nach ~/.memorycore/trash.json verschoben. Wird ein verworfener Eintrag mit frischen semantischen Nachweisen wieder abgerufen, stellt ihn das wieder her („recall to revive“).

• Cold-/Hot-Routing – jeder Schreibvorgang wird klassifiziert: hohe Wichtigkeit oder präferenzartig → Hot (lokal); selten genutzter Fakt → Cold (remote); veralteter Statusdatensatz → verworfen.

• Sechs-Schritte-Overflow – Kapazitätsbasis → Dedup → Filtern von Veraltetem → Merge → sicherer Schreibvorgang (zuerst Cold, dann lokal löschen) → Verifizierung.

• Wartung der Cold-Ebene – Dedup-Merge, Bereinigung des Veralteten, Konfliktauflösung, Prüfung der Embedding-Integrität.

• Kapazitätskontrolle – weicher Schwellwert (ein Overflow vor dem Schreiben) / harter Schwellwert (erzwingt Overflow) / Zielverhältnis. Standardwerte: 60 % / 80 % / 40 % eines Limits von 5000 Zeichen.

• Sanfte Degradation – ist die Cold-Ebene nicht erreichbar? Schreibvorgänge schlagen laut fehl (niemals still verworfen), der Overflow behält lokale Einträge, und der Health-Check liefert den lokalen Status mit cold.error.

• Null Kernmodifikation – Das System ist als Drop-in-Compagnon entwickelt, damit die eingebauten Speicher-Tools deines Agenten weiterhin funktionieren.

Related MCP server: AI Long-Term Memory MCP Server

Architektur

┌─────────────────────────────── Mac / local ──────────────────────────────┐
│  LLM agent (e.g. Hermes)                                                 │
│    │  MCP client                                                         │
│    ▼                                                                     │
│  MemoryCore MCP server                                                   │
│    ├─ local_store.py        hot tier: MEMORY.md / USER.md (chars-based)  │
│    ├─ classifier.py         cold/hot/stale routing rules                 │
│    ├─ overflow.py           six-step overflow                            │
│    ├─ maintenance.py        cold-tier governance                         │
│    └─ cold_store_client.py  →  LocalBackend (SQLite, in-process)         │
│                               or RemoteBackend (MCP streamable-http)     │
└──────────────────────────────────────────────────────────────────────────┘
                     LocalBackend: mnemosyne-memory (in-process engine)
                     RemoteBackend: remote MCP memory service

Optional (Hermes Agent only): hermes-plugin/memorycore-prefetch
  ┌───────────────────────────────────────────────────────────────────────┐
  │ MemoryProvider plugin (single-model qwen3, enabled by default)        │
  │   system_prompt_block → static index (always active)                  │
  │   prefetch → ColdStoreClient.recall_results(top_k=20)                 │
  │            → dense ranking → session + hot-tier dedup → top-5         │
  │   Disable: MEMORYCORE_PREFETCH_ENABLED=0                              │
  └───────────────────────────────────────────────────────────────────────┘

Schnellstart

Voraussetzungen

• ollama – Embedding-API (Installation: https://ollama.com)

• qwen3-embedding:0.6b – empfohlenes Embedding-Modell (1024-dimensional)

# Install ollama (macOS/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# Pull the embedding model
ollama pull qwen3-embedding:0.6b

Installieren & Ausführen

pip install "origin-memorycore @ git+https://github.com/moonandecho/origin-memorycore.git"

# That's it! MemoryCore runs with ollama for embeddings:
#   - Hot tier:  MEMORY.md / USER.md (default ~/.hermes/memories)
#   - Cold tier: SQLite via mnemosyne-memory (default ~/.memorycore/data/)
#   - Embedding: qwen3-embedding:0.6b via ollama (http://localhost:11434/v1)
python -m memorycore.server          # stdio transport (default)

Layout des Datenverzeichnisses (alles unter ~/.memorycore/):

~/.memorycore/
├── data/          # SQLite database (MNEMOSYNE_DATA_DIR)
└── ...

Überschreiben mit MNEMOSYNE_DATA_DIR.

Modellwechsel

Das Standard-Embedding-Modell ist qwen3-embedding:0.6b (1024-dim). Verwende ein beliebiges ollama-Modell, indem du Umgebungsvariablen setztest:

export MEMORYCORE_EMBED_URL="http://localhost:11434/v1"
export MEMORYCORE_EMBED_MODEL="nomic-embed-text"   # or your preferred model

Oder siehe auf eine beliebige OpenAI-kompatible Embedding-API:

export MEMORYCORE_EMBED_URL="https://api.openai.com/v1"
export MEMORYCORE_EMBED_MODEL="text-embedding-3-small"

Registriere es in deinem MCP-Client (Beispiel für Hermes Agent config.yaml):

mcp_servers:
  memorycore:
    command: python
    args: ["-m", "memorycore.server"]

Remote-Modus (optional)

Falls du einen gemeinsamen Remote-Mnemosyne-MCP-Dienst der lokalen Engine bevorzugst, setze MEMORYCORE_COLD_BACKEND=remote:

export MEMORYCORE_COLD_BACKEND=remote
export MNEMOSYNE_URL="http://your-memory-service:9000/mcp"
python -m memorycore.server

Verfügbare Tools:

Hermes-Integration – Per-Turn-Prefetch

Der MCP-Server ist client-agnostisch. Für Hermes Agent gibt es ein optionales Companion-Plugin, das einen zweck-Kanal-Zugriff auf die Cold-Ebene bietet:

Zwei-Kanal-Design

• Statistischer Index-Kanal (immer aktiv, null Overhead) – ein Systemprompt-Block mit verfügbaren Themen, der eine Hinweis gibt, memorycore_recall(query) für den Abruf nach Bedarf zu verwenden (konfigurierbar über MEMORYCORE_INDEX_TOPICS, kommagetrennt).

• Per-Continue-Prefetch-Kanal (standardmäßig aktiviert) – ruft jede Durchgang die Cold-Ebene ab, rankt nach Dense Score und injiziert die Top-5 in den Kontext, Abschluss, der Agent relevante Inhalte vor dem Reden „remember“. Set MEMORYCORE_PREFETCH_ENABLED=0, um zu deaktivieren und nur On-Demand-Abruf zu verwenden.

Prefetch-Pipeline

query → preprocess → cold-tier recall (20 candidates)
  → dense ranking (qwen3) → top-5
  → session dedup → hot-tier dedup → inject into context

MemoryCore verwendet eine Single-Modell-qwen3-Architektur (kein Reranker). Dense Scores von qwen3 werden für das relative Ranking innerhalb eines Batches verwendet; es gibt keinen absoluten Schwellwert – die Top-5 Kandidaten nach Dense Score werden nach dem Dedup immer injiziert.

Sanfte Degradation

Wenn ollama nicht erreichbar ist (nicht installiert, nicht gestartet oder das Modell nicht gezogen), gibt den Prefetch still einen leeren String zurück. Das Orientations, es läuft ohne injizierten Speicher weiter und es wird kein Fehler an den Benutzer ausgegeben. Ein Log auf DEBUG-Ebene zeichnet den Fehler der Abfrage auf.

Einsatz (Hermes Agent)

# 1. install origin-memorycore (provides the cold tier + ColdStoreClient)
pip install "origin-memorycore @ git+https://github.com/moonandecho/origin-memorycore.git"

# 2. put the plugin in Hermes' user plugin dir
mkdir -p ~/.hermes/plugins
cp -r hermes-plugin/memorycore-prefetch ~/.hermes/plugins/

# 3. activate (takes effect next session)
hermes config set memory.provider memorycore-prefetch

Drei Positionen nach der Installation:

Plugin-Konfiguration

Anforderungen & Hinweise:

• Hermes-spezifisch: Das Plugin importiert Hermes-Laufzeitmodule (agent.memory_provider) und funktioniert nicht als eigenständiges Paket – es ist die Hermes-Integrationsseite von MemoryCore. Vollständige Details: hermes-plugin/memorycore-prefetch/README.md.

• Jeder Abruf hat ein 5-Sekunden-Timeout; Fehler verfallen still zu einer leeren Injection und blockieren niemals die Unterhaltung.

Governance der Hot-Ebene

Die Hot-Ebene (MEMORY.md / USER.md) wird in jedem Durchgang in den Kontext injiziert, also muss sie klein und aktuell bleiben. MemoryCore setzt drei Mechanismen zusätzlich zum Sechs-Schritte-Overflow ein, sodass historische Aufzeichnungen deterministisch in die Cold-Ebene entlassen werden statt sich anzustauen:

Alterung der Metadaten in der Hot-Ebene

• • *Sidecar-Metadaten: MEMORY.meta.json / USER.meta.json liegen neben den .md-Dateien, abgedeckt durch den SHA-256-Fingerprint des Eintragsinhalts. Atomische Schreibvorgänge plus Datei-Locker halten sie prozessübergreifend sicher; das mit § getrennte .md-Format bleibt unberührt, damit die Speicher-Tools des Hosts wie gehabt weiterlaufen.

• • Jeder Eintrag wird als state (historische Entscheidungen / Statusrecords) oder rule (Vorgaben / Präferenzen) Typed:

  • state: wird 7 Tage nach dem Schreiben in die Cold-Ebene überführt (konfigurierbar: STATE_TTL_DAYS)

  • rule: wird nie altersüberführt; nach 30 Tagen ohne Update werden lange Einträge (>200 Zeichen) zu Kandidaten für die LLM-Kompression (konfig. RULE_COMPRESS_DAYS). Regeln erhalten zusätzlic einen Bestandteil, durch das unten beschriebene Invalidierungs-Leiter – ohne eine aktive Präferenz jemals falsch zu verrenten.

• Wenn sich der Inhalt eines Eintrags ändert, ändert sich sein Schlüssel – der nächste Reconcile rekommt den neuen Inhalt und sammelt verwaiste Schlüssel gelöschten.

Doppelte Schreibe-Eintrags-Governance

• store_fact-Schreibeintrag: Inhalte, die wie ein abgeschlossener Entscheidungs/Status-Rekord aussehen (ein Datum plus Fertigstellmerkmale wie z. B. 拍板/已配置, ohne Verhalten) werden direkt in die Cold-Ebene geleitet – sie gelangen nie in die Hot-Ebene.

• Plugin-on_memory_write Direktschreibkanal: Nach jedem Add/Replace eines eingebauten Memorytools wird der Eintrag sofort typisiert. state-Einträge migrieren im Hintergrund in die Cold-Ebene (Dedup → Cold-Schreibvorgang bestätigt → aus der Hot-Ebene entfernt; bei Cold-Fehlerfälle bleibt der Eintrag mit einem Stempel als 7-Tage-Rückstützableger). Das läuft unabhängig von Schwellwerten. Ein Worker-Thread der Wartungsartige bond (Größe 128); ist die Queue voll, wird der Eintrag übersprungen und der nächste Overflow-Reconcil ihn als Backstop abstellt.

Metadaten-First-Overflow

Jeder Overflow-Lauf gleicht zuerst Metadaten von (stempelt nicht typisierte Legacy- Einträge und sammelt Waisen), et al.clare Einträge danach auf Basis der Metadaten. Keywords bleiben nur noch als Fallback für untypisierte Einträge. Ein Sidecar-Fehler degradiert auf den Keyword-Pfad und blockiert den Overflow nie.

Regel-Invalidierungs-Signale (abgestufter Schutz)

Eine Hot-Ebene aus reinen rule-Einträgen hat konstruktionsbedingt keinen ausstieg („niemals eine Präferenz abzusenken“). Daher würden kurze, nie bearbeitete Regeln sonst für immer bleiben und schließlich die Hot-Ebene füllen. MemoryCore schließt diese Lücke mit einer Druck-Leiter (pressure ladder): Jeder Overflow-Lauf misst die reale Nutzung (Basline) und öffnet bei steigendem Druck tiefere Ausgänge (die Reaktion). Fünf beobachtbare Signale die Eignung und Reihenfolge – Druck entscheidet, ob gehandelt wird:

Abgestufter Schutz: A-Klassen-Metaregeln (Verhaltens- / Interaktions- / Schreibstil-Grundsätze), Red-Line-Regeln und Einträge mit Wichtigkeit ≥ 0,9 werden niemals von S2/S4/S5 erfasst – sie werden nur zusammengeführt oder komprimiert. Stub-Zeiger haben ihren eigenen Lebenszyklus (GC nach dem Ältesten zuerst bei hartem Druck; das Cold-Tier wird nie angelangt), so dass Zeiger die Hot-Ebene kein zweites Mal füllen können. Jede Ausmusterung erfolgt Cold-Write-First: Der lokale Eintrag wird erst geändert, nachdem das Cold-Tier die Aufnahme bestätigt hat; bei einem Fehler bleibt das Original erhalten. Wenn ein Signal nicht verfügbar ist (kein Aktivitätskostenpflichtig, kein LLM-Systemschlüssel), fällt die Signalleiter auf das bisherige Verhalten zurück, statt zu raten.

Konstanten (memorycore/core/config.py): RULE_RETYPE_DAYS=60, RULE_STUB_IDLE_DAYS=45, ACTIVITY_WINDOW_DAYS=30, MAX_STUB_PER_RUN=3, STUB_MAX_CHARS=40, IMPORTANCE_PROTECT=0.9.

Health-Check: memorycore_memory_auditit

Ein schreibgeschütztes Werkzeug, das jeden Hot-Tier-Eintrag mit Typ, Alter, Ruhestandsliste und Keep/Sink-Einstufung auflistet – der Observabilittskern zur Diagnose eines Überlaufs, der nichts zum Versenken findet.

Skaltest- und Optimierungsergebnisse

MemoryCore wurde bei einer Cold-Tier-Größe von zehntausend Einträgen stimmungsgeprüft und abrufoptimiert (isolierte Testumgebung, kein Kontakt mit Produktionsdaten, reproduzierbare Ergebnisse).

Schreiben & Kapazität

Abfrage-Latenz – Median 48 ms bei top_k=5; Zehntausend-Eintragungs-Skala entspricht der Hundert-Eintragungs-Skala, keine Latenzregression.

Recall-Qualität – drei Prüfungen:

1. Übereinstimmung (Selbst-Re-Recall): 20/20 Treffer in Top-1 – exakte Übereinstimmung ist intakt.

2. Rauschunterdrückung (unabhängige Abfragen): mittlere Top-1-Dichte-Score 0,056, die Meisten liefern 0,0 – unzugehörige Textinhalte sick seltener ins Relationn.

3. Kurzabfrage-Recall (vor → nach) – das wichtigste Optimierungsergebnis:

Was optimiert wurde: Bei hoher Themenichte schob die feste Kandidatenbeschnitt k=max(top_k, 20) detaillierte Erinnerungen aus dem Kandidatenpool, sodass Kurzabfragen sie nicht mehr abrufen konnte. Der Fix erweitert den Kandidatenbeschnitt auf k=max(top_k*4, 300) und erweitert den Kandidaten intern am Recall-Eingang, bevor der Rückgabewert beschnitten wird – jeder Recall-Kanal (Prefetch pro Umdrehung und On-Demand-Rabruf) profitiert von einem einzigen Fix. Der Fach bleibt auf die Recall-Phase beschränkt; die Ranking-Logik ist unverändert, das Verhalten ist sogar predict-est und umkehrbar.

Hinweis: Die Tests liefen gegen eine synthetische 10.000-Einträge-Datenbank (80 „golden“ Erinnerungen + 9.920 Füll-Erinnerungen im Tageslogton, gleiche Konfiguration wie Produktionsumgebung); Produktionsdaten wurden nicht angefasst.

Hinweise für sqlite-vec-Benutzer

Wenn Sie die sqlite-vec-Vektorindizierung für das mnemosyne-Cold-Tier aktivieren, beachten Sie, dass beam.py's _wm_vec_search_sqlite eine Raw-Similaritätsformel sim = 1 - distance / (2 * EMBEDDING_DIM) verwendet, die float32-Abstände auf ~1,0 kollabieren lässt, wodurch der Dynamische Threshold praktisch wirkungslos wird (alle Ergebnisse bestehen).

Patch: Ersetzen Sie die Formel im Float32-Zweig durch sim = 1 - d² / 2 – das liefert die exakte Kosinus-Ähnlichkeit für normalisierte Vektoren und stellt das korrekte Schwellwertverhalten wieder her.

Cold-Store-Vertrag

Jeder Dienst, der diese fünf MCP-Werkzeuge anbietet, kann als Cold-Tier dienen:

Siehe examples/cold-store-contract.md für den vollständigen Vertrag und einen Referenzclient.

Konfiguration

Die Kapazitätskonstanten liegen in memorycore/core/config.py (CHAR_LIMIT_*, SOFT_THREESHOLD, HARD_THESHOLD, TARGET_RATIO).

Funktionsweise

1. Schreiben – store_fact klassiert den Inhalt:

   • Wichtigkeit ≥ 0,8 oder passend zu Hot-Keywords (Präferenzen / Regeln / Korrekturen / Red-Line-Regeln) → hot, bleibt lokal

   • Veraltete Zeichen (kurze Einträge, z. B. „已修复 / done“) → verworfen (nicht migriert)

   • alles andere → cold, direkt in den Remote-Dienst perpersisted

2. Überlauf – wenn die Hot-Nutzung die Soft-Schwelle überschreitet, werden selten häufig verweisene Nutzung in die Cold-Ebene migriert; bei Hard-Schwellwert wird bis zum Ziellevel erzwungen überlaufen. Die Reihenfolge ist immer: erst in Cold-Tier schreiben, verifizieren, dann lokal löschen – nichts geht verloren, wenn die Cold-Bühne fehlschlägt.

3. Wartgen – ein periodischer Durchlauf über das Cold-Tier führt Duplikte zusammen, entfernt veraltete Einträge, löst Konflikte und prüft die Embedding-Integrität.

License

MIT © 2026 moonandecho

Drittanbieter-Lizenzen

• mnemosyne-memory – MIT, von AxDSan. Die In-Prozess-Speicher-Engine, die von LocalBackend verwendet wird.

• MCP Python SDK – MIT.

• ollama – MIT. Lokaler Embedding-API-Service.

• qwen3-embedding – Apache-2.0, von Alibaba Cloud. Standard-Embedding-Modell (nicht enthalten; wird über ollama pullt).