Ebb — ein agentenzentrierter Wissensgraph

Langzeitgedächtnis für KI-Agenten, aufgebaut als Graph. Relevanz ist aktualitätsgewichtete Verbindungsstärke: Wissen, das wiederverwendet wird, bleibt lebendig, ungenutztes Wissen verfällt und wird archiviert, und nichts wird gelöscht, bis ein Mensch zustimmt. Läuft eingebettet (null Infrastruktur) oder auf Neo4j (Produktion).

Die beiden Mechanismen, um die es aufgebaut ist — verbindungsgewichtete Relevanz und Zeitverfall — sind native Graphoperationen, und beide haben tiefe Vorarbeiten (PageRank/Zentralität; ACT-R-Basisaktivierung und Ausbreitungsaktivierung aus der Kognitionswissenschaft; Spaced-Repetition-Vergessenskurven). Dies ist eine kleine, ehrliche Implementierung dieser Linie, die speziell auf Agentengedächtnis abzielt.

Warum es so aufgebaut ist

1. Engine und Schnittstelle sind getrennt. Der Graphspeicher sitzt hinter einer kleinen Schnittstelle (GraphStore). Agenten und die Bewertungslogik berühren nie eine spezifische Datenbank, sodass Sie denselben Graphen heute auf einer eingebetteten Engine ausführen und später mit einer Umgebungsvariable auf Neo4j umsteigen können.

2. Relevanz ist aktualitätsgewichtet, nicht rohe Verbindungsanzahl. „Mehr Verbindungen = relevanter“ belohnt alte, stark referenzierte Daten für immer — genau das Problem veralteter Daten, das das System beseitigen soll. Hier wird der Beitrag jeder Kante zur Relevanz mit einem Zeitverfallsfaktor multipliziert, der an wann die Verbindung zuletzt verstärkt wurde gekoppelt ist. Eine gestern verstärkte Kante zählt fast voll; eine, die vor sechs Monaten zuletzt berührt wurde, zählt fast nichts. Die Wiederverwendung einer Verbindung (recall/reinforce) setzt ihre Uhr zurück — so verfolgt Relevanz, was tatsächlich lebendig ist, und veraltetes Wissen sinkt von selbst.

Beweis aus dem Demo-Seed-Graphen (python -m ebb.demo):

node                             raw#   activation
decision:outcome-pricing            3        6.116   <- fresh, few links, ranks #1
decision:seat-pricing              11        3.077   <- MOST links, ranks #3
...
note:analysis-* (x10)               1        0.051   <- decayed -> archived (tier 4)

Die überholte Pro-Sitzplatz-Entscheidung hat die höchste rohe Verbindungsanzahl im Graphen und rangiert trotzdem auf Platz drei, hinter einer frischen Entscheidung mit einem Drittel so vielen Links. Rohe Anzahl verlor; Aktualität gewann.

Related MCP server: Memory Engine MCP

Was es enthält

• Graphmodell — jede Notiz, Entscheidung, Besprechung, Person, Kunde, Fakt ist ein Knoten; jede Referenz ist eine zeitgestempelte, typisierte, gewichtete Kante.

• Bewertungs-Engine (scoring.py) — aktualitätsgewichtete Aktivierung, exponentieller Verfall (konfigurierbare Halbwertszeit), ein Hop der Ausbreitungsaktivierung (ein portabler Ersatz für PageRank) und Tier-Zuweisung. Reine Funktionen, vollständig unit-getestet.

• Vier Archiv-Tiers — 1 heiß (Standard-Recall) · 2 warm (tieferer Recall) · 3 kalt (archiviert, nur auf Abruf) · 4 eingefroren (wartet auf menschliche Freigabe vor Löschung). Angeheftete Knoten werden nie automatisch archiviert.

• MCP-Server (mcp_server.py) — die Agentenschnittstelle: remember, recall, connect, reinforce, forget, neighbors, pin, maintain, review_queue, stats.

• Zwei Backends — KuzuStore (eingebettet, Standard) und Neo4jStore (Produktion), gleiche Schnittstelle, gleiche Cypher-Formen.

Schnellstart (eingebettet — null Infrastruktur)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m ebb.demo      # narrated end-to-end walkthrough
pytest -q                 # 11 tests, all green

Kein Docker, kein Server, keine Ports. Kùzu ist eine In-Process-Graphdatenbank, daher ist Ebb nur ein Ordner (./ebb_db).

Einbinden in einen MCP-Client (z. B. Claude Desktop)

1. Kopieren Sie den ebb-Block aus claude_desktop_config.example.json in die MCP-Konfiguration Ihres Clients und korrigieren Sie die absoluten Pfade.

2. Starten Sie den Client neu. Die Ebb-Tools erscheinen im Tools-Menü.

3. Der Agent kann jetzt remember über Sitzungen hinweg, recall was relevant ist, und reinforce was er weiterhin verwendet — mit Verfall und Archivierung, die für ihn übernommen werden.

Produktionsmodus (Neo4j)

docker compose up -d      # Neo4j + Graph Data Science + APOC
EBB_BACKEND=neo4j NEO4J_PASSWORD=brainbrain python -m ebb.demo

Gleicher Code, gleiches Verhalten. Auf Neo4j erhalten Sie zusätzlich die GDS-Bibliothek, sodass der Ausbreitungsaktivierungsdurchlauf in scoring.py zu echtem PageRank / Zentralität / Community-Erkennung aufsteigen kann, wenn die Skalierung es erfordert. (Das Cypher des Neo4j-Backends spiegelt das vollständig getestete Kùzu-Backend; führen Sie pytest gegen eine Live-Instanz aus, bevor Sie ihm in der Produktion vertrauen.)

Das Modell, kurz

Aktivierung eines Knotens = Σ (edge.weight × decay(age_since_last_reinforced)) + read-recency-bonus, plus ein gedämpfter Hop desselben von seinen Nachbarn. Verfall ist eine Halbwertszeit (Standard 30 Tage, einstellbar). Tiers werden auf der Aktivierung geschnitten, die gegen den aktivsten nicht angehefteten Knoten normalisiert wird. recall mischt diese Aktivierung mit Textabgleich der Abfrage und gibt zurück, warum jedes Ergebnis aufgetaucht ist. Alles ist an einem Ort einstellbar — ebb/scoring.py::Config.

Schreiben eines Ingestions-Adapters

Ebb ist quellenagnostisch: alles, was remember/connect aufruft, kann es speisen. Eine Quelle (ein Notizordner, ein Wiki, ein Issue-Tracker) wird zu einem Graphen, indem Dokumente auf Knoten, Links/Erwähnungen auf Kanten und ein Bearbeitungszeitstempel auf die Aktualitätsuhr abgebildet werden. Halten Sie Adapter und ihre Daten aus dem Repo heraus.

Aufbau

src/ebb/
  model.py        # Node, Edge, tiers
  scoring.py      # decay, activation, spreading, tiering  <- the core
  store.py        # GraphStore interface
  kuzu_store.py   # embedded backend (default)
  neo4j_store.py  # production backend
  engine.py       # Brain: remember/recall/connect/reinforce/maintain/...
  mcp_server.py   # agent-facing MCP tools
  seed.py         # fictional demo graph
  demo.py         # narrated walkthrough
tests/            # 11 tests: scoring + end-to-end
docker-compose.yml

Lizenz

MIT — siehe LICENSE.