Engraphy

Assoziatives Gedächtnis für KI-Agenten, modelliert nach dem menschlichen Geist.

Der Name stammt von Engraphy, einem alten Begriff aus der Gedächtnisforschung für den Prozess des Anlegens eines Engramms, der Spur, die eine Erinnerung im Gehirn hinterlässt. Engraphy macht das für Agenten: Es prüft jede neue Erinnerung gegen das, was es bereits weiß, bevor der Schreibvorgang abgeschlossen wird, führt Wiederholungen zusammen, verknüpft wirklich neue Fakten und überschreibt niemals stillschweigend. Nichts wird gelöscht, sodass die Historie begehbar bleibt.

Engraphy ist selbst gehostet. Es speichert, was ein Agent lernt, als typisierten Wissensgraphen auf Postgres + pgvector: Schreibvorgänge deduplizieren sich selbst gegen bestehende Erinnerungen, Abruf verschmilzt semantische und lexikalische Suche, Isolation zwischen Benutzern wird von der Datenbank erzwungen, und die gesamte Form des Gedächtnisses wird pro Anwendung als Pack deklariert.

Es existiert, um das flache JSON-, Einzelbenutzer- und stdio-Modell des Referenz-MCP-Speicherservers durch etwas zu ersetzen, das Nebenläufigkeit, Paraphrasen, Duplikate und Jahre angesammelter Erinnerungen übersteht. Es spricht das Model Context Protocol, sodass jeder MCP-Client (eine VS-Code-Erweiterung, eine Desktop-App, ein anderer Agent) es über HTTP verwenden kann.

Quelltext verfügbar. Lizenziert unter der Business Source License 1.1: Lesen, ausführen, darauf aufbauen und in Produktion für das eigene Produkt verwenden. Das Anbieten von Engraphy selbst als gehosteten oder verwalteten Dienst für Dritte ist dem Lizenzgeber bis zum Änderungsdatum vorbehalten, an dem es in Apache-2.0 übergeht. Siehe Lizenz.

Was es tut

• Ein typisierter Gedächtnisgraph. Erinnerungen sind typisierte Knoten (fact, decision, person, event, …), verbunden durch typisierte Kanten (involves, references, supersedes, …). Die Typen, ihre Attributschemata und die Regeln, welche Kanten welche Typen verbinden dürfen, werden pro Raum in einem Pack deklariert und in Postgres durchgesetzt.

• Schreibvorgänge, die sich selbst deduplizieren. Jeder Schreibvorgang wird eingebettet und gegen bestehende Erinnerungen gebändert. Eine fast wörtliche Wiederholung wird automatisch zusammengeführt; ein wirklich neues, aber verwandtes Faktum wird als eigener durchsuchbarer Knoten behalten und durch eine Kante verbunden (nichts wird stillschweigend absorbiert); ein Grenzfall wird als ausstehendes Duplikatprüfungs-Urteil für den Aufrufer zur Auflösung geparkt. Jeder Schreibvorgang gibt einen Resonanzbericht darüber zurück, was er berührt hat.

• Hybrider Abruf. search verschmilzt einen Vektor-Teil (Kosinus über Einbettungen) und einen lexikalischen Teil (Postgres-Volltext) mit Reciprocal Rank Fusion, und traverse geht die Kanten entlang. Attributwerte werden in die durchsuchbare Oberfläche eingefaltet, sodass ein nur in einem typisierten Attribut gespeichertes Faktum weiterhin auffindbar ist.

• Isolation, die die Datenbank erzwingt. Mehrere Räume und mehrere Prinzipale innerhalb eines Raums werden durch Postgres Row-Level Security getrennt, die unter einer Nicht-Superuser-Rolle läuft, nicht durch Anwendungsprüfungen, die vergessen werden können. Der Server verbindet sich als NOBYPASSRLS-Rolle.

• Scope-Routing für LLMs gebaut. Jeder Scope trägt eine Beschreibung dessen, was er regelt; das schreibgeschützte scope_guide-Tool gibt dieses Routing-Manifest zurück, sodass ein Agent entscheiden kann, wo eine neue Erinnerung hingehört, bevor er schreibt.

• Eine Operator-CLI und eine MCP-Tool-Oberfläche für alles vom Bootstrapping eines Raums bis zum Prägen von Tokens, Importieren von Daten, Anwenden von Packs und Verifizieren von Wiederherstellungen.

Related MCP server: gbrain

So funktioniert es

flowchart LR
    C[MCP client<br/>VS Code · desktop · agent] -->|HTTP + bearer token| S[Engraphy server<br/>FastMCP]
    S --> E[Embedding<br/>nomic-embed-text-v1.5]
    S --> DB[(Postgres 16 + pgvector<br/>nodes · edges · scopes<br/>RLS · schema enforcement)]
    P[Pack<br/>types · edges · briefing] -.declares.-> DB

Ein Schreibvorgang wird eingebettet, durch Ähnlichkeit in merge / merge-link / pending / new gebändert und unter der Identität des Aufrufers committet. Ein Lesevorgang (search, get, traverse, briefing) läuft unter RLS, sodass ein Aufrufer nur die Scopes sieht, die ihm gewährt wurden. Ein Pack deklariert die Knotentypen, Kantentypen, Attributschemata und die Session-Start-Briefing für einen Raum, sodass eine Engine viele unterschiedlich geformte Gedächtnisanwendungen bedient. Die Architekturübersicht geht den vollständigen Schreib- und Lesepfad durch.

Schnellstart

Voraussetzungen: Docker (mit Compose). Das Cloud-Profil bringt Postgres hoch, führt Migrationen aus, richtet die App-Rolle ein und startet den Server in einem Befehl.

# 1. Configure secrets (never committed)
cp deploy/.env.example .env   # then edit, or:
printf 'POSTGRES_PASSWORD=%s\nENGRAPHY_APP_ROLE_PASSWORD=%s\n' \
  "$(openssl rand -hex 16)" "$(openssl rand -hex 16)" > .env

# 2. Bring up Postgres + migrate + provision + serve
docker compose up -d          # first boot downloads the ~523 MB embedding model

# 3. Create a space, apply the starter pack, mint a client token
docker compose --profile admin run --rm admin \
  engraphy-admin space create --id personal --display-name "My Memory" --principal me
docker compose --profile admin run --rm admin \
  engraphy-admin pack apply packs/starter/pack.yaml --space personal
docker compose --profile admin run --rm admin \
  engraphy-admin token create --space personal --principal me \
    --client-name my-editor --role readwrite

Der Server läuft jetzt auf 127.0.0.1:8000 (setzen Sie einen TLS-terminierenden Reverse-Proxy davor, um ihn zu exponieren). Weisen Sie jeden MCP-Client mit dem Bearer-Token darauf hin. Der Setup-Leitfaden behandelt auch den lokalen Weg ohne Docker.

Oder lassen Sie die Skripte es tun

up.sh und provision.sh (mit up.ps1 / provision.ps1 als Windows-Äquivalente) kapseln genau die obige Sequenz und fügen das Warten hinzu, das ein Copy-Paste-Schnellstart nicht kann:

./up.sh          # writes .env with random passwords, starts the stack,
                 # then blocks until /healthz returns 200
./provision.sh   # creates the space, applies the starter pack, mints a token,
                 # and prints the client settings to paste in

up.sh pollt /healthz anstelle des Compose-Health-Status, weil Compose beim ersten Start starting meldet, solange der Modell-Cache zum Seed benötigt, was von außen wie ein Crash-Loop aussieht. Eine 200 ist das echte Signal.

Beide Skripte sind sicher erneut ausführbar: Eine vorhandene .env wird nie überschrieben, und ein vorhandener Raum oder ein bereits angewendetes Pack wird übersprungen, nicht als Fehler behandelt, sodass ein erneuter Lauf trotzdem ein frisches Token prägt.

Alles ist parametrisiert, mit Standardwerten, die unverändert funktionieren:

Das Token wird einmal ausgegeben und von den Skripten nie auf die Festplatte geschrieben; der Server speichert nur seinen SHA-256. Wenn Sie es verlieren, führen Sie provision.sh erneut aus, um ein neues zu erhalten.

Verwendung von einem Client

Engraphy ist ein MCP-Server, also verbindet sich ein Client und ruft Tools auf:

Siehe die Tool-Referenz für Parameter, Rückgaben und ein Beispiel pro Tool. Eine First-Party-VS-Code-Erweiterung befindet sich in vscode-extension/.

Dokumentation

• docs/: Entwicklerdokumentation, Architektur, Setup, Packs, Tool-Referenz, Bereitstellung und ein End-to-End-Tutorial.

• design/: das Design-Set, das Datenmodell, Abruf und Deduplizierung, Authentifizierung und Mandantenfähigkeit, Betrieb, das Pack/Ontologie-System und die Benchmark-Umgebung. Hier lebt die technische Begründung.

• skills/: prägnante Anleitungen, die ein LLM-Agent laden kann, um Engraphy gut zu nutzen (Schreiben und Deduplizierung, Abruf, Scopes und Sichtbarkeit, Antwortdisziplin).

Anforderungen

• Postgres 16 mit pgvector (das pgvector/pgvector:pg16-Image enthält beides).

• Python ≥ 3.12.

• dbmate für Migrationen (im Admin-Container gebündelt; nur für den Weg ohne Docker auf PATH benötigt).

• Das Einbettungsmodell nomic-ai/nomic-embed-text-v1.5 (384-dim, ~523 MB, wird beim ersten Start heruntergeladen und zwischengespeichert).

Projektstatus

v0.1.0. Das Schema und der Durchsetzungskern, Engine-Verhalten (Deduplizierung, hybrider Abruf, Graphdurchlauf, Briefings), der MCP-Server mit Authentifizierung und Admin sowie die Operator-CLI sind implementiert und durch eine Live-Postgres-Testsuite sowie einen CI-Job abgedeckt, der die ausgelieferten Bereitstellungsartefakte Ende-zu-Ende testet. Eine Benchmark-Umgebung (bench/, design/09) führt die Engine gegen öffentliche Langzeitgedächtnis-Datensätze aus; sie ist ein Werkzeug zum Messen von Änderungen, keine Quelle für Marketingzahlen.

Lizenz

Engraphy ist unter der Business Source License 1.1 lizenziert (siehe LICENSE).

• Sie dürfen Engraphy lesen, modifizieren, weiterverbreiten, selbst hosten und in Produktion als Gedächtnisschicht für Ihre eigenen Anwendungen und Agenten verwenden.

• Sie dürfen nicht Engraphy selbst Dritten vor dem Änderungsdatum als gehosteten oder verwalteten Dienst anbieten.

• Änderungsdatum: 2026-08-22 + 4 Jahre (2030-08-22), an dem die Lizenz in die Apache License, Version 2.0 übergeht.

Copyright (c) 2026 Devon Clark.