Gemeinsamer, beständiger Speicher für Codierungsagenten.
Die Art von Speicher, die überlebt, wenn man mitten im Projekt von Claude Code zu Codex zu Cursor wechselt — und überlebt, wenn einem in einem davon die Tokens ausgehen.
Wenn du jemals einen Kontextfenster durchgebrannt hast, ein anderes Tool geöffnet hast und dann zehn Minuten damit verbracht hast, noch einmal zu erklären, was du getan hast, dann ist das hier für dieses Problem. BlueOcean Vector betreibt einen kleinen Server auf deinem Rechner. Jeder MCP-fähige Agent kann daraus lesen und hineinschreiben. Egal, welches Tool du als nächstes öffnest, es fragt einfach: "Was wissen wir über dieses Projekt?" und macht dort weiter, wo das letzte aufgehört hat.
[!TIP] Speichere eine Entscheidung in Claude Code → öffne morgen Codex → es weiß bereits, warum du Postgres DynamoDB vorgezogen hast, nicht nur, dass du es getan hast.
Related MCP server: AIVectorMemory
Jede Agentensitzung beginnt bei Null. Du erklärst das Projekt, die Einschränkungen, das "das haben wir schon versucht, es hat nicht funktioniert" — und dann endet die Sitzung und alles ist weg. Multipliziere das mit jedem Tool, das du verwendest, und du gibst echte Tokens nur dafür aus, Kontext wiederherzustellen, der vor einer Stunde noch existiert hat.
BlueOcean Vector ist eine kleine, langweilige Lösung: ein gemeinsamer Speicher, eine URL und ein gemeinsamer Satz von Tools (memory_store, memory_search, memory_summarize_session und ein paar mehr), die jeder MCP-Client aufrufen kann. Es versucht nicht, klug zu entscheiden, was erinnert werden soll — es gibt Agenten einfach einen Ort, an dem sie Dinge ablegen und wieder abholen können, begrenzt auf das jeweilige Projekt, damit eine Suche in einer Codebasis kein Rauschen aus einer anderen an die Oberfläche bringt.
Es gibt bereits ein gut besiedeltes Feld von "Speicher für KI-Agenten"-Projekten. Es ist fair, klar zu sagen, wo dieses hier tatsächlich steht, anstatt so zu tun, als wäre der Bereich leer.
Projekt | Wie ein Agent damit kommuniziert | Wer entscheidet, was erinnert wird | Semantische Vektorsuche |
SDK / gehostete API | Automatisch — ein LLM extrahiert Fakten bei der Aufnahme | Ja, hinter der Extraktionsebene verborgen | |
SDK oder ein offizieller MCP-Server | Automatisch — Entitäten/Beziehungen werden in einen Wissensgraphen extrahiert | Sekundär zur Graphendurchsuchung | |
Letta (ehemals MemGPT) | Vollständige Stateful-Agent-Plattform, Server + SDK | Halbautomatisch — das eigene LLM des Agenten lagert Speicher ein/aus | Ja, für Archivspeicher |
MCP-nativ, kein Server nötig | Explizit — der aufrufende Agent schreibt | Nur Fallback (~1,8s), Stichwortsuche ist primär | |
threadctx-mcp | MCP-nativ | Explizit + optional passives Git-Einfangen | Bezahlter Cloud-Tarif — Lokaler Modus nur Stichwortsuche |
BlueOcean Vector | MCP-nativ, ein gemeinsamer Server | Explizit — der aufrufende Agent schreibt | Primär und immer aktiv |
Zwei ehrliche Erkenntnisse:
Die Nische "MCP-nativ, funktioniert mit jedem Client" ist nicht leer — Memorix ist bereits dort, mit mehr integrierten Tools. Was hier anders ist: Die Vektorsuche ist der primäre Abrufpfad und kein Fallback oder etwas, das hinter einer Bezahlschranke steckt; das Standard-Embedding-Modell ist wirklich mehrsprachig (Thailändisch+Englisch getestet); und es ist als ein gemeinsamer, beständiger Server gebaut und nicht als ein Tool ohne Installation pro Agent — Bearer-Token-Authentifizierung, ein dokumentierter Pfad zu ECS, Kubernetes-fähige Health-Probes und echte Lösungen für die Nebenläufigkeitsprobleme, auf die ein gemeinsamer Server tatsächlich stößt.
Keine automatische Extraktion oder Konsolidierung — im Gegensatz zu mem0, Graphiti, Letta, cognee oder LangMem liest hier nichts deine Unterhaltung und entscheidet, was es wert ist, erinnert zu werden. Das ist ein bewusster Einfachheits-Kompromiss, kein fehlendes Feature: Ein Agent muss explizit memory_store aufrufen. Wenn du ein System möchtest, das selbstständig darüber nachdenkt, was für dich behalten werden soll, wird eines der oben genannten Projekte das besser können als dieses hier.
Einige Projekte sind eine Million Zeilen Code. Und kein Speichersystem — BlueOcean Vector eingeschlossen — sollte versuchen, sie alle zu speichern. Code zu speichern ist die Aufgabe eines Code-Such-Tools, nicht die eines Speicher-Servers.
BlueOceans Aufgabe ist enger und nützlicher: Merke, was wichtig war, und wo du es findest. Es speichert die Entscheidungen, die Architektur, das "das haben wir versucht, es hat nicht funktioniert" — das kondensierte Wissen, das ein Agent sonst aus einer Million Zeilen wiederentdecken müsste — plus gerade genug Kontext, um den Agenten bei Bedarf wieder auf den eigentlichen Code zu verweisen.
Das Ergebnis ist, dass der Speicher mit dem wächst, was es tatsächlich wert ist, erinnert zu werden, nicht mit der Größe der Codebasis. Ein Projekt mit einer Million Zeilen kann ein paar tausend Speichereinträge haben. Das hält den Abruf kostengünstig, egal wie groß das Projekt wird.
Das Zurücklesen des Speichers ist der Punkt, an dem sich diese Unterscheidung auszahlt. Die billigste Alternative — ein Skill oder Plugin, das Projekthnotizen in eine .remember-Datei schreibt, die ein Agent zurückliest — funktioniert hervorragend, bis die Datei größer als das Kontextfenster wird; dann hört sie leise auf, nützlich zu sein.
BlueOcean begrenzt jede Suche auf ein Token-Budget (Standard 2000 Tokens, konfigurierbar über BLUEOCEAN_MAX_TOKENS). Die semantische Suche zieht nur die relevanten Einträge und teilt dann das Budget auf: ~60 % für kondensierte Zusammenfassungen, ~40 % für den vollständigen Inhalt der besten Treffer. Einträge, die über das Budget hinausgehen, werden abgeschnitten, niemals vollständig ausgegeben.
Ansatz | Kosten pro Abruf | Wächst mit der Speichergröße? |
BlueOcean Vector ( | begrenzt auf das Token-Budget (Standard 2000) | Nein — begrenzt, unabhängig von der Sammlungsgröße |
| entspricht der gesamten Dateigröße | Ja — linear; übersteigt schließlich das Kontextfenster |
| entspricht diesem Abschnitt | Teilweise — aber der Agent muss den Abschnitt erraten, ohne Relevanzbewertung |
Eine echte Suche gegen ein kleines Demoprojekt ergab 121 Tokens für eine Zusammenfassung + einen vollständigen Eintrag — ein paar Prozent des 2000-Token-Budgets, und dieses Budget wächst nie, während das Projekt Speicher ansammelt. Bei einer einfachen Datei kostet derselbe Lesevorgang jedes Mal die gesamte Datei, sodass ein Projekt mit 5k Einträgen (Hunderttausende von Tokens) auf einen Schlag nicht lesbar ist.
┌────────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐ ┌──────┐
│Claude Code │ │Cursor│ │ Codex │ │Gemini/Antigrav│ │ Kiro │ ...any MCP-http tool
└─────┬──────┘ └──┬───┘ └───┬────┘ └───────┬───────┘ └──┬───┘
└───────────┴─────────┴──────────────┴────────────┘
│ http://localhost:8765/mcp
┌───────────────────────────┐
│ blueocean-mcp │ Python MCP server
│ (one shared, persistent │ (docker compose)
│ server, not per-agent) │
└─────────────┬─────────────┘
│
┌───────────────────────────┐
│ Qdrant (vector DB) │ Docker locally → ECS Fargate in the cloud
└───────────────────────────┘Ein paar Designentscheidungen, die es wert sind, bekannt zu sein:
Entscheidung | Warum |
Ein Server, erreichbar per URL | Jeder gängige MCP-Client (und viele Nischen-Clients) hat seinen eigenen Befehl "Remote-Server hinzufügen". Zeige sie alle auf dieselbe URL und keiner benötigt von uns eine maßgeschneiderte Konfigurationsdatei-Bearbeitung. |
Qdrant darunter, eine Sammlung pro Projekt | Speicher für |
Standardmäßig mehrsprachig | Das Embedding-Modell ist |
Token-budgetierte Lesevorgänge |
|
Der stdio-Transport funktioniert auch, wenn du bevorzugst, dass jedes Tool seinen eigenen lokalen Prozess startet, anstatt mit dem gemeinsamen Server zu kommunizieren — siehe Alternative: stdio unten. Der gemeinsame HTTP-Server ist weiterhin der empfohlene Pfad; stdio startet eine separate Kopie des Embedding-Modells pro Agent.
# 1. Bring up Qdrant + the MCP server (both run in the background via docker compose)
./scripts/setup_local.sh
# 2. Register the URL with whichever agents you use
./scripts/register_mcp.shDas war's. setup_local.sh startet beide Container, wartet darauf, dass Qdrant tatsächlich antwortet (nicht nur "der Prozess wurde gestartet"), kopiert .env.example beim ersten Start nach .env und synchronisiert das Python-Paket. register_mcp.sh ruft dann die mcp add-CLI jedes Tools auf (oder bearbeitet für Cursor direkt ~/.cursor/mcp.json, da Curoris CLI nur bei geöffneter App funktioniert), um es auf http://localhost:8765/mcp zu verweisen.
Für jedes andere MCP-http-fähige Tool, auch für uns unbekannte, gib einfach dieselbe URL über die eigene Funktion "Remote-MCP-Server hinzufügen" des Tools an:
http://localhost:8765/mcpDie Registrierung des Servers macht die Tools verfügbar; es bringt einen Agenten nicht dazu, sie von selbst zu verwenden. scripts/install_skill.sh installiert einen kleinen Skill — "Überprüfe den Speicher zu Beginn einer Sitzung, schreibe hinein, bevor der Kontext knapp wird" — in die von dir verwendeten Agenten, sodass die Gewohnheit da ist, ohne dass du sie in jeder Eingabeaufforderung wiederholen musst:
./scripts/install_skill.sh # interactive picker
./scripts/install_skill.sh all # install into every supported tool found
./scripts/install_skill.sh --list # see what's installed whereEs ist eine einzige kanonische SKILL.md, die in das eigene Skills-Verzeichnis jedes Tools symbolisch verlinkt wird — bearbeite sie einmal, jedes Tool übernimmt die Änderung.
Kein Docker verfügbar, oder du möchtest lieber keinen gemeinsamen Server betreiben? Führe aus:
uv run blueocean-mcp --transport stdio --qdrant-url http://localhost:6333und verweise die MCP-Konfiguration des Tools auf den command (siehe .venv/bin/blueocean-mcp) anstelle einer url.
Tool | Was es tut |
| Einen Eintrag speichern – Inhalt, eine komprimierte Zusammenfassung, eine Wichtigkeitsbewertung und Bereichs-/Modul-Tags |
| Semantische Suche, token-budgetiert: zuerst günstige Zusammenfassungen, dann vollständigen Inhalt für das, was passt |
| Den vollständigen Inhalt eines Eintrags anhand der ID abrufen |
| Einen Eintrag anhand der ID entfernen |
| Alle Projekte auflisten, die eine Speichersammlung haben |
| Vor der Suche anzeigen, welche Bereiche/Module existieren, um die Abfrage sinnvoll einzugrenzen |
| Eine komprimierte Übergabenotiz für den nächsten Agenten hinterlassen |
| Zählungen und Verteilung, hauptsächlich für Administration/Debugging |
Ein sinnvoller Agenten-Workflow: Rufe zu Beginn einer Sitzung memory_manifest und dann memory_search auf, um Kontext günstig zu laden; speichere echte Entscheidungen während der Arbeit (Wichtigkeit 5 für „Warum wir X statt Y gewählt haben“, Wichtigkeit 3 für Routine-Status); rufe memory_summarize_session auf, bevor du das Werkzeug wechselst oder das Budget knapp wird.
Alles befindet sich in .env (kopiere .env.example als Startpunkt). Die Standardeinstellungen funktionieren für die lokale Nutzung auf einem einzelnen Rechner; die interessanten Stellschrauben sind:
BLUEOCEAN_EMBEDDING – fastembed (Standard, lokal und kostenlos), openai oder bedrock. Lege auch BLUEOCEAN_EMBED_MODEL fest: Vektoren, die mit einem Modell geschrieben wurden, können mit einem anderen nicht sinnvoll durchsucht werden, daher müssen lokal und in der Cloud dasselbe Modell verwenden.
BLUEOCEAN_QDRANT_URL – wo Qdrant läuft.
BLUEOCEAN_MAX_TOKENS / BLUEOCEAN_TOP_K – das standardmäßige Suchbudget.
BLUEOCEAN_AUTH_TOKEN – standardmäßig nicht gesetzt (in Ordnung für reine 127.0.0.1-Nutzung). Siehe Sicherheit, wenn du dies über deinen eigenen Rechner hinaus verfügbar machst.
Transport (streamable-http vs stdio) ist ein CLI-Flag, keine Umgebungsvariable – es ist eine Entscheidung „Wie führe ich das aus?“, die beim Start getroffen wird, keine dauerhafte Einstellung.
uv run blueocean-admin stats <project>
uv run blueocean-admin manifest <project>
uv run blueocean-admin list
uv run blueocean-admin export <project>
uv run blueocean-admin prune <project> --older-days 90 --max-importance 2 [--dry-run]
uv run blueocean-admin snapshot <project> [--out ./backups]
uv run blueocean-admin restore <project> <snapshot-file> --yes
uv run blueocean-admin generate-token --write-env[!WARNING] Wenn mehr als eine Agentensitzung ein Projekt gemeinsam nutzt, weiß
prunedas nicht. Es löscht alles, was deinen Filtern entspricht, auch Einträge, die eine andere Sitzung vor fünf Minuten geschrieben hat. Führe zuerst--dry-runaus und bevorzuge enge Filter gegenüber einem breiten Zurücksetzen.
export gibt nur die Nutzdaten als JSON aus (with_vectors=False) – die Wiederherstellung daraus bedeutet, alles von Grund auf neu einzubetten, keine echte Point-in-Time-Wiederherstellung. snapshot/restore verwenden stattdessen Qdrants eigenen nativen Snapshot-Mechanismus: Vektoren, Nutzdaten und Indexzustand, atomar erfasst. snapshot lädt die Datei auf die lokale Festplatte herunter und löscht die serverseitige Kopie, sobald der Download als intakt bestätigt wurde (Backups, die nur innerhalb desselben Qdrant-Volumes leben, das sie sichern, sind keine Backups). restore überschreibt die aktuellen Daten des Projekts, daher ist --yes erforderlich.
Projektnamen werden streng validiert (^[a-z0-9][a-z0-9_-]*$, entsprechend der von diesem Projekt bereits empfohlenen Verzeichnisnamen-Konvention) anstatt stillschweigend normalisiert – zwei Agenten, die leicht unterschiedliche Schreibweisen desselben Projekts erraten ("Team A" vs "team-a"), führten früher ohne Warnung zu einer Zusammenführung in eine Sammlung; jetzt wird der abweichende Name stattdessen abgelehnt.
Testdateien unter tests/ sind eigenständige Skripte (if __name__ == "__main__":), keine von pytest erkannten Dateien – führe sie als Module aus:
uv run python -m tests.smoke
uv run python -m tests.auth
uv run python -m tests.mcp_e2e
uv run python -m tests.backup # real snapshot -> delete collection -> restore cycle
uv run python -m tests.health # /health diagnostics + the cloud-provider self-test TTL cachetests/auth.py prüft speziell, dass nicht authentifizierte und Anfragen mit falschem Token abgelehnt werden (401) und dass ein korrekter Token sowohl über den Header als auch über den ?token=-Query-Param-Pfad funktioniert.
Standardmäßig keine Authentifizierung – sinnvoll für reine 127.0.0.1-Nutzung, nicht sinnvoll, sobald dies von irgendwo anders erreichbar ist.
[!IMPORTANT] Wenn du diesen Server über localhost hinaus verfügbar machst (ein gemeinsam genutzter Rechner, die Cloud), setze
BLUEOCEAN_AUTH_TOKEN, bevor du irgendetwas anderes tust.
uv run blueocean-admin generate-token --write-env
docker compose up -d --force-recreate blueocean-mcp
./scripts/register_mcp.sh # reads the token from .env, re-sends it to every toolNicht jedes Werkzeug kann einen benutzerdefinierten Header setzen, wenn es einen entfernten Server per URL registriert, daher akzeptiert der Server den Token auf zwei Arten und jeder Client verwendet die, die er unterstützt:
Authorization: Bearer <token> – Claude Code, Gemini/Antigravity
?token=<token> in der URL – Codex, Kiro, Cursor
Der stdio-Transport überspringt dies vollständig: Es handelt sich um einen lokal gestarteten Unterprozess, der bereits durch die Betriebssystem-Berechtigungen zum Starten von Prozessen geschützt ist, anstatt im Netzwerk zu sitzen.
GET /health ist bewusst nicht authentifiziert und prüft, ob Qdrant tatsächlich erreichbar ist, nicht nur, ob der Prozess läuft. Es ist das, was der Healthcheck von docker-compose.yml abfragt. Es meldet auch den aktiven Embedding-Anbieter/das aktive Modell und validiert für openai/bedrock (nicht fastembed, dessen Modell-Laden bereits den Prozessstart blockiert) die Anmeldeinformationen über einen kostenlosen Kontrollebenen-Aufruf anstelle des abgerechneten Embed-Endpunkts, wobei das Ergebnis für BLUEOCEAN_HEALTH_EMBED_TTL Sekunden (Standard 60) zwischengespeichert wird, sodass ein 10-Sekunden-Abfrageintervall nicht bei jedem Treffer zu einem Anbieter-API-Aufruf wird:
{"status": "ok", "qdrant": "reachable", "embedding": {"provider": "fastembed", "model": "intfloat/multilingual-e5-large", "ok": true}}Setze den Token über BLUEOCEAN_AUTH_TOKEN (Umgebungsvariable / .env), nicht über das CLI-Flag --auth-token – ein als CLI-Argument übergebener Wert ist für jeden anderen lokalen Benutzer über ps sichtbar. Die Zugriffsprotokollierung ist ebenfalls standardmäßig deaktiviert (access_log=False), da drei der fünf unterstützten Clients den Token als ?token=... senden und ein einfaches Zugriffsprotokoll ihn bei jeder einzelnen Anfrage im Klartext in deinen Protokollen ablegen würde.
docker compose up -d startet zwei langlebige Dienste: qdrant (Port 6333) und blueocean-mcp (Port 8765). Für die Cloud wandern dieselben beiden Dienste zu ECS Fargate (oder Qdrant Cloud plus einem kleinen Fargate/App Runner-Dienst für blueocean-mcp) – registriere die öffentliche URL bei jedem Werkzeug genau so, wie du es lokal tun würdest. Die Dockerfile fixiert das Embedding-Modell, sodass in der Cloud erstellte Vektoren mit denen kompatibel sind, die auf deinem Laptop erstellt wurden.
Kubernetes liest den healthcheck: von docker-compose.yml nicht – es benötigt eigene Probes im Pod-Spezifikation, aber sie können auf denselben Pfad verweisen:
readinessProbe:
httpGet: { path: /health, port: 8765 }
livenessProbe:
httpGet: { path: /health, port: 8765 }qdrant-client ist auf die exakte Version des Qdrant-Servers festgelegt (siehe das Image-Tag in docker-compose.yml). Qdrant versioniert seinen Client und Server im Gleichschritt, und die API hat sich zwischen den Versionen geändert – .search() wurde zugunsten von .query_points() in 1.19 entfernt. Wenn du das Server-Image erhöhst, erhöhe auch qdrant-client entsprechend und führe die Testsuite erneut aus; springe nicht mehrere Versionen auf echten Daten ohne vorherigen Snapshot.
mcp ist auf >=2.0.0,<3.0.0 festgelegt, enger als die meisten Abhängigkeiten hier. Seine API (mcp.server.mcpserver.MCPServer und Verwandte) hat sich zwischen den Versionen erheblich verändert, und eine lockere Einschränkung riskiert, dass ein Docker-Build stillschweigend etwas Inkompatibles auflöst – Docker-Builds verwenden uv.lock nicht.
Embedding-Anbieter und -Modell sind ein Paar. Wechsle eines von beiden und alte Vektoren werden zu unauffindbarem Müll gegenüber neuen. Fixiere das Modell in .env, anstatt einer Bibliotheksvoreinstellung zu vertrauen, die sich unter dir ändern könnte.
MIT – siehe LICENSE.
Delete a single memory entry by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| point_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full disclosure burden. It only says 'Delete', which implies irreversibility, but fails to state this explicitly, required auth scopes, or if the deletion is soft or hard. No annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Could arguably add 'irreversibly' for transparency, but current length is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 required params, 0% coverage, an output schema exists but is not referenced, and 7 siblings. The description is too minimal; it omits return value info, ID source hints, and deletion semantics. Incomplete for reliable agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It does not explain what 'project' or 'point_id' represent, their formats, or any validation rules. The description adds no paramenter meaning beyond the schema's field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a single memory entry'), differentiated from siblings like memory_store or memory_search. The 'by ID' detail specifies the key identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives (e.g., memory_summarize_session might delete differently), no prerequisites for which IDs are valid, and no consequences like cascading effects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the full content of a single memory entry by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| point_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full behavioral burden. It states it retrieves content, but it does not disclose any side effects (none expected for get), permissions needed, or error behavior (e.g., what happens if point_id not found). The lack of annotations is mitigated by the read-only nature implied by 'Fetch', but more context on behavior would improve the score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, short and front-loaded with action and object. It contains no redundant information, earning its place. However, it lacks any additional detail that could make it more helpful without expanding much.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is adequate for a basic retrieval. However, it leaves gaps: the 'project' parameter is unexplained, and the response format is not described (no output schema). A more complete description could clarify the project scope or that the full content is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description mentions 'by ID' which aligns with 'point_id', but it does not explain the 'project' parameter's role or provide any context beyond what the schema already offers. The description adds minimal value, leaving the agent to infer the purpose of 'project'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), identifies the resource ('a single memory entry'), and specifies the retrieval mode ('full content by ID'). It clearly distinguishes from sibling tools like memory_search (searches) or memory_list_projects (lists), as it targets a single entry by a unique identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is clear but does not provide explicit guidance on when to use this tool vs alternatives. It implies usage for retrieving a known memory entry by ID, but it does not mention when not to use it (e.g., for partial content) or direct the agent to other tools like memory_search for lookup by content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects that have a memory collection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'List all projects,' failing to disclose read-only nature, return format, authentication needs, or any side effects. This is insufficient for safe agent usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no unnecessary words. Every part adds value, and it is front-loaded with the action and target.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and low complexity, the description should clarify what is returned (list of project names? IDs?). It is adequate for a simple listing but incomplete for an agent to fully understand the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so schema coverage is 100% by default. Per guidelines, 0 params yields a baseline of 4. The description adds no param semantics, but none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'all projects that have a memory collection,' using a specific verb and resource. It is distinct from sibling tools like memory_store or memory_search, though it does not explicitly differentiate from memory_stats or memory_manifest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives (e.g., memory_stats might list stats). The description only states what it does, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the areas/modules present in a project's memory.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It does not mention whether the operation is read-only, what happens if the project does not exist, or any side effects (likely none). The verb 'Show' implies a read operation, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is very concise. However, it is somewhat under-specified for a tool with no annotations and no param descriptions, so it leans slightly toward being too brief rather than optimally informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (1 required param, no annotations, no output schema), the description is incomplete. It does not explain what 'areas/modules' mean, what the output format looks like, or how this differs from memory_stats. An agent would need to infer too much.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the single parameter 'project'. It does not explain what valid project values are, how to specify them (e.g., name, ID), or whether the parameter is case-sensitive. This leaves the agent guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Show' and the resource 'areas/modules present in a project's memory', which is specific and distinguishes it from siblings like memory_stats (which likely shows statistics) or memory_store (which stores data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as memory_stats or memory_search. The description does not provide context about what kind of memory overview this offers or when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search a project's memory with token-budgeted return (summary + full layers).
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | ||
| query | Yes | ||
| top_k | No | ||
| module | No | ||
| project | Yes | ||
| max_tokens | No | ||
| importance_min | No | ||
| time_range_end | No | ||
| time_range_start | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It hints at token budgeting and a two-layer result structure, but it doesn't disclose what happens when the token budget is exceeded (truncation? sorting?), whether the tool is idempotent/read-only, or any rate-limit concerns. For a semantic search that returns multiple entries, key behavioral traits like ordering (by relevance?) and result format are underspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It could improve clarity by unpacking jargon like 'full layers' and 'token-budgeted return', but it remains concise and scannable. A small structure improvement would be breaking into two sentences for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (9 parameters, zero descriptions, no output schema), a one-line description is vastly insufficient. It omits the return format structure, ordering, how filters combine, and the role of the token budget. The agent cannot reliably determine how to craft calls or interpret results from this definition alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the nine parameters, so the description must compensate. It mentions 'query' and 'token-budgeted' (mapped to max_tokens) but fails to explain area, module, top_k, importance_min, time_range_start, time_range_end, or their interplay. Most parameters remain opaque to the agent, making effective invocation difficult.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as performing a semantic search over a project's memory with a token-budgeted return that includes both a summary and full layers. This distnguishes it from siblings like memory_get (exact retrieval) and memory_store (write), but it doesn't explicitly contrast them. The purpose is well-stated but could be strengthened by naming when to prefer this over other memory tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use semantic search vs. the alternative memory tools like memory_get or memory_list_projects. It doesn't state prerequisites, restrictions (e.g., project must exist), or typical use cases. With seven siblings, explicit 'when to use' advice is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Admin: collection stats (count, importance/area distribution, size).
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It mentions the output includes 'count, importance/area distribution, size' but does not explicitly state that the operation is read-only, what permissions are required beyond 'Admin', whether any side effects occur, or if rate limits apply. The safety profile is only implied by the nature of 'stats'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one short sentence with no filler. It front-loads the key information ('Admin: collection stats') and then lists the statistics provided. However, it could be slightly more informative without losing conciseness (e.g., specifying the parameter). It earns its place but is at the edge of under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the high-level output but omits the return format (e.g., object keys, data types) and any explanation of valid values for 'project'. With no output schema, the agent might need to guess the structure. The description is minimally complete for a stats retrieval but lacks enough detail for reliable invocation without domain knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required parameter 'project'. The description does not explain what 'project' represents (e.g., project name, ID, or path) or how to use it. The phrase 'collection stats' loosely ties to the parameter, but the agent is left guessing whether 'project' refers to a project identifier or a collection name. The description adds no semantic value beyond the schema's bare type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it provides admin-level collection statistics including count, importance/area distribution, and size. This distinguishes it from sibling tools like memory_list_projects (which lists projects) and memory_search (which searches within a collection). The verb 'stats' implies retrieval, and the resource is 'collection stats', making the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The prefix 'Admin:' hints at restricted access, but there is no explicit statement of prerequisites, user roles, or scenarios where other tools (e.g., memory_list_projects, memory_get) would be more appropriate. The agent receives no help in deciding between memory_stats and its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a memory entry for a project (content + condensed summary + importance + area/module).
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | ||
| module | Yes | ||
| content | Yes | ||
| project | Yes | ||
| summary | Yes | ||
| metadata | No | ||
| importance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions persistence but does not state whether this is a create or update operation, if it overwrites existing entries, or what idempotency guarantees exist. For a tool that stores data, these details are critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It effectively conveys the core action, but could benefit from a second sentence to cover usage guidance or behavioral notes without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, 0% schema coverage, no annotations, and an output schema (not described), the description is incomplete. It fails to clarify what the tool returns, how conflicts are handled, or how 'importance' is interpreted. The sibling tools suggest a rich system, but this description lacks enough detail for an agent to use it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate. It mentions content, summary, importance, area, and module but adds no extra context (e.g., format, constraints, or relationships). The 'metadata' and 'importance' parameters lack any semantic explanation beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it persists a memory entry and lists the key fields (content, condensed summary, importance, area/module). It distinguishes the tool from siblings like memory_search and memory_get, but could be more explicit about its unique role among the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives like memory_summarize_session or memory_manifest. It does not specify prerequisites, when not to use it, or how it fits into the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a condensed summary of a work session for later retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | ||
| project | Yes | ||
| conclusion | Yes | ||
| importance | No | ||
| session_id | Yes | ||
| observations | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only states 'store for later retrieval' without disclosing side effects like overwriting, idempotency, or dependencies. With no annotations, the bare description fails to convey behavioral traits beyond basic write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, which is very concise. However, it lacks any structure (e.g., bullet points, examples) and does not earn its place by providing sufficient information for a tool with 6 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters (5 required), 0% schema coverage, and no annotations, the description is severely incomplete. It does not explain the purpose of each parameter, expected output, or constraints, making it inadequate for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no parameter-level meaning. The agent receives no explanation for fields like project, area, observations, conclusion, session_id, or importance, leaving critical semantics ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores a condensed summary of a work session, using a specific verb and resource. It distinguishes from generic memory_store by emphasizing session summaries, but does not explicitly differentiate from siblings like memory_store or memory_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., memory_store for raw data, memory_search for retrieval). The description lacks context for prerequisites or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0memory_deletememory_getmemory_list_projectsmemory_manifestmemory_searchmemory_statsmemory_storememory_summarize_sessionScored across 8 tools
Each tool targets a distinct memory operation: stats, store, search, get by ID, delete, list projects, manifest areas, and session summary. No two tools overlap in purpose, ensuring clear differentiation for an agent.
All tools follow the uniform 'memory_<verb>_<noun>' pattern with snake_case. Verbs are descriptive and consistent (stats, store, search, get, delete, list_projects, manifest, summarize_session), making the set predictable and easy to navigate.
With 8 tools, the surface covers the core memory management lifecycle (create, read, delete, search) plus administrative utilities (stats, manifest, project listing, session summary). This is well-scoped without being excessive or sparse.
The tool set covers the fundamental CRUD operations except for an explicit update/modify tool. While search and get provide read access, and store creates new entries, the absence of an update operation is a minor gap that agents may need to work around.
Long-term memory for AI coding agents: durable project facts, recalled by every MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
An MCP memory server. One memory your agents share — across models, devices and apps.
