Memoria compartida y persistente para agentes de codificación.
El tipo de memoria que sobrevive al cambiar de Claude Code a Codex a Cursor en medio de un proyecto — y sobrevive a que te quedes sin tokens en uno de ellos.
Si alguna vez has consumido una ventana de contexto, abierto una herramienta diferente y luego dedicado diez minutos a reexplicar lo que estabas haciendo, esto es para ese problema. BlueOcean Vector ejecuta un pequeño servidor en tu máquina. Cualquier agente compatible con MCP puede leer de él y escribir en él. La herramienta que abras a continuación simplemente pregunta "¿qué sabemos de este proyecto?" y continúa desde donde la anterior lo dejó.
[!TIP] Guarda una decisión en Claude Code → abre Codex mañana → ya sabe por qué elegiste Postgres sobre DynamoDB, no solo que lo hiciste.
Related MCP server: AIVectorMemory
Cada sesión de agente comienza desde cero. Explicas el proyecto, las restricciones, el "ya lo intentamos, no funcionó" — y luego la sesión termina y todo desaparece. Multiplica eso por cada herramienta que uses, y estás gastando tokens reales solo para restablecer un contexto que ya existía hace una hora.
BlueOcean Vector es una solución pequeña y aburrida: un almacén de memoria compartido, una URL y un conjunto común de herramientas (memory_store, memory_search, memory_summarize_session y algunas más) que cualquier cliente MCP puede llamar. No intenta ser inteligente sobre qué recordar — solo les da a los agentes un lugar para dejar cosas y recuperarlas, con alcance por proyecto para que una búsqueda en un código base no saque a la superficie ruido de otro.
Ya existe un campo bien poblado de proyectos de "memoria para agentes de IA". Vale la pena ser sincero sobre dónde se sitúa este realmente, en lugar de fingir que el espacio está vacío.
Proyecto | Cómo habla un agente con él | Quién decide qué se recuerda | Búsqueda semántica de vectores |
SDK / API alojada | Automático — un LLM extrae hechos al ingerir | Sí, envuelta detrás de la capa de extracción | |
SDK, o un servidor MCP oficial | Automático — entidades/relaciones extraídas en un grafo de conocimiento | Secundario a la travesía del grafo | |
Letta (anteriormente MemGPT) | Plataforma de agente con estado completo, servidor + SDK | Semiautomático — el propio LLM del agente pagina la memoria de entrada/salida | Sí, para memoria de archivo |
Nativo MCP, sin servidor que ejecutar | Explícito — el agente llamante escribe | Solo como respaldo (~1.8s), la búsqueda por palabras clave es primaria | |
threadctx-mcp | Nativo MCP | Explícito + captura pasiva opcional de git | Nivel de nube de pago — el modo local es solo por palabras clave |
BlueOcean Vector | Nativo MCP, un servidor compartido | Explícito — el agente llamante escribe | Principal y siempre activo |
Dos conclusiones honestas:
El nicho "Nativo MCP, funciona con cualquier cliente" no está vacío — Memorix ya vive allí, con más herramientas integradas. Lo que es diferente aquí es que la búsqueda vectorial es la ruta de recuperación principal en lugar de un respaldo o algo detrás de un nivel de pago, el modelo de incrustación predeterminado es genuinamente multilingüe (tailandés+inglés probado), y está construido para ejecutarse como un servidor único, compartido y persistente en lugar de una herramienta por agente sin instalación — autenticación por token de portador, una ruta documentada hacia ECS, sondas de salud listas para Kubernetes y correcciones reales para los problemas de concurrencia que un servidor compartido realmente encuentra.
Sin extracción o consolidación automática — a diferencia de mem0, Graphiti, Letta, cognee o LangMem, nada aquí lee tu conversación y decide qué vale la pena recordar. Eso es una compensación de simplicidad deliberada, no una característica faltante: un agente tiene que llamar explícitamente a memory_store. Si quieres un sistema que razone sobre qué conservar en tu nombre, uno de los proyectos anteriores hará eso mejor que este.
Algunos proyectos tienen un millón de líneas de código. Y ningún sistema de memoria — BlueOcean Vector incluido — debería intentar almacenarlo todo. Almacenar código es trabajo de una herramienta de búsqueda de código, no de un servidor de memoria.
El trabajo de BlueOcean es más estrecho y más útil: recordar lo que importaba, y dónde encontrarlo. Contiene las decisiones, la arquitectura, el "lo intentamos, no funcionó" — el conocimiento condensado que un agente tendría que redescubrir a partir de un millón de líneas — más el contexto justo suficiente para señalar al agente de vuelta al código real cuando necesite detalles.
El resultado es que la memoria crece con lo que realmente vale la pena recordar, no con el tamaño del código base. Un proyecto de un millón de líneas puede tener unos pocos miles de entradas de memoria. Eso mantiene la recuperación barata sin importar lo grande que se vuelva el proyecto.
Leer la memoria es donde esa distinción da sus frutos. La alternativa más barata — una habilidad o plugin que vierte notas del proyecto en un archivo .remember que un agente lee — funciona muy bien hasta que el archivo supera la ventana de contexto, entonces silenciosamente deja de ser útil.
BlueOcean limita cada búsqueda a un presupuesto de tokens (por defecto 2000 tokens, configurable mediante BLUEOCEAN_MAX_TOKENS). La búsqueda semántica extrae solo las entradas relevantes, luego divide el presupuesto: ~60% para resúmenes condensados, ~40% para el contenido completo de los mejores resultados. Las entradas que superan el presupuesto se truncan, nunca se vuelcan por completo.
Enfoque | Costo por recuperación | ¿Crece con el tamaño de la memoria? |
BlueOcean Vector ( | limitado al presupuesto de tokens (por defecto 2000) | No — acotado, independientemente del tamaño de la colección |
Archivo | igual al tamaño total del archivo | Sí — lineal; eventualmente excede la ventana de contexto |
Archivo | igual a esa sección | Parcial — pero el agente debe adivinar qué sección sin clasificación por relevancia |
Una búsqueda real contra un pequeño proyecto de demostración devolvió 121 tokens para un resumen + una entrada completa — un pequeño porcentaje del presupuesto de 2000 tokens, y ese presupuesto nunca crece a medida que el proyecto acumula memoria. Con un archivo simple, la misma lectura cuesta el archivo completo cada vez, por lo que un proyecto de 5k entradas (cientos de miles de tokens) es ilegible de una sola vez.
┌────────────┐ ┌──────┐ ┌────────┐ ┌───────────────┐ ┌──────┐
│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
└───────────────────────────┘Algunas decisiones de diseño que vale la pena conocer:
Decisión | Por qué |
Un servidor, accesible por URL | Cada cliente MCP convencional (y muchas variantes) tiene su propio comando "agregar un servidor remoto". Apúntalos todos a la misma URL y ninguno necesita edición de archivos de configuración personalizada de nuestra parte. |
Qdrant debajo, una colección por proyecto | La memoria de |
Multilingüe por defecto | El modelo de incrustación es |
Lecturas con presupuesto de tokens |
|
El transporte stdio también funciona si prefieres que cada herramienta genere su propio proceso local en lugar de hablar con el servidor compartido — consulta Alternativa: stdio a continuación. El servidor HTTP compartido sigue siendo la ruta recomendada; stdio inicia una copia separada del modelo de incrustación por agente.
# 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.shEso es todo. setup_local.sh inicia ambos contenedores, espera a que Qdrant realmente responda (no solo "el proceso comenzó"), copia .env.example a .env en la primera ejecución y sincroniza el paquete de Python. register_mcp.sh luego llama al CLI mcp add de cada herramienta (o, para Cursor, edita ~/.cursor/mcp.json directamente, ya que el CLI de Cursor solo funciona mientras la aplicación está abierta) para que apunte a http://localhost:8765/mcp.
Para cualquier otra herramienta compatible con MCP-http, incluidas aquellas de las que nunca hemos oído hablar, simplemente proporciona la misma URL a través de la función "agregar servidor MCP remoto" de esa herramienta:
http://localhost:8765/mcpRegistrar el servidor hace que las herramientas estén disponibles; no hace que un agente las busque por sí mismo. scripts/install_skill.sh instala una pequeña habilidad — "revisar la memoria al inicio de una sesión, escribir en ella antes de quedarte sin contexto" — en los agentes que uses, para que el hábito esté presente sin que lo repitas en cada indicación:
./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 un SKILL.md canónico, enlazado simbólicamente en el directorio de habilidades de cada herramienta — edítalo una vez, cada herramienta recoge el cambio.
¿No tienes Docker disponible o prefieres no ejecutar un servidor compartido? Ejecuta:
uv run blueocean-mcp --transport stdio --qdrant-url http://localhost:6333y apunta la configuración MCP de la herramienta al command (consulta .venv/bin/blueocean-mcp) en lugar de una url.
Tool | What it does |
| Guardar una entrada — contenido, un resumen condensado, una puntuación de importancia y etiquetas de área/módulo |
| Búsqueda semántica con presupuesto de tokens: primero resúmenes baratos, contenido completo para lo que quepa |
| Obtener el contenido completo de una entrada por ID |
| Eliminar una entrada por ID |
| Listar todos los proyectos que tienen una colección de memoria |
| Ver qué áreas/módulos existen antes de buscar, para acotar la consulta de forma sensata |
| Dejar una nota de traspaso condensada para el agente que lo retome después |
| Conteos y distribución, principalmente para administración/depuración |
Un flujo de trabajo razonable para el agente: llamar a memory_manifest y luego a memory_search al inicio de una sesión para cargar contexto de forma económica; memory_store decisiones reales sobre la marcha (importancia 5 para "por qué elegimos X sobre Y", importancia 3 para estado rutinario); llamar a memory_summarize_session antes de cambiar de herramienta o cuando quede poco presupuesto.
Todo está en .env (copia .env.example para empezar). Los valores predeterminados funcionan para uso local en una sola máquina; los parámetros interesantes son:
BLUEOCEAN_EMBEDDING — fastembed (predeterminado, local y gratuito), openai o bedrock. Fija también BLUEOCEAN_EMBED_MODEL: los vectores escritos con un modelo no se pueden buscar de forma significativa con otro, por lo que local y nube deben coincidir.
BLUEOCEAN_QDRANT_URL — dónde reside Qdrant.
BLUEOCEAN_MAX_TOKENS / BLUEOCEAN_TOP_K — el presupuesto de búsqueda predeterminado.
BLUEOCEAN_AUTH_TOKEN — no establecido por defecto (válido para uso solo en 127.0.0.1). Consulta Seguridad si expones esto más allá de tu propia máquina.
El transporte (streamable-http vs stdio) es un indicador de CLI, no una variable de entorno — es una elección de "cómo ejecuto esto" que se toma al inicio, no una configuración persistente.
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] Si más de una sesión de agente comparte un proyecto,
pruneno lo sabe. Elimina todo lo que coincida con tus filtros, incluso entradas que otra sesión escribió hace cinco minutos. Ejecuta con--dry-runprimero y prefiere filtros estrechos a un reinicio amplio.
export solo vuelca el payload como JSON (with_vectors=False) — restaurar desde él significa re-embedding todo desde cero, no una restauración real en un punto en el tiempo. snapshot/restore usan el mecanismo de snapshot nativo de Qdrant: vectores, payload y estado del índice, capturados atómicamente. snapshot descarga el archivo al disco local y elimina la copia del servidor una vez que se confirma que la descarga está intacta (las copias de seguridad que viven solo dentro del mismo volumen de Qdrant que están respaldando no son copias de seguridad). restore sobrescribe los datos actuales del proyecto, por lo que requiere --yes.
Los nombres de proyecto se validan estrictamente (^[a-z0-9][a-z0-9_-]*$, coincidiendo con la convención de nombres de directorio que este proyecto ya recomienda) en lugar de normalizarse silenciosamente — dos agentes que adivinan ortografías ligeramente diferentes del mismo proyecto ("Team A" vs "team-a") solían fusionarse en una sola colección sin advertencia; ahora el que no coincide se rechaza.
Los archivos de prueba en tests/ son scripts independientes (if __name__ == "__main__":), no archivos descubiertos por pytest — ejecútalos como módulos:
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 verifica específicamente que las solicitudes no autenticadas y con token incorrecto sean rechazadas (401) y que un token correcto funcione tanto a través del encabezado como de la ruta del parámetro de consulta ?token=.
Sin autenticación por defecto — razonable para uso local solo en 127.0.0.1, no razonable en cuanto esto sea accesible desde cualquier otro lugar.
[!IMPORTANT] Si expones este servidor más allá de localhost (una máquina compartida, la nube), establece
BLUEOCEAN_AUTH_TOKENantes de hacer cualquier otra cosa.
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 toolNo todas las herramientas pueden establecer un encabezado personalizado al registrar un servidor remoto por URL, por lo que el servidor acepta el token de dos maneras y cada cliente usa la que soporta:
Authorization: Bearer <token> — Claude Code, Gemini/Antigravity
?token=<token> on the URL — Codex, Kiro, Cursor
El transporte stdio omite esto por completo: es un subproceso generado localmente, ya controlado por los permisos de generación de procesos del SO en lugar de estar en la red.
GET /health está deliberadamente no autenticado y verifica que Qdrant sea realmente accesible, no solo que el proceso esté vivo. Es lo que sondea el healthcheck de docker-compose.yml. También informa el proveedor/modelo de embedding activo, y para openai/bedrock (no fastembed, cuya carga de modelo ya bloquea el inicio del proceso) valida las credenciales mediante una llamada gratuita al plano de control en lugar del endpoint de embedding facturado, almacenando en caché el resultado durante BLUEOCEAN_HEALTH_EMBED_TTL segundos (por defecto 60) para que un intervalo de sonda de 10s no se convierta en una llamada a la API del proveedor en cada golpe:
{"status": "ok", "qdrant": "reachable", "embedding": {"provider": "fastembed", "model": "intfloat/multilingual-e5-large", "ok": true}}Establece el token mediante BLUEOCEAN_AUTH_TOKEN (variable de entorno / .env), no el indicador de CLI --auth-token — un valor pasado como argumento de CLI es visible para cualquier otro usuario local a través de ps. El registro de acceso a las solicitudes también está desactivado por defecto (access_log=False), ya que tres de los cinco clientes compatibles envían el token como ?token=... y un registro de acceso sin formato lo pondría en texto plano en tus registros en cada solicitud.
docker compose up -d ejecuta dos servicios de larga duración: qdrant (puerto 6333) y blueocean-mcp (puerto 8765). Para la nube, los mismos dos servicios se trasladan a ECS Fargate (o Qdrant Cloud más un pequeño servicio Fargate/App Runner para blueocean-mcp) — registra la URL pública con cada herramienta exactamente como lo harías localmente. El Dockerfile fija el modelo de embedding para que los vectores producidos en la nube sean compatibles con los producidos en tu portátil.
Kubernetes no lee el healthcheck: de docker-compose.yml — necesita sus propias sondas en la especificación del Pod, pero pueden apuntar a la misma ruta:
readinessProbe:
httpGet: { path: /health, port: 8765 }
livenessProbe:
httpGet: { path: /health, port: 8765 }qdrant-client está fijado a la versión exacta del servidor Qdrant (consulta la etiqueta de imagen en docker-compose.yml). Qdrant versiona su cliente y servidor al unísono, y la API ha cambiado entre versiones — .search() fue eliminado en favor de .query_points() en 1.19. Si actualizas la imagen del servidor, actualiza qdrant-client para que coincida y vuelve a ejecutar el conjunto de pruebas; no saltes varias versiones con datos reales sin un snapshot primero.
mcp está fijado >=2.0.0,<3.0.0, más estricto que la mayoría de las dependencias aquí. Su API (mcp.server.mcpserver.MCPServer y similares) ha cambiado significativamente entre versiones, y una restricción flexible corre el riesgo de que una compilación de Docker resuelva silenciosamente algo incompatible — las compilaciones de Docker no usan uv.lock.
El proveedor de embedding y el modelo son un par emparejado. Cambia cualquiera de ellos y los vectores antiguos se convierten en basura no buscable frente a los nuevos. Fija el modelo en .env en lugar de confiar en un valor predeterminado de la biblioteca que podría cambiar sin previo aviso.
MIT — consulta 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.
