realMemory

Eine persistente Speicherschicht für LLM-Agenten mit kontinuierlichem Lernen: ein lokaler „hippokampaler“ Speicher, der ohne Neuindizierung schreibt, über Trace-Dynamik vergisst und Episoden während des „Schlafs“ zu Semantik konsolidiert.

Status: v0.4 — ein einziger SQLite-Speicher, der von allen Prozessen gemeinsam genutzt wird, globale/Projekt-Speicherbereiche, hybride FTS5-Suche, Schwellenwerte an realen Texten kalibriert.

Die Idee in Kürze

Das LLM bleibt eingefroren („Kortex“). realMemory ist ein separates veränderbares Modul („Hippokampus“):

• Novelty-Gate-Schreibvorgänge: Ein bekanntes Faktum wird potenziert, ein verwandtes wird verknüpft, ein neues erhält eine neue Trace. Umformulierungen stapeln sich nie.

• Gemeinsamer + projektbezogener Speicher: Jede Trace trägt einen Scope (global oder einen Projektnamen); recall sieht das aktuelle Projekt plus global und vermischt niemals Kontexte.

• Vergessen durch Trace-Dynamik: Die Retention jeder Trace zerfällt exponentiell, Verstärkungen verlängern ihre Lebensdauer, ausreichend verstärkte Episoden werden zu semantischen Traces befördert (langsamer Zerfall). Die Vergessenskurve ist eine Eigenschaft der Synapse, kein Cron-Job.

• Ein assoziativer Graph gratis: Alles, was zusammen abgerufen wurde, wird durch Plastizität gebunden (eine STDP-ähnliche Regel) — Multi-Hop-Traversierung entsteht aus Nutzungsstatistiken, nicht aus LLM-Entitätsextraktion.

• Hybrider Abruf: Die Exakt-Token-Suche (FTS5) ergänzt Embeddings — Fehler-IDs, Paketnamen und Codes werden auch bei niedriger Kosinus-Ähnlichkeit gefunden.

• Schlaf: Offline-Konsolidierung committet Eligibility-Traces, lässt schwache Verknüpfungen zerfallen/beschneidet sie und befördert Status. Der gesamte Zustand lebt in einer SQLite-Datenbank: Ein MCP-Server und Hooks laufen gleichzeitig, ohne Daten zu verlieren.

Related MCP server: Cortex

Schnellstart

pip install -e ".[dev]"
pytest                # full core test suite
python -m realmemory.eval.bench_recall --facts 1500 --queries 200   # synthetic
python -m realmemory.eval.bench_real                                # real-text (fastembed)

from realmemory import Hippocampus, MemoryConfig

hippo = Hippocampus.open("./rm_data", config=MemoryConfig.dev())
hippo.remember("The project uses PostgreSQL 16 with alembic migrations",
               scope="myproject")            # a project-scoped fact
hippo.remember("The user prefers concise answers") # global by default

packet = hippo.recall("which database does the project use?", scope="myproject")
for item in packet.items:
    print(f"[{item.confidence:.2f}] ({item.source}) {item.text}")
if packet.abstained:
    print("no trustworthy memories")     # abstention instead of hallucination

hippo.consolidate()   # "sleep": commit traces, decay weak links

Lokaler Embedder

Standardmäßig verwendet der Kern einen deterministischen HashingEmbedder (keine Modelle). Der lokale semantische Embedder für den Produktionsbetrieb ist fastembed (ONNX Runtime, CPU):

pip install 'realmemory[local]'

• Modell: paraphrase-multilingual-MiniLM-L12-v2, dim=384, Russisch+Englisch.

• Modell-Cache: ~/.cache/realmemory/fastembed (~240 MB), wird einmal heruntergeladen.

• Gemessene Last: ~580 MB Prozess-RAM; ~65–75 ms pro Text auf der CPU; ein vollständiger Abruf ≈ 77 ms. Für den Agenten unsichtbar.

• Die Asymmetrie wird berücksichtigt: Fakten werden mit embed() enkodiert, Abfragen mit embed_query().

• Die Gate-Schwellenwerte sind pro Modellanisotropie kalibriert: Das Schwellenwertprofil liegt in FastEmbedProvider.recommended_thresholds, wird beim Serverstart angewendet und ist aus dem Realtext-Benchmark abgeleitet (siehe unten).

Anbindung an ZCode / Claude Code (MCP)

Registrieren Sie einen Stdio-Server im Benutzerbereich in Ihrer Client-Konfiguration:

"realmemory": {
  "type": "stdio",
  "command": "/path/to/venv/Scripts/python.exe",
  "args": ["-m", "realmemory.api.mcp_server",
           "--path", "/path/to/rm_data",
           "--embedder", "local"]
}

Agent-Tools (als kognitive Aktionen benannt): recall(query,k,project) · memorize(text,kind,related_ids,project) · reflect(memory_ids,reward) · revise(old_id,new_text) · introspect() · dream_log().

Gemeinsamer + projektbezogener Speicher: Jede Trace ist mit einem Scope versehen — global (Präferenzen, Identität) oder ein Projektname. Das Projekt wird automatisch erkannt (REALMEMORY_PROJECT → ZCODE_PROJECT_DIR → aktuelles Verzeichnis mit .git); es kann auch explizit über das Argument project oder --project übergeben werden. recall durchsucht das aktuelle Projekt + global; andere Projekte lecken nie hinein.

Eine vollständige Namensraum-Isolation zwischen getrennten Gehirnen ist über Hippocampus.open(path, namespace=...) / --namespace verfügbar.

Die Datenbank speichert eine Embedder-Markierung (db_meta) und weigert sich, mit einer anderen geöffnet zu werden — alte und neue Vektoren sind per Kosinus nicht vergleichbar.

Automatisierung: Agenten tatsächlich dazu bringen, es zu nutzen

Drei Mechanismen, die standardmäßig installiert sind:

1. Skill / Anweisungen, die beschreiben, wann recall / memorize / reflect verwendet werden sollen, geladen in jeden Sitzungskontext.

2. SessionStart-Hook → python -m realmemory.hook_cli brief — injiziert einen kurzen Speicherzustand: semantische Fakten und dauerhafte episodische Traces des aktuellen Projekts + global, ~600-Zeichen-Budget.

3. Stop-Hook → python -m realmemory.hook_cli sleep — Konsolidierung nach jeder Antwort; wird durch den Datenbankzustand gesteuert (überspringt, wenn sich seit dem letzten Schlaf nichts geändert hat). Dauert ~0.3 s und lädt das Embedder-Modell nicht.

Hooks und der MCP-Server laufen gefahrlos gleichzeitig: Der gesamte Zustand liegt in SQLite, gleichzeitige „Schlaf“-Läufe werden durch eine Transaktion serialisiert.

Betrieb

• Backups: Vor jedem „Schlaf“ wird die Datenbank in <store>/backups/ kopiert (konsistente SQLite-Backup-API), die letzten 10 Kopien werden behalten (backups_keep; 0 deaktiviert). Jede Schema-Migration erstellt zuerst automatisch eine Sicherheitskopie.

• Schema-Version, aufgezeichnet in db_meta.schema_version.

• Hook-Fehler sind nicht lautlos: Ein fehlschlagender Hook schreibt in das stderr der Sitzung und hinterlässt ein hook_error-Ereignis im Journal, das im Report sichtbar ist.

• Lerndisziplin: Der Report zeigt reflect/recall — unter ~0.1 bewertet der Agent abgerufene Erinnerungen selten und Zerfall/Beförderung laufen blind.

• Projekt-Routing wird mit einem einzigen Aufruf verifiziert — introspect zeigt das aktuell erkannte Projekt.

Beobachtbarkeit („wie sich der Speicher im Laufe der Zeit verhält“)

Jedes Ereignis wird an das Journal in der Datenbank angehängt: Schreibvorgänge, Recalls (Latenz, Enthaltung, Konfidenz), Feedback, Konsolidierungen mit vollständigen Metriken. Jederzeit vollständiger Report:

python -m realmemory.report --path ./rm_data [--json report.json]

Zeigt: Speicherwachstum nach Typ/Scope/Status, Novelty-Gate-Entscheidungsverlauf, Enthaltungsanteil und p50/p95-Recall-Latenz, was verstärkt wurde, welche Episoden verblassen, Retentionsdynamik über Schlaf-Phasen hinweg, Hook-Fehler.

Phase-0-Ergebnisse (reale Durchläufe)

Synthetischer Benchmark (bench_recall, Hashing-Embedder, dim=2048):

Realtext-Benchmark (bench_real, fastembed MiniLM dim=384, 103 RU/EN-Fakten, 89 Abfragen — Paraphrasen, exakte Tokens, Rauschen):

Lehre aus dem synthetischen Benchmark: Er erzielte 1.000, während die Standard-Schwellenwerte bei realem Text fast alles zu wenigen Blobs zusammenführten — die Kalibrierung wird jetzt aus Benchmark-Verteilungen abgeleitet und liegt im Embedder-Profil. Derselbe Realtext-Benchmark enthält eine naive Vollscan-Kosinus-Baseline: Die Pipeline gewinnt deutlich bei exakten Tokens (1.000 vs. 0.800), ist bei Paraphrasen gleichauf und enthält sich derzeit weniger aggressiv als ein reiner Schwellenwert — siehe docs/ARCHITECTURE.md §7.2. Skalierungsdurchlauf (10k–50k Traces) mit ehrlichen Erkenntnissen über eine Recall-Qualitätsklippe bei 30k bei synthetischen Daten: §7.3.

Details und das negative Hamming-SDM-Ergebnis in docs/ARCHITECTURE.md §3 und §7.

Tests: 122 bestanden.

Architektur

Kurz gesagt: L1 — SDRVotingIndex, Pointer-Voting über einen invertierten Index von SDR-Einheiten (Kapazität + Kandidaten), L2 — ein Assembly-Netzwerk über denselben Einheiten (Assoziationen, Vervollständigung, Multi-Hop), gekrönt von einem exakten Embedding-Reranking, einem Novelty-Gate, Zerfallsrichtlinien und einem Offline-Konsolidierer („Schlaf“).

Modul-Schnittstellen sind in docs/CONTRACTS.md festgelegt; Forschungshintergrund und Quellen in docs/RESEARCH.md.

Projektstruktur

src/realmemory/
├── encoding/     # embedders, SDR encoding
├── core/         # L1 SDRVotingIndex, L2 AssemblyNetwork, plasticity
├── policies/     # novelty gate, trace decay/promotion
├── store/        # SQLite storage (traces, edges, eligibility, events)
├── api/          # MCP server
└── eval/         # benchmarks

Lizenz

MIT