Engram

Every thought leaves a trace.

Verleihen Sie Ihrem KI-Agenten ein Gehirn, das vergessen kann.

Engram ist ein vollständig lokal ausgeführter MCP-Speicherdienst. Es geht nicht nur um "Speichern und Abrufen" – es simuliert die menschlichen Mechanismen des Vergessens, der Verstärkung und der Assoziation, damit Agenten sich über Sitzungen hinweg an wirklich Wichtiges erinnern und Details, die nicht mehr benötigt werden, auf natürliche Weise vergessen können.

Keine Cloud-Abhängigkeit, die Daten bleiben immer auf Ihrem Rechner.

Welche Probleme werden gelöst?

Problem 1: Unterbrechung des Zustands zwischen Sitzungen

Jede Konversation mit einem KI-Agenten ist ein unbeschriebenes Blatt. Die Präferenzen, die Sie ihm gestern mitgeteilt haben, die Architektur-Entscheidungen von letzter Woche, die Fehler, in die Sie letzten Monat getappt sind – bei der nächsten Sitzung ist alles weg. Das Leeren des Context-Windows entspricht einer Formatierung des Gehirns.

Problem 2: Datei-Entropie

Das Hineinstopfen von Kontext in CLAUDE.md oder .cursorrules scheint das Problem zu lösen, schafft aber in Wirklichkeit neue: Die Dateien werden immer länger, veraltete Informationen vermischen sich mit neuen, und der manuelle Wartungsaufwand steigt stetig. Sie verwalten kein Gedächtnis, sondern pflegen ein Dokument, das immer schwerer zu lesen ist.

Problem 3: Verlust des Engineering-Status

Was hat der Agent getan, wo steckt er fest, was ist der nächste Schritt – für diese strukturierten Engineering-Zustände gibt es keinen Speicherort. Jede neue Sitzung erfordert 10 Minuten "Re-Alignment", bevor die eigentliche Arbeit beginnen kann.

Die Lösung von Engram: Nicht "alles speichern", sondern die Mechanismen des Vergessens, der Verstärkung und der Assoziation des menschlichen Gedächtnisses simulieren:

• Wichtige Präferenzen und Entscheidungen verblassen extrem langsam und bleiben fast dauerhaft erhalten.

• Temporärer Debugging-Kontext verblasst nach 11 Tagen auf natürliche Weise.

• Wissen, das wiederholt abgerufen wird, festigt sich.

• Widersprüchliche Informationen werden automatisch überschrieben, um Konflikte zu vermeiden.

• Neu in v0.2: Strukturierte Sitzungsübergabe (session handoff), damit die nächste Sitzung am Haltepunkt fortgesetzt werden kann, statt bei Null anzufangen.

• Neu in v0.4: Engineering-Status-Zentrum — strukturierte Fehlerursachenanalyse (track_failure) und Fortschrittsverfolgung (track_progress), damit der Agent nicht nur Informationen, sondern auch den Engineering-Status speichert.

Related MCP server: Ori Mnemos

Kernmechanismen

1. Ebbinghaus-Vergessenskurve

Jede Erinnerung hat einen Stärkewert (strength), der mit der Zeit exponentiell abnimmt:

effective_λ = base_λ × (1 - importance × 0.8)
strength = importance × e^(-λ × days) × (1 + recall_count × 0.2)

Drei Faktoren bestimmen gemeinsam, wie lange eine Erinnerung überlebt:

Vier Gedächtniskategorien:

Design-Absicht: Erfolgreiche Strategien sollen am längsten gespeichert werden (strategy ~38 Tage), Fehler am kürzesten (failure ~11 Tage) – da sich Umgebungen ändern und die Fehler von gestern morgen bereits behoben sein könnten.

2. Intelligente Deduplizierung und Konfliktlösung

Beim Speichern einer neuen Erinnerung fügt das System diese nicht einfach hinzu, sondern führt zuerst einen semantischen Abgleich mit vorhandenen Erinnerungen durch:

相似度 ≥ 0.85 → REINFORCE  只增加回忆次数，不重复存储
相似度 0.65~0.84 → 检测矛盾
  ├── 语义矛盾 → REPLACE   用新内容覆盖旧内容
  └── 语义兼容 → MERGE     合并为一条更完整的记忆
相似度 < 0.65 → NEW        存为新记忆

Die Konflikterkennung erfolgt durch Polaritätsanalyse: Extrahieren positiver Wörter (prefer/love/adopt) und negativer Wörter (avoid/hate/reject) sowie Verneinungen (not/don't/never), um zu beurteilen, ob zwei Erinnerungen gegensätzliche Standpunkte ausdrücken.

Beispiel: Wenn bereits "Benutzer bevorzugt TypeScript" gespeichert ist und "Benutzer entscheidet sich gegen TypeScript für Go" hinzugefügt wird, erkennt das System den Widerspruch und ersetzt die alte Erinnerung automatisch durch die neue.

3. Hybride Suche (Vektor + BM25 + Graph)

Beim Abrufen von Erinnerungen wird ein dreifaches hybrides Scoring verwendet:

最终得分 = 0.4 × BM25关键词得分 + 0.6 × (语义相似度 × 衰减强度) + 图谱加成

Warum nicht nur Vektorsuche?

Effekt der Fusion: Eine Suche nach "Datenbank-Performance" findet nicht nur Erinnerungen, die direkt Performance erwähnen, sondern über den Graphen auch verwandte Indexierungsstrategien oder Caching-Entscheidungen.

4. Semantischer Graph

Jede Erinnerung baut beim Speichern automatisch semantische Verbindungen zu bestehenden Erinnerungen auf:

• Berechnung der Kosinus-Ähnlichkeit zu allen vorhandenen Erinnerungen.

• Bei Ähnlichkeit ≥ 0.40 wird eine bidirektionale Kante erstellt, Gewicht = Ähnlichkeit × 0.5.

• Jede Erinnerung verbindet sich mit maximal 5 ähnlichsten Nachbarn.

Zwei Schlüsselfunktionen des Graphen:

Assoziationsfindung: Bei der Suche wird ausgehend von den Treffern eine BFS (maximale Tiefe 2) durchgeführt, um assoziierte Erinnerungen zu finden, selbst wenn diese keine direkte semantische Ähnlichkeit zum Suchbegriff haben. Wie menschliches "Assoziieren".

Kettenschutz: Wenn eine Erinnerung unter den Schwellenwert fällt, aber ihre Nachbarn noch stark sind, bleibt sie erhalten – da sie als Brücke zwischen zwei wichtigen Wissenspunkten dienen könnte.

5. Automatische Konsolidierung und Bereinigung

Alle 12 Stunden führt das System im Hintergrund eine Wartungsaufgabe aus:

Konsolidierung (Consolidation):

1. Identifikation von Clustern mit Ähnlichkeit ≥ 0.70.

2. Beibehaltung der Erinnerung mit der höchsten Wichtigkeit als Haupterinnerung.

3. Zusammenführung der einzigartigen Informationen der anderen Erinnerungen.

4. Neuberechnung der Vektor- und Graphbeziehungen.

5. Löschung der nun redundanten Erinnerungen.

Bereinigung (Pruning):

1. Berechnung der aktuellen Stärke jeder Erinnerung.

2. Stärke < 0.05 und Bestehen des Kettenschutz-Checks → Löschen.

3. Stärke < 0.05, aber Nachbarn noch stark → Beibehalten (Kettenschutz).

Das bedeutet, dass die Datenbank automatisch schlank bleibt – kein manuelles Aufräumen erforderlich, kein unendliches Wachstum.

Engineering-Status-Zentrum (v0.4)

Engram ist nicht nur ein Speicher-Plugin – es ist eine Zustandsebene, die Engineering-Prozesse versteht.

Fehlerursachenanalyse (track_failure)

Wenn der Agent auf Bugs, Testfehler oder Deployment-Probleme stößt, werden diese strukturiert protokolliert:

# MCP 调用
track_failure(
    error="CSRF token missing on checkout",
    component="payment",
    severity="critical",        # → importance=0.9
    root_cause="middleware not loaded after refactor",
    fix="re-add CsrfMiddleware to pipeline",
    related_test_ids=["test_checkout_01", "test_payment_csrf"]
)

Design-Entscheidungen:

• severity wird automatisch auf importance gemappt (critical=0.9, major=0.7, minor=0.5).

• Feste Verwendung der Kategorie failure (schnellster Zerfall λ=0.35, ~11 Tage Halbwertszeit) – Umgebungen ändern sich, alte Fehlerberichte veralten natürlich.

• Das Feld component unterstützt aggregierte Statistiken pro Modul zur schnellen Identifizierung von Hochrisikobereichen.

Fortschrittsverfolgung (track_progress)

Verfolgung von Feature-/Aufgabenstatus über Sitzungen hinweg:

track_progress(
    feature="login-flow-refactor",
    status="in_progress",       # → importance=0.8
    completion=60,
    blockers=["waiting for API design review"],
    quality_score=0.85,
    notes="auth module done, UI pending"
)

Design-Entscheidungen:

• status wird automatisch auf importance gemappt (blocked=0.9 am höchsten, done=0.5 am niedrigsten).

• Feste Verwendung der Kategorie strategy (langsamster Zerfall λ=0.10, ~38 Tage Halbwertszeit) – Fortschrittsstatus sollen am längsten gespeichert werden.

• Abgeschlossene Features verblassen natürlich, kein manuelles Aufräumen nötig.

Engineering-Metriken (Erweiterung von memory_stats)

memory_stats aggregiert nun automatisch Engineering-Daten:

{
  "total": 42,
  "categories": {"fact": 20, "failure": 8, "strategy": 14},
  "engineering": {
    "failures": {
      "total": 8,
      "by_component": {"auth": 5, "payment": 3},
      "by_severity": {"critical": 2, "major": 6}
    },
    "features": {
      "total_tracked": 4,
      "active": {
        "login-refactor": {"status": "in_progress", "completion": 60},
        "payment-fix": {"status": "blocked", "completion": 30}
      }
    }
  }
}

Technische Architektur

┌──────────────────────────────────────────────┐
│              MCP Client                      │
│      (Claude Code / Cursor / ...)            │
└──────────────────┬───────────────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼───────────────────────────┐
│              server.py                       │
│  8 MCP tools  ·  APScheduler (12h 维护)      │
├──────────────────────────────────────────────┤
│                                              │
│  ┌─ 写入路径 ──────┐  ┌─ 读取路径 ──────┐    │
│  │  resolve.py     │  │  retrieve.py    │    │
│  │  去重/矛盾消解   │  │  混合检索+评分   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
│  ┌─ 维护路径 ──────┐  ┌─ 统计路径 ──────┐    │
│  │  consolidator   │  │  decay.py       │    │
│  │  聚类合并+剪枝   │  │  遗忘曲线+强度   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
├──────────────────────────────────────────────┤
│  embedding.py          │  graph.py           │
│  768d / 1024d 向量编码  │  NetworkX 语义图谱  │
├──────────────────────────────────────────────┤
│              db.py — DuckDB                  │
│  向量存储  ·  BM25 全文索引  ·  CRUD          │
└──────────────────────────────────────────────┘

数据文件（~/.engram/）：
├── memories.duckdb     # 向量数据库（单文件，零运维）
├── graph.json          # 语义图谱（JSON 序列化）
└── model_cache/        # 嵌入模型缓存

MCP-Tool-Schnittstellen

Referenz für Wichtigkeit

Vorteile für den Benutzer

1. Der Agent "kennt" Sie wirklich

Sie müssen nicht bei jedem Gespräch Ihren Tech-Stack, Ihre Codiergewohnheiten oder den Projektkontext neu erklären. Der Agent weiß, dass Sie Go statt Java bevorzugen, dass das Projekt ein Monorepo nutzt und welche Architektur-Entscheidungen Sie letzte Woche getroffen haben.

2. Wissen entwickelt sich natürlich

Konfliktlösung bedeutet, dass das Wissen des Agenten immer auf dem neuesten Stand ist. Wechsel von React zu Vue? Ein Gespräch reicht für das automatische Update. Keine manuelle Pflege einer Liste "Was der Agent wissen sollte".

3. Null Wartungsaufwand

• Kein manuelles Löschen alter Erinnerungen – die Vergessenskurve erledigt das.

• Kein manuelles Zusammenführen von Duplikaten – der Konsolidierer übernimmt das.

• Keine Sorge vor Datenwachstum – automatische Wartung alle 12 Stunden.

• Keine externen Dienste – DuckDB als Einzeldatei, sofort einsatzbereit.

4. Vollständige Privatsphäre

Alle Daten liegen in ~/.engram/, keine Internetverbindung, kein Upload, keine Cloud-Abhängigkeit. Auch das Embedding-Modell läuft lokal. Ihre Erinnerungen gehören Ihnen.

5. Assoziative Entdeckung

Die Graph-Erweiterung ermöglicht es dem Agenten, nicht nur "zu finden, was gesucht wurde", sondern entlang semantischer Verbindungen verwandtes Wissen zu finden, das nicht direkt passt. Wie ein erfahrener Kollege, der nicht nur die Frage beantwortet, sondern auch ergänzt: "Übrigens, das hängt mit der Sache von neulich zusammen."

6. Wird mit der Nutzung intelligenter

Verstärkungsmechanismus: Erinnerungen, die wiederholt abgerufen werden, werden stärker und verblassen langsamer. Der Agent lernt automatisch, welches Wissen für Sie am wertvollsten ist.

Schnellstart

# 安装
pip install mcp-engram

# 初始化（下载模型、创建数据库）
engram-setup

# 按照输出提示将配置块添加到 Claude Code 配置中

Claude Code Konfiguration

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": {
        "HF_ENDPOINT": "https://hf-mirror.com"
      }
    }
  }
}

CLAUDE.md Integration

Fügen Sie dies in CLAUDE.md Ihres Projekts hinzu:

## Memory Rules

### Step 1 — 先回忆再行动
每次任务开始时，用请求中的关键词调用 `recall_memory`。

### Step 2 — 学到新东西就存
| 情况 | 操作 |
|------|------|
| 全新知识 | `store_memory(content, importance)` |
| 补充已有 | `update_memory(memory_id, merged_content)` |
| 推翻已有 | `update_memory(memory_id, new_content)` |

Umgebungsvariablen

Kurzübersicht kritische Schwellenwerte

LoCoMo Benchmark-Bewertung

Bewertung der Suchqualität basierend auf LoCoMo (Snap Research Benchmark für langfristiges Konversationsgedächtnis). LoCoMo ist der Standard, der von Produkten wie Mem0/Zep/Memobase/MemMachine verwendet wird.

Testkonfiguration

• Datensatz: locomo10.json (2/10 Konversationen, 233 QA, ohne adversarial)

• Suche: recall() top-k=5

• LLM: DeepSeek-V3.2 / GLM-5.1 (Hinweis: Basisprodukte nutzen einheitlich GPT-4o-mini)

• Metriken: Token-level F1 (offizielle LoCoMo-Metrik) + Hit@5 (LLM-unabhängige Suchtrefferquote)

Turn Mode — Beste Konfiguration (bge-m3 + bge-reranker-v2-m3, DeepSeek-V3.2)

Zweistufige Suche: recall top-50 → CrossEncoder rerank auf top-5, importance=1.0 Korrektur des Gewichtsverhältnisses

Turn Mode — Optimierungspfad (DeepSeek-V3.2)

Vier Optimierungsrunden kumuliert F1 +50.3% (0.29 → 0.44), Hit@5 +26.2pp (51.5% → 77.7%).

Turn Mode — LLM-Vergleich (all-mpnet-base-v2)

Observation Mode (abstrakte assertive Fakten)

Vergleich mit Branchen-Benchmarks

Fazit: Vier Optimierungsrunden mpnet(0.29) → bge-m3(0.35) → +reranker(0.39) → +weight fix+r50(0.44). Hit@5: 51.5% → 77.7%. Der Abstand zu Mem0(0.67) wurde von 56% auf 35% reduziert.

Best Config Kurzübersicht

Empfohlene Konfiguration: bge-m3 (1024d) + bge-reranker-v2-m3 zweistufige Suche

Metrik	Wert	Beschreibung
Gesamt F1	0.4383	Token-level, DeepSeek-V3.2
Gesamt Hit@5	77.7%	Reine Suchtrefferquote, LLM-unabhängig
Temporal Hit@5	95.2%	Hervorragende Leistung bei zeitlichen Fragen
Optimierungsumfang	F1 +50.3%, Hit +26.2pp	Vier Runden kumuliert (relativ zu initialem mpnet)

Wichtige Parameter: recall top-50 → rerank to top-5, importance=1.0 Korrektur des Gewichtsverhältnisses. Lokale Bereitstellung ohne Cloud-Abhängigkeit, Abstand zu Mem0 (mit GPT-4o-mini) auf 35% reduziert.

Entwicklung

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v

Lizenz

MIT