memo-bank

Tus especificaciones son contratos. Esto hace que un agente las lea antes de editar tu código — y te dice cuándo quedan obsoletas.

memo-bank es un servidor MCP de solo lectura sobre un corpus markdown nativo de git, más dos bucles de mantenimiento que mantienen la integridad de ese corpus. Apunta a un repositorio y un agente puede responder «¿qué reglas rigen este archivo?» en unas dos lecturas, en lugar de volver a deducir la respuesta a partir de cuarenta archivos cada vez.

Licencia MIT · Python ≥3.11 · tres dependencias (mcp, python-frontmatter, PyYAML).

Por qué

La documentación se pudre de dos maneras distintas, y la mayoría de las herramientas no aborda ninguna de las dos:

• Ausencia — existe código que ninguna documentación rige. `el bucle de cobertura saca a la superficie el código sin cubrir que se está editando de verdad como una lista priorizada de especificaciones deseadas.

• Desactualización — existe una documentación, pero el código ha avanzado. el **chequeo de desvío** marca cualquier documento de referencia cuyos archivos regidos hayan cambiado después de su last_reviewed`.

Ambos se ejecutan de forma no bloqueante en pre-commit. Ninguno inventa contenido: te dicen qué escribir y cuándo revisarlo, y el corpus sigue siendo Markdown simple en git.

Related MCP server: cardloom-mcp

Instalación

pip install -e '.[dev]'      # from a clone; PyPI publishing not set up yet
memobank --help

Uso

¿Vas a adoptar memo-bank en un proyecto nuevo? Ver SCAFFOLDING.md.

memobank init --target ../my-project --island my-project --slice umbrella=.
memobank validate ../my-project --index docs/index.json
memobank serve    --federation ../my-project/.island-slices.json   # the MCP server
memobank coverage --mode staged                                    # missing specs
memobank drift    --registry .island-slices.json                   # stale specs
memobank benchmark --federation .island-slices.json                # time-to-context

init solo escribe lo que es propiedad del proyecto — .island-slices.json, AGENTS.md, el esqueleto del corpus y las plantillas de autoría. No se copia código del motor, por lo que un proyecto nunca puede llevar un motor bifurcado que quede obsoleto y fuera de sincronía.

Mira cómo funciona

Estás a punto de editar un archivo. Pregunta qué lo define:

$ memobank serve … →  docs.resolve_path("src/services/api.ts")

  hmac-signing-client   (matched glob: src/services/api.ts)
  → docs.get("hmac-signing-client") → the contract you must satisfy:
      "NEVER log the server token, even partially."
      "NEVER sign a path that differs from what the server receives."

Dos lecturas y tienes en la mano la regla que te habría mordido. Pregunta por un tema en su lugar, y la expansión es lo que hace que la búsqueda léxica acierte:

docs.search_live("crawling reviews")                      →  top hit, score  3.0
docs.search_live("refresh fetch ingest cache stale quota") →  top hit, score 32.0

Mismo corpus, misma intención: la segunda consulta usa las palabras que la documentación utiliza de verdad.

Luego, los bucles hacen que siga siendo honrada:

$ memobank coverage --mode staged
⚠ 1 changed file(s) have no governing spec — added to the spec-wanted backlog:
  - src/services/audio.ts

$ memobank drift --registry .island-slices.json
⚠ 1 governing doc(s) may be stale — governed code changed since their last_reviewed:
  - review-ingestion-status (last_reviewed 2026-06-27) — 7 changed: …

El modelo de corpus

Cada slice (un repositorio, o un subproyecto dentro de uno) es dueño de docs/{specs,state,archive}/:

Frontmatter es un esquema validado; applies_to globs son la superficie de precedencia (el globo más cercano gana), y las referencias cruzadas son identificadores estables del tipo kind:id en lugar de rutas. Las especificaciones se escriben de forma independiente de la implementación — cinco secciones (Problem · Contract · Restrictions · Open threads · Code references), con referencias de archivos concretas confinadas a la última sección, para que el contrato sobreviva a los refactors.

Las herramientas (superficie MCP)

Herramientas disponibles: docs.list, docs.get, docs.get_section, docs.resolve_path, docs.search_live, docs.search_archive, docs.resolve_term, docs.compose_context.

Forman una escalera de carga incremental: punteros → una sección → un documento → búsqueda clasificada → un sistema limitado por presupuesto. La recuperación es léxica (bag-of-words, sin embeddings, sin bloqueo comercial), por lo tanto expande una consulta temática con sinónimos del dominio antes de buscar. La propia descripción de docs.search_live lo dice, y en la práctica se multiplicó aproximadamente por 10 la puntuación de los resultados principales.

docs.resolve_term lee un mapa de términos de .haft/specs/term-map.md o el de documentación docs/_terms/term-map.md; con ninguno de los dos, reporta absent en lugar de fallar. se precisa ninguna otra herramienta.

Configuración

Un solo archivo, .island-slices.json, es todo el contrato de adopción:

{
  "island": "my-project",
  "slices": [{ "name": "umbrella", "root": "." },
             { "name": "api", "root": "services/api" }],
  "source_globs": ["src/**"],
  "schema": "docs/specs/schema-frontmatter-v1.md"
}

Solo se requiere slices; todo lo demás es opcional con valores por defecto. Esta máquina no lleva literales de proyecto.

Estado

Software en funcionamiento, usado en proyectos reales — no es un producto pulido. Limitaciones conocidas: el vocabulario island / slices se heredó del primer proyecto que lo usó, memobank init no instala el hook de git (copia hooks/pre-commit tu mismo), last_reviewed tiene gran parte de granularidad de fecha, así que los cambios hechos el mismo día podrían volver a señalarse; mcp está fijado a <2 (el 2.x cambió en la API de Server — sin probar).

Las contribuciones son bienvenidas — ver **CONTRIBUTING.md también.

Licencia

MIT — ver LICENSE.