AI Memory — MCP Server de Memoria Técnica para Equipos

Servidor MCP (Model Context Protocol) que le da a tu AI asistente memoria persistente. El AI puede buscar, guardar, listar, recuperar contexto reciente, persistir resúmenes de sesión y guardar prompts del usuario como conocimiento técnico almacenado localmente.

Características

Storage primario en LanceDB — Persistencia local en .memoria/
Búsqueda híbrida — Texto plano o semántica (vectorial con LanceDB + embeddings locales)
Chunking inteligente — Divide documentos por secciones ## para recuperación quirúrgica
Filtrado por tipo — Busca solo decisiones, bugfixes, patrones, etc.
Score threshold — Descarta resultados irrelevantes en búsqueda vectorial
Fallback automático — Si la búsqueda vectorial falla, cae a texto plano
Metadata equivalente a frontmatter — Tipo, fecha, proyecto y topic_key; en Markdown histórico/manual se representa como frontmatter YAML
Protección de escritura — Sanitización de nombres, prevención de path traversal, anti-duplicados

Tools MCP expuestas

Tool	Descripción
`buscar_en_memoria`	Busca conocimiento técnico. Acepta `query` (obligatorio) y `type` (opcional)
`guardar_en_memoria`	Guarda una nueva memoria con `title`, `content` y `type`
`actualizar_memoria`	Actualiza el contenido de una memoria existente por `fileName`
`listar_memorias`	Lista todas las memorias con título, tipo y fecha
`mem_context`	Devuelve un resumen de memorias recientes. Acepta `project`, `type` y `limit` (opcionales)
`mem_session_summary`	Guarda un resumen estructurado de sesión. Acepta `content` y `project`
`mem_save_prompt`	Guarda el prompt del usuario. Acepta `content` y `project`
`mem_bootstrap`	Recupera contexto consolidado al inicio de una sesión. Acepta `query`, `project` y `limit`
`mem_checkpoint`	Guarda un checkpoint reusable al cierre de sesión. Acepta `project`, `prompt`, `summary`, `savePrompt`, `saveSummary` y `durableMemories`

Tipos de memoria soportados

decision · bugfix · pattern · config · convention · general · session_summary · prompt

Estructura del proyecto

.memoria/               ← Storage local primario de LanceDB
.github/
  memory/              ← Memorias Markdown históricas o de compatibilidad
  agents/              ← Agentes especializados de memoria (multi-agente)
  prompts/             ← Prompts reutilizables (ej: arranque de sesión)
  skills/              ← Skills de Copilot
.vscode/
  mcp.json             ← Registro del servidor MCP para VS Code
  mcp-server-hybrid/
    src/
      config.ts        ← Configuración centralizada (env vars)
      index.ts         ← Servidor MCP + routing de tools
      lancedbPrimaryStorage.ts ← Storage primario y recuperación en LanceDB
      lexicalSearch.ts ← Boundary interno de búsqueda léxica
      vectorStorage.ts ← Búsqueda híbrida + chunking por ##
      memoryContext.ts ← Contexto reciente sobre memorias existentes
      sessionSummary.ts ← Persistencia estructurada de resúmenes de sesión
      savePrompt.ts    ← Persistencia explícita de prompts del usuario
      sessionBootstrap.ts ← Bootstrap de sesión consolidado
      sessionCheckpoint.ts ← Checkpoint de sesión reutilizable
      memoryWriter.ts  ← Escritura + listado de memorias
    dist/              ← Código compilado
    package.json
    tsconfig.json

Instalación

Bootstrap rápido en Windows

Desde la raiz del repo:

powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap-dev.ps1

Este bootstrap valida Node latest LTS, instala dependencias con npm ci si existe lockfile, compila y corre la bateria critica.

Opciones utiles:

# Intentar instalar o actualizar Node latest LTS con winget antes de seguir
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap-dev.ps1 -UpgradeNodeLts

# Intentar reparar better-sqlite3 para el Node actual
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap-dev.ps1 -RepairNativeModules

# Ejecutar la suite completa en lugar de la bateria critica
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap-dev.ps1 -FullTests

Si la reparacion nativa falla, el bootstrap no bloquea el proyecto: mantiene el flujo con fallback lexico y te deja la advertencia para resolver Python o node-gyp despues.

Python no es requisito para una instalacion base limpia. Solo puede hacer falta si queres reconstruir la dependencia nativa opcional better-sqlite3 para recuperar FTS5/BM25.

Para diagnosticar el entorno nativo manualmente:

cd .vscode/mcp-server-hybrid
npm run doctor:native

Instalación manual

cd .vscode/mcp-server-hybrid
npm ci
npm run build

Si abrís el repositorio en VS Code sin haber corrido todavía la instalación manual, el launcher configurado en .vscode/mcp.json intenta autocurar el primer arranque del MCP: si faltan node_modules ejecuta npm ci y si falta dist/index.js ejecuta npm run build antes de levantar el servidor.

Esto evita el error Cannot find module ... dist/index.js en clones limpios. Para contributors, el camino recomendado sigue siendo correr el bootstrap explícito desde la raíz.

Si better-sqlite3 no puede instalarse o cargar su binding nativo, el servidor sigue arrancando y degrada la búsqueda léxica a substring matching. El único costo es perder FTS5/BM25 hasta que ejecutes npm run rebuild:native en un entorno con Python y toolchain nativo.

Verificar la instalación

Ejecutar los tests unitarios para confirmar que todo funciona:

npm test

Resultado esperado: la suite debe terminar sin fallos. El conteo exacto de tests puede variar a medida que crece la cobertura.

Para verificar la conexión MCP de extremo a extremo desde la raíz del repositorio:

node scripts/mcp-connect-test.mjs

Esto lanza el servidor como proceso hijo, verifica tools/list e invoca además las tools read-only listar_memorias, mem_context y mem_bootstrap. Si el script completa sin error, la conexión y las rutas principales de lectura del runtime están funcionando.

Nota sobre recarga del runtime MCP

Si recompilás el servidor local (npm run build) y seguís viendo errores viejos desde las tools MCP en VS Code, el problema puede ser que el runtime MCP siga usando una instancia previa del servidor.

En ese caso, recargá la ventana de VS Code o reiniciá la sesión MCP antes de volver a probar mem_checkpoint, mem_session_summary o mem_save_prompt.

Nota sobre better-sqlite3 y cambios de versión de Node

Si ves warnings de FTS5/BM25 con mensajes de NODE_MODULE_VERSION o ausencia de better-sqlite3, el servidor ahora degrada a substring matching para no romper la búsqueda en texto plano.

Para recuperar el rendimiento de FTS en el entorno local, ejecutá:

cd .vscode/mcp-server-hybrid
npm run rebuild:native

Después de eso, si estabas usando el servidor desde VS Code Chat, recargá la ventana o reiniciá la sesión MCP.

Recomendación de canal de Node

El repo ya no asume una versión fija como 22 LTS. La política recomendada es usar siempre la latest LTS oficial de Node.js.

Para validar rápido tu entorno local:

cd .vscode/mcp-server-hybrid
npm run doctor:node

Este comando consulta el feed oficial de releases de Node.js y te avisa si estás fuera del canal LTS recomendado hoy.

Recetas operativas

Recompilar el servidor MCP

cd .vscode/mcp-server-hybrid
npm run build

Usar esto despues de cambios en src/ antes de volver a probar el runtime desde VS Code.

Ejecutar la bateria critica de regresion

cd .vscode/mcp-server-hybrid
npm run test:critical

Esta bateria cubre lifecycle de sesion, colisiones de session_summary y contrato de routing.

Generar un snapshot curado para sync futura

cd .vscode/mcp-server-hybrid
npm run export:curated-sync -- --project ai-memory

Esto exporta un snapshot JSON curado bajo .github/memory/exports/<project>/ usando solo memorias versionables (decision, convention, pattern, bugfix, config) y deja afuera prompts o resúmenes transitorios.

Generar un journal incremental curado

cd .vscode/mcp-server-hybrid
npm run export:curated-journal -- --project ai-memory

Esto compara el estado curado actual contra el último snapshot versionado del proyecto y escribe solo eventos upsert nuevos o cambiados bajo .github/memory/exports/<project>/journal/.

Si no hay cambios reales contra el baseline, no escribe ningún archivo ni actualiza manifests para evitar ruido en Git.

Si se usa --base <snapshot> para generar un journal manual contra un baseline explícito, ese archivo no actualiza journal/latest.json y queda fuera de la cadena activa usada por cleanup.

Este comando requiere que ya exista un snapshot curado baseline. Si hace falta, primero corré npm run export:curated-sync -- --project ai-memory.

Previsualizar un journal incremental con dry-run

cd .vscode/mcp-server-hybrid
npm run preview:curated-journal -- --project ai-memory

Esto carga el último journal incremental versionado del proyecto y produce el mismo plan conservador del import manual actual, pero sin aplicar cambios reales.

Importar un journal incremental curado

cd .vscode/mcp-server-hybrid
npm run import:curated-journal -- --project ai-memory --latest

Este comando corre en dry-run por defecto para obligarte a revisar primero el plan incremental conservador.

Para aplicar cambios reales después de esa revisión:

cd .vscode/mcp-server-hybrid
npm run import:curated-journal -- --project ai-memory --latest --apply

También podés usar --file <journal> si querés aplicar un artefacto específico en vez del último journal activo.

Analizar y compactar la cadena incremental

cd .vscode/mcp-server-hybrid
npm run sync:compact -- --project ai-memory --dry-run

Esto informa el baseline actual, cuántos journals existen desde ese baseline, cuántos eventos acumulan y si ya conviene compactar según los umbrales actuales.

Para compactar realmente:

cd .vscode/mcp-server-hybrid
npm run sync:compact -- --project ai-memory

La compactación genera un nuevo snapshot curado baseline y resetea solo el manifest activo del journal. No borra journals históricos automáticamente.

Limpiar journals históricos ya cubiertos

cd .vscode/mcp-server-hybrid
npm run sync:cleanup -- --project ai-memory --dry-run

Esto identifica journals cuyo baseSnapshot ya no coincide con el baseline actual y que, por lo tanto, quedaron cubiertos por una compactación posterior.

La limpieza automática solo considera journals de la cadena activa gestionada por journal/latest.json. Los journals manuales exportados con --base explícito se conservan.

Para borrarlos realmente:

cd .vscode/mcp-server-hybrid
npm run sync:cleanup -- --project ai-memory

La limpieza no toca journals activos del baseline actual.

Simular un import manual del snapshot curado

cd .vscode/mcp-server-hybrid
npm run import:curated-sync -- --file ../../.github/memory/exports/ai-memory/<snapshot>.json

Si querés importar el último snapshot versionado del proyecto sin pasar la ruta manualmente:

cd .vscode/mcp-server-hybrid
npm run import:curated-sync -- --project ai-memory --latest

Y para ejecutar el import real después de revisar el plan:

cd .vscode/mcp-server-hybrid
npm run import:curated-sync -- --project ai-memory --latest --apply

Si necesitás purgar un namespace temporal de proyecto sin tocar la raíz default:

cd .vscode/mcp-server-hybrid
npm run purge:project -- --project tmp-validacion

Y para ejecutar el borrado real después de revisar el plan:

cd .vscode/mcp-server-hybrid
npm run purge:project -- --project tmp-validacion --apply

Si querés hacer el flujo corto de export versionado + preview inmediato del último snapshot con dry-run:

cd .vscode/mcp-server-hybrid
npm run sync:curated-latest -- --project ai-memory

Ese wrapper no aplica imports reales. Solo genera el snapshot versionado por defecto, actualiza latest.json y ejecuta un preview con --latest.

El import manual usa reglas conservadoras:

upsert por topic_key cuando existe identidad estable,
skip si la memoria ya es idéntica en el destino,
conflicto si hay mismo title + type pero distinto contenido sin topic_key.

Cuando el dry-run es satisfactorio, el mismo comando puede ejecutarse con --apply para aplicar el import al storage local activo.

Politica operativa para snapshots curados

La carpeta .github/memory/exports/<project>/ forma parte de la capa versionable del repo. No reemplaza al storage local en .memoria/ ni habilita versionado del estado crudo del runtime.

Reglas operativas:

generar snapshots solo para handoff entre maquinas, milestones, releases o cambios durables relevantes;
versionar solo snapshots curados y su latest.json asociado dentro de .github/memory/exports/<project>/;
actualizar latest.json unicamente junto con el snapshot al que apunta;
no usar exports con --out como fuente para --latest, porque los exports custom no forman parte del flujo versionado del repo;
revisar en PR cualquier cambio en .github/memory/exports/ como artefacto curado, no como ruido autogenerado;
ejecutar primero el import sin --apply para revisar el plan antes de cualquier mutación real en otra maquina o entorno;
no ejecutar el import real si el dry-run reporta conflictos no explicados;
mantener alineados project, carpeta de export y latest.json para que --latest siga siendo confiable.

Checklist minima para importar desde otro entorno:

actualizar el repo hasta el commit que contiene el snapshot y su latest.json;
ejecutar npm run import:curated-sync -- --project <project> --latest;
verificar que el reporte no muestre conflictos inesperados;
recien entonces repetir el comando con --apply para aplicar el import al storage local activo.

Ejecutar solo el contrato de routing

cd .vscode/mcp-server-hybrid
npm run test:routing-contract

Usar esto cuando cambies la politica del Memory Coordinator o la matriz de casos.

Reconstruir better-sqlite3 despues de cambiar Node

cd .vscode/mcp-server-hybrid
npm run rebuild:native

Si seguis viendo comportamiento viejo en VS Code Chat despues del rebuild, recarga la ventana o reinicia la sesion MCP.

Verificar la conexion MCP extremo a extremo

node scripts/mcp-connect-test.mjs

Usar esto desde la raiz del repo para confirmar que el servidor publica las tools esperadas y puede ejecutar llamadas read-only reales sobre el runtime configurado en .vscode/mcp.json.

Flujo Multi-Agente

El proyecto incluye un sistema de agentes especializados en .github/agents/ para flujos de trabajo más complejos:

ID técnico	Nombre visible	Propósito	Herramientas
`memory-coordinator`	`Memory Coordinator` (Coordinador de Memoria)	Orquestador principal: interpreta la intención del usuario y delega	Todos
`memory-archivist`	`Memory Archivist` (Archivista de Memoria)	Guarda y actualiza conocimiento durable (decisiones, patrones, bugfixes)	`guardar_en_memoria`, `actualizar_memoria`, `listar_memorias`
`memory-researcher`	`Memory Researcher` (Investigador de Memoria)	Busca y recupera contexto del equipo	`buscar_en_memoria`, `listar_memorias`, `mem_context`, `mem_bootstrap`
`session-manager`	`Session Manager` (Gestor de Sesion)	Gestiona el ciclo completo de sesion (bootstrap al inicio, checkpoint al cierre)	`mem_bootstrap`, `mem_checkpoint`, `mem_session_summary`, `mem_save_prompt`

Convención recomendada: mantener el ID técnico y el nombre visible en inglés para invocación y routing, y usar el alias en español para explicar responsabilidades en documentación y conversaciones del equipo.

Para usar un agente, seleccionarlo en el selector de agentes de VS Code Chat o invocarlo como sub-agente desde el coordinador. En documentación interna conviene mencionar ambos formatos: el identificador técnico para ejecución y el alias en español para lectura humana.

Para una matriz formal de casos de routing, validación manual rápida y contrato automatizado, ver docs/MATRIZ_DE_CASOS_DE_ROUTING.md.

Prompt de arranque de sesión

El archivo .github/prompts/session-start.prompt.md permite iniciar cualquier sesión con contexto completo escribiendo /session-start en el chat de VS Code Copilot seguido del objetivo de la sesión.

Configuración en VS Code

El servidor se registra en .vscode/mcp.json:

{
  "servers": {
    "aimemory": {
      "command": "node",
      "args": [
        "${workspaceFolder}/.vscode/mcp-server-hybrid/dist/index.js"
      ],
      "env": {
        "USE_VECTOR_SEARCH": "true",
        "MEMORY_PATH": "${workspaceFolder}/.github/memory",
        "LANCEDB_STORAGE_PATH": "${workspaceFolder}/.memoria"
      }
    }
  }
}

Variables de entorno

Variable	Descripción	Default
`MEMORY_PATH`	Ruta a memorias Markdown históricas o de compatibilidad	`../../.github/memory` (relativa)
`LANCEDB_STORAGE_PATH`	Ruta al storage primario de LanceDB	`../../.memoria` (relativa)
`USE_VECTOR_SEARCH`	`"true"` para búsqueda semántica, cualquier otro valor para texto plano	`false`

Modelo de almacenamiento

El storage primario actual vive en .memoria/ y usa LanceDB.
.github/memory/ se mantiene para compatibilidad, documentación histórica y migración/importación desde Markdown cuando haga falta.
La migración a SQLite + FTS5 fue descartada como dirección principal del proyecto.

Formato de memorias

Cada memoria es un archivo Markdown con frontmatter YAML:

---
type: decision
date: 2026-04-20
project: ai-memory
---

# Título de la memoria

Contenido en Markdown...

También pueden incluir topic_key opcional en el frontmatter para representar temas evolutivos:

---
type: decision
date: 2026-04-20
project: ai-memory
topic_key: architecture/search-pipeline
---

Si guardar_en_memoria recibe topic_key, hace upsert semántico dentro del mismo project + type en lugar de crear siempre un archivo nuevo.

`mem_context`

mem_context es la primera tool inspirada directamente en Engram: sirve para retomar trabajo previo sin lanzar una búsqueda libre. En este proyecto, la implementación está adaptada al modelo Markdown y devuelve:

memorias recientes ordenadas por fecha y modificación
preview corto por memoria
conteo por tipo dentro del contexto filtrado
soporte opcional para project, type y limit

`mem_session_summary`

mem_session_summary toma otra idea central de Engram: antes de cerrar una sesión o después de una compactación, el agente puede persistir un resumen curado y reutilizable. En este proyecto:

valida un formato estructurado con secciones obligatorias
guarda la memoria como session_summary
deja ese resumen disponible para mem_context y buscar_en_memoria

Formato esperado:

## Goal
## Instructions
## Discoveries
## Accomplished
## Next Steps
## Relevant Files

Instructions es opcional; las demás secciones son obligatorias.

`mem_save_prompt`

mem_save_prompt toma la intención de Engram de preservar el pedido original del usuario para sesiones futuras. En este proyecto:

guarda el prompt como memoria tipo prompt
rechaza prompts triviales demasiado cortos
deja el texto disponible para mem_context y buscar_en_memoria
usa un título generado con preview + timestamp para evitar colisiones

`mem_bootstrap`

mem_bootstrap consolida el arranque de sesión en una sola respuesta estructurada. Internamente combina:

contexto reciente desde mem_context
relevancia semántica o léxica desde buscar_en_memoria
prioridad para session_summary, decision y convention

La respuesta está organizada en secciones como Active Goal, Open Next Steps, Key Decisions y Memory Hits.

`mem_checkpoint`

mem_checkpoint simplifica el cierre de sesión. Internamente orquesta:

mem_session_summary para persistir el resumen estructurado
mem_save_prompt para preservar la intención del usuario

Permite guardar ambos artefactos juntos o desactivar uno de ellos con savePrompt y saveSummary.

También acepta durableMemories para persistir decisiones, patrones, bugfixes, convenciones, configuraciones o memorias generales detectadas durante la sesión sin hacer llamadas adicionales a guardar_en_memoria.

Flujo de sesión recomendado

Con mem_bootstrap y mem_checkpoint, el flujo recomendado para continuidad entre sesiones es este:

Inicio de sesión

Ejecutar mem_bootstrap con el objetivo actual del usuario.
Revisar las secciones Open Next Steps, Key Decisions y Relevant Files.

Cierre de sesión

Ejecutar mem_checkpoint con el resumen de sesión y el prompt a preservar.
Ejecutar guardar_en_memoria solo si surgió conocimiento durable nuevo.

El diseño propuesto para formalizar este ciclo vive en SESSION_LIFECYCLE.md.

Stack técnico

Runtime: Node.js ≥ 18 (recomendado: latest LTS oficial)
Protocolo: MCP (Model Context Protocol) via @modelcontextprotocol/sdk
Storage persistente: LanceDB en .memoria/
Búsqueda vectorial: LanceDB + @huggingface/transformers (modelo all-MiniLM-L6-v2, corre local)
Fallback léxico: boundary interno en src/lexicalSearch.ts; backend actual con SQLite/FTS5 en memoria vía better-sqlite3 más degradación controlada a substring matching
Lenguaje: TypeScript (ESM puro, NodeNext)
Tests: vitest — suite del servidor validada en el estado actual del repo

Estado Actual Para Handoff

Storage primario: vigente en LanceDB bajo .memoria/.
Cobertura de volumen: existe una prueba unitaria del storage primario con más de 100 memorias en src/lancedbPrimaryStorage.test.ts.
Capa léxica: ya está desacoplada detrás de src/lexicalSearch.ts.
Backend léxico alternativo: la comparación o integración de un reemplazo para better-sqlite3 no está iniciada; quedó cancelada en la última sesión.
Testing guiado vía memorias de ejemplo MCP: fuera de alcance por decisión actual.

Documentación adicional

Documento	Descripción
docs/GUIA_DE_USUARIO.md	Guía completa de uso con ejemplos para cada tool
CONTRIBUTING.md	Cómo desarrollar, agregar tools, convenciones y patrones de seguridad
SESSION_LIFECYCLE.md	Diseño del ciclo bootstrap/checkpoint de sesión
PRD.md	Product Requirements Document

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github		.github
.vscode		.vscode
docs		docs
scripts		scripts
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LANCEDB_AS_PRIMARY_STORAGE.md		LANCEDB_AS_PRIMARY_STORAGE.md
PRD.md		PRD.md
Readme.md		Readme.md
SESSION_LIFECYCLE.md		SESSION_LIFECYCLE.md
SYNC_INCREMENTAL_JOURNAL.md		SYNC_INCREMENTAL_JOURNAL.md

Folders and files

Latest commit

History

Repository files navigation

AI Memory — MCP Server de Memoria Técnica para Equipos

Características

Tools MCP expuestas

Tipos de memoria soportados

Estructura del proyecto

Instalación

Bootstrap rápido en Windows

Instalación manual

Verificar la instalación

Nota sobre recarga del runtime MCP

Nota sobre better-sqlite3 y cambios de versión de Node

Recomendación de canal de Node

Recetas operativas

Recompilar el servidor MCP

Ejecutar la bateria critica de regresion

Generar un snapshot curado para sync futura

Generar un journal incremental curado

Previsualizar un journal incremental con dry-run

Importar un journal incremental curado

Analizar y compactar la cadena incremental

Limpiar journals históricos ya cubiertos

Simular un import manual del snapshot curado

Politica operativa para snapshots curados

Ejecutar solo el contrato de routing

Reconstruir better-sqlite3 despues de cambiar Node

Verificar la conexion MCP extremo a extremo

Flujo Multi-Agente

Prompt de arranque de sesión

Configuración en VS Code

Variables de entorno

Modelo de almacenamiento

Formato de memorias

mem_context

mem_session_summary

mem_save_prompt

mem_bootstrap

mem_checkpoint

Flujo de sesión recomendado

Inicio de sesión

Cierre de sesión

Stack técnico

Estado Actual Para Handoff

Documentación adicional

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`mem_context`

`mem_session_summary`

`mem_save_prompt`

`mem_bootstrap`

`mem_checkpoint`

Packages