Ida-Memory

Ein eigenständiger MCP-Server (Model Context Protocol): ein gemeinsames, themenübergreifendes Wissensgraph-Gedächtnis, das mehrere KIs/Connectors gleichzeitig verbinden können (z.B. Claude Desktop, claude.ai, mehrere claude.ai Routinen wie Ida-Telegram). Getrennt von Ida-Untis und Ida-Telegram -- ein eigener Container, ein eigenes Repo, keine Abhängigkeit dazwischen.

Baut exakt auf dem Datenmodell und den Werkzeugnamen des offiziellen MCP-Referenzservers @modelcontextprotocol/server-memory auf -- dieselben neun Tools, dieselbe Semantik, dasselbe JSONL-Speicherformat. Der Unterschied: das Original spricht nur stdio (lokal, ein Prozess pro Client) und kann daher nicht als gemeinsamer Remote-Server für mehrere KIs gleichzeitig gehostet werden. Ida-Memory ist eine native Python-Neuimplementierung mit identischem Verhalten, aber über Streamable HTTP -- lauffähig als ein einziger Container, den beliebig viele MCP-Clients gleichzeitig über einen Cloudflare Tunnel verbinden.

Datenmodell

• Entity: {name, entityType, observations: [text, ...]} -- ein Ding, das man sich merken will (Person, Projekt, Vorliebe, Fakt-Themenblock, ...).

• Relation: {from, to, relationType} -- eine gerichtete Beziehung zwischen zwei Entities (z.B. "Ida" --arbeitet_an--> "Ida-Memory").

Gespeichert als JSONL (memory.jsonl, eine JSON-Zeile pro Entity/Relation) in einem persistenten Docker-Volume.

Related MCP server: knowledgeplane

Warum das auch nach Jahren noch günstig bleibt

Der Verlauf ohne Limit hätte ein Problem: bringt ein Client jedes Mal den kompletten Wissensstand mit, wird das mit wachsendem Bestand (im Lauf der Jahre potenziell tausende Einträge) immer teurer -- viele Tokens für Fakten, die für die aktuelle Frage gar nicht relevant sind. Deshalb:

• search_nodes/open_nodes sind der Normalfall. Sie geben nur Treffer zurück, nie den ganzen Graphen -- so bleibt jede Abfrage klein, unabhängig davon, wie groß das Gedächtnis insgesamt ist.

• search_nodes deckelt zusätzlich die Trefferzahl (SEARCH_RESULT_LIMIT, Standard 30 -- über dem offiziellen Original hinaus, das keine Grenze kennt). Ein zu allgemeiner Suchbegriff kann sonst bei großem Bestand trotzdem hunderte Treffer liefern. Gibt es mehr Treffer als angezeigt, steht das explizit in der Antwort, damit gezielter nachgefragt werden kann.

• read_graph (alles auf einmal) bleibt für den Sonderfall verfügbar, liefert aber ab einer gewissen Größe einen Warnhinweis, stattdessen gezielt zu suchen.

Damit bekommt eine KI immer genug Kontext, um eine Frage zu verstehen, aber nicht mehr als nötig -- auch wenn aus zehn heutigen Fakten in ein paar Jahren zehntausend geworden sind.

Das gilt genauso beim Schreiben, nicht nur beim Lesen. Der Server kann selbst nicht beurteilen, was "wichtig" ist -- das entscheidet die schreibende KI bei jedem Aufruf von create_entities/create_relations/ add_observations. Die Tool-Beschreibungen und die Server-instructions weisen die verbundenen KIs deshalb ausdrücklich an:

• Nur dauerhaft nützliche, wirklich relevante Fakten speichern -- nicht jede beiläufige oder einmalige Kleinigkeit.

• Eine observation nur an die Entity hängen, zu der sie tatsächlich gehört -- nicht vorsorglich an mehrere.

Der Grund: ein mit Trivialkram vollgeschriebener Graph macht später auch die bewusst begrenzten Suchergebnisse (search_nodes-Limit) weniger brauchbar -- jeder unwichtige Eintrag konkurriert um einen der begrenzten Plätze in der Trefferliste. Weniger, aber relevante Einträge sind besser als möglichst viele.

Architektur

Zwei getrennte Container, ein gemeinsames Datenvolume -- MCP-Endpunkt und Web-Dashboard laufen bewusst auf unterschiedlichen Ports/Hostnamen, nicht im selben Prozess:

KI/Client 1 (z.B. claude.ai)   --https-->  Cloudflare Tunnel (memory.deine-domain.de)
KI/Client 2 (z.B. eine Routine) --https-->        |
KI/Client 3 (z.B. Claude Desktop) --https-->      v
                                       10.7.0.1:4568 auf deinem Server
                                               |
                                               v
                                Docker-Container "ida-memory-mcp"  (schreibt)
                                               |
                                               v
                                    /data/memory.jsonl (Docker-Volume)
                                               ^
                                               | (liest nur)
                                Docker-Container "ida-memory-dashboard"
                                               ^
                                       10.7.0.1:4571 auf deinem Server
                                               |
Browser --(Cloudflare-Access-Login)--> Cloudflare Tunnel (idamemory.deine-domain.de) --+

Beide Container binden ihren Port nur auf die Docker-Netzwerk-Gateway-IP (10.7.0.1), wie bei den anderen Ida-*-Containern auf demselben Server -- von außen nicht direkt erreichbar, nur über den bereits laufenden cloudflared-Prozess. Die beiden Hostnamen sind aber unterschiedlich abgesichert: memory.* (MCP) verlangt bei jeder Anfrage das geheime MCP_AUTH_TOKEN (App-Ebene, damit auch KI-Clients ohne interaktiven Login sich verbinden können); idamemory.* (Dashboard) hat auf App-Ebene gar keinen Auth-Zwang mehr, sondern wird ausschließlich durch eine davor geschaltete Cloudflare-Access-Application geschützt (Login per E-Mail-Code) -- siehe Abschnitt "Web-Dashboard" unten. Diese Access-Application ist deshalb sicherheitskritisch, nicht optional.

Voraussetzungen

• Docker + Docker Compose auf dem Server

• Ein bereits eingerichteter und verbundener Cloudflare Tunnel auf diesem Server

1. Einrichten, bauen, starten

git clone https://github.com/<dein-user>/Ida-Memory.git
cd Ida-Memory
cp .env.example .env

.env mit MCP_AUTH_TOKEN ausfüllen (z.B. openssl rand -hex 32).

Image bauen lassen: Bei jedem Push auf main baut .github/workflows/docker-publish.yml das Image automatisch nach ghcr.io/<dein-user>/ida-memory:latest. Einmalig auf öffentlich stellen (GitHub -> Profil -> Packages -> ida-memory -> Package settings -> Change visibility -> Public), damit docker compose es ohne Login ziehen kann.

docker compose pull
docker compose up -d
docker compose logs -f

2. An den bestehenden Cloudflare Tunnel anbinden

Zwei Ingress-Regeln, eine pro Container (analog zu den anderen Ida-*-Projekten):

ingress:
  - hostname: memory.deine-domain.de
    service: http://10.7.0.1:4568
  - hostname: idamemory.deine-domain.de
    service: http://10.7.0.1:4571
  - service: http_status:404

(Bzw. im Zero-Trust-Dashboard unter Public Hostname eintragen -- dabei wird i.d.R. automatisch auch der passende DNS-CNAME-Eintrag angelegt.) Danach cloudflared neu laden.

Für idamemory.* zusätzlich zwingend: eine Access-Application einrichten, siehe Abschnitt "Web-Dashboard" weiter unten -- ohne die ist der komplette Wissensgraph für jeden im Internet lesbar, der den Hostnamen kennt.

3. Als MCP-Connector hinzufügen

Für jede KI, die mitlesen/schreiben soll (z.B. claude.ai -> Einstellungen -> Connectors -> Add custom connector), als URL:

https://memory.deine-domain.de/mcp?token=<MCP_AUTH_TOKEN>

Für die Ida-Telegram-Routine: denselben Connector zusätzlich bei den Konnektoren der Routine auswählen und in den Routine-Anweisungen erwähnen, dass für themenübergreifendes Wissen dieser Connector zu benutzen ist (steht im Ida-Telegram-README bereits als Vorschlag für den Anweisungstext).

Verfügbare MCP-Tools

Namen und Verhalten entsprechen 1:1 dem offiziellen Referenzserver:

Projekt-Tracking: Übergabe-Notiz zwischen KI-Sitzungen

Über die normalen observations hinaus (freier Text, unstrukturiert) gibt es für Entities vom Typ "Projekt" ein optionales, strukturiertes Feld project: {status, beschreibung, geplant, aktualisiert_am}, gesetzt über projekt_info_setzen. Zweck: eine andere KI -- oder dieselbe KI in einer neuen, kontextlosen Sitzung -- soll allein durch dieses Feld verstehen, wo die Arbeit an einem Projekt gerade steht, ohne den Nutzer erneut fragen zu müssen, was schon umgesetzt wurde. Das ist bewusst kein Dashboard-Feature -- der Weg dorthin ist der MCP-Connector, genau wie bei allen anderen Tools:

• status: kurzer aktueller Stand, freier Text (z.B. "Geplant", "In Entwicklung", "Aktiv/Fertig", "Pausiert", "Archiviert").

• beschreibung: was im Projekt bereits umgesetzt ist und funktioniert -- konkret genug, dass eine neue Sitzung direkt weiß, worauf sie aufbaut, nicht nur eine Ein-Satz-Idee.

• geplant: der nächste konkrete Schritt bzw. die Roadmap.

• aktualisiert_am: wird automatisch bei jedem Aufruf gesetzt (UTC).

projekt_info_setzen ändert nur die tatsächlich übergebenen Felder (fehlende = unverändert lassen), legt die Entity bei Bedarf neu an (Standard-Typ "Projekt") und sollte nach jeder inhaltlich relevanten Änderung am Projekt erneut aufgerufen werden, nicht nur einmalig beim Projektstart -- sonst veraltet die Übergabe-Notiz und der eigentliche Zweck geht verloren.

Das project-Feld ist Teil der normalen Entity und taucht deshalb überall automatisch mit auf, wo Entities zurückgegeben werden -- search_nodes, open_nodes, read_graph -- eine KI muss projekte_liste also gar nicht kennen, um beim Nachschlagen eines bekannten Projektnamens den Stand zu sehen; projekte_liste() ist nur die schnelle Übersicht über alle Projekte auf einmal, ohne jedes einzeln nachschlagen zu müssen.

Web-Dashboard

Neben den MCP-Tools gibt es ein Browser-Dashboard, um den Wissensgraphen selbst anzusehen -- ohne Umweg über eine KI. Läuft als eigener Container (ida-memory-dashboard, app/dashboard_server.py) auf einem eigenen Port (DASHBOARD_PORT, Standard 4571) und damit auch einem eigenen Cloudflare-Hostnamen -- bewusst getrennt vom MCP-Endpunkt, nicht im selben Prozess:

https://idamemory.deine-domain.de/

Absicherung bewusst anders als beim MCP-Endpunkt: kein MCP_AUTH_TOKEN in der URL -- der Dashboard-Prozess selbst hat gar keinen App-Level-Auth mehr (siehe Sicherheitshinweis im Docstring von app/dashboard_server.py). Stattdessen haengt vor dem Hostnamen eine Cloudflare-Access-Application mit einer Policy, die nur eine bestimmte E-Mail-Adresse per Login-Code durchlaesst -- einmal einloggen, danach merkt sich der Browser das fuer die konfigurierte session_duration (z.B. 30 Tage), ganz ohne einen langen Token manuell einzutippen. Einrichtung: Zero Trust Dashboard -> Access -> Applications -> Add an application -> Self-hosted, Domain = idamemory.deine-domain.de, Policy mit Include-Regel E-Mail = deine Adresse. Wichtig: dieser Hostname darf niemals ohne eine solche Access-Application live gehen -- sonst waere der komplette Wissensgraph oeffentlich lesbar.

• Liste: durchsuchbar, nach Entity-Typ filterbar, seitenweise geladen (nicht alles auf einmal) -- Klick auf eine Karte öffnet die Detailansicht mit allen Beobachtungen und Verknüpfungen.

• Graph: interaktive Knoten-Kanten-Ansicht (Maus/Rad oder Zwei-Finger- Pinch zum Zoomen, ziehbar, Knoten einzeln verschiebbar), zeigt immer den kompletten Graphen, keine Deckelung auf eine Teilmenge -- eigene, synchron vorberechnete Force-Layout-Engine (kein sichtbares "Einpendeln" beim Laden). Knotengröße richtet sich nach Anzahl Verbindungen, nicht nach Beobachtungsanzahl. Klick auf einen Knoten hebt ihn und seine direkten Nachbarn hervor, der Rest wird gedimmt; "Erweitern" laedt gezielt die Nachbarschaft eines Knotens nach (fuer Fokus-Exploration statt alles auf einmal zu betrachten), zusätzlich nach Entity-Typ filterbar wie in der Liste.

• Passt sich responsiv an Desktop, Tablet und Handy an (Material-3-Design, folgt automatisch dem System-Farbschema hell/dunkel).

Backend-seitig (app/dashboard.py, neue Lesefunktionen in app/knowledge_graph.py: list_entities, entity_detail, neighborhood, top_connected, stats) liest dieselbe /data/memory.jsonl wie die MCP-Tools -- eine einzige Quelle der Wahrheit, kein zweiter Speicherpfad, auch wenn es ein eigener Prozess/Container ist (app/dashboard_server.py teilt sich das Docker-Volume mit app/server.py, schreibt aber nie selbst hinein -- _save() schreibt atomar, damit ein gleichzeitiger Lesevorgang nie eine unvollständige Datei zu sehen bekommt). Alles clientseitig in app/dashboard.html (eine Datei, kein Build-Schritt, kein externes JS-Framework, eigene Canvas-Graph-Engine).

Lokal testen ohne Cloudflare

docker compose up -d
curl -H "Authorization: Bearer $MCP_AUTH_TOKEN" http://10.7.0.1:4568/healthz
curl http://10.7.0.1:4571/healthz

Troubleshooting

• Container startet nicht: docker compose logs -- meist fehlt MCP_AUTH_TOKEN in .env.

• Claude/eine KI bekommt 401: Token in Client-Konfiguration und .env vergleichen.

• add_observations meldet "existiert nicht": Die Entity muss vorher über create_entities angelegt werden -- add_observations legt keine neuen Entities an.

• Gedächtnis nach Neustart leer: Prüfen, ob docker compose down (ohne -v) statt versehentlich docker compose down -v benutzt wurde -- -v löscht auch das benannte Volume ida-memory-data.