Memento

Una capa de memoria local-primero, independiente del LLM, para asistentes de IA.

Documentación

Una capa de memoria local-first e independiente del LLM para asistentes de IA
runmemento.com

Cada sesión de IA comienza de la misma manera: re-explicando tus preferencias, las convenciones de tu proyecto, las decisiones que tomaste la semana pasada, los callejones sin salida que evitar. Cada herramienta resuelve esto de su propia manera aislada (CLAUDE.md, .cursorrules, copilot-instructions.md, ChatGPT Memory) — pero tú, el humano, eres la única constante. Tu memoria no debería fragmentarse entre proveedores.

Memento es un lugar donde vive esa memoria. Ejecuta un servidor MCP sobre un archivo SQLite local, de modo que cualquier asistente de IA compatible con MCP — Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, un bot de investigación, un agente personalizado — pueda leer y escribir memoria estructurada y duradera sobre ti, tu trabajo y tus decisiones. Local-first, sin llamadas de red salientes por defecto, sin bloqueo de proveedor.

Claude Chat answering 'what did we lock-in for the dashboard revamp last week?' by recalling memories from Memento — the assistant uses the Memento integration, calls search and confirm, and returns a structured answer with no re-explanation from the user

_{Un chat nuevo sin contexto previo — Memento suministra la memoria de lo que se decidió la semana pasada.}

Inicio rápido

Tres pasos desde cero hasta una capa de memoria funcional:

1. Ejecuta `init` (interactivo en una TTY)

npx @psraghuveer/memento init

Crea la base de datos bajo el valor predeterminado de XDG ($XDG_DATA_HOME/memento/memento.db, típicamente ~/.local/share/memento/memento.db en POSIX), ejecuta las migraciones y — en una TTY — te guía a través de cuatro preguntas de configuración de una sola tecla:

Tu nombre preferido. Se almacena como la clave de configuración user.preferredName para que los recuerdos lean "A Raghu le gusta …" en lugar de "Al usuario le gusta …".
¿Instalar la habilidad incluida? Un y/N. Copia skills/memento/ en ~/.claude/skills/ para clientes que cargan habilidades en formato Anthropic.
¿Sembrar con un paquete inicial? Elige uno de los cuatro paquetes incluidos (engineering-simplicity, pragmatic-programmer, twelve-factor-app, google-sre) para que tu almacén tenga recuerdos útiles desde el primer día. Omite para comenzar vacío.
¿Auto-instalar el fragmento de persona? Detecta clientes de IA en tu máquina y escribe un bloque envuelto en marcadores en el archivo de instrucciones personalizadas de alcance de usuario de cada uno (~/.claude/CLAUDE.md para Claude Code, ~/.config/opencode/AGENTS.md para OpenCode, ~/Documents/Cline/Rules/memento.md para Cline). Idempotente y removible. Los clientes solo de interfaz (Cowork, Claude Desktop, Claude Chat, Cursor User Rules) reciben instrucciones de pegado impresas en su lugar.

Luego imprime fragmentos MCP de copiar y pegar para cada cliente compatible. Idempotente — vuelve a ejecutarlo en cualquier momento para reimprimir los fragmentos y volver a preguntar cualquier cosa que hayas omitido. Pasa --no-prompt para suprimir el flujo interactivo (CI, scripts).

2. Conecta tu cliente de IA

init imprime un subcomando de una línea (donde el cliente incluye uno) o un fragmento JSON para fusionar en la configuración MCP del cliente. Elige el de tu cliente, pégalo y luego reinicia el cliente para que cargue el nuevo servidor MCP.

La guía completa por cliente vive en docs/guides/mcp-client-setup.md.

3. Confirma que el fragmento de persona llega a tu asistente

Memento incluye tres superficies de enseñanza — una columna vertebral MCP instructions en el cable, una habilidad incluida para clientes capaces de habilidades y el fragmento de persona. De las tres, solo el fragmento de persona está garantizado para llegar al prompt del sistema del asistente en cada mensaje — la especificación MCP deja instructions opcional y las implementaciones de clientes varían en si lo muestran; la habilidad se activa por intención, por lo que no se dispara en mensajes neutrales iniciales.

Si dijiste Y al prompt de auto-instalación de persona en el Paso 1, esto ya está hecho para cada cliente basado en archivos detectado en tu máquina — el fragmento se escribió en ~/.claude/CLAUDE.md, ~/.config/opencode/AGENTS.md y/o ~/Documents/Cline/Rules/memento.md según corresponda. Para clientes solo de interfaz (Cowork, Claude Desktop, Claude Chat en claude.ai, Cursor User Rules) y para cualquier cliente que tengas donde el auto-instalador no se activó, copia el fragmento de persona de docs/guides/teach-your-assistant.md y pégalo en la ranura de instrucciones personalizadas / prompt del sistema del cliente (el nombre del campo varía — "Instrucciones personalizadas" en la interfaz de configuración del cliente, etc.).

Eso es todo. Verifica que el cable funcione de extremo a extremo con npx @psraghuveer/memento verify-setup — un recorrido de ida y vuelta de escritura/búsqueda/limpieza que demuestra que tu asistente realmente puede llamar a Memento.

Luego prueba una sesión nueva: "Recuerda que prefiero pnpm sobre npm para proyectos Node." En la próxima sesión, pregunta "¿Cuál es mi gestor de paquetes preferido?" y el asistente debería recordarlo sin que lo re-expliques.

Siembra tu almacén con un paquete

Una instalación nueva de Memento está vacía. Los paquetes son paquetes YAML curados de recuerdos que puedes instalar en un paso — una guía de stack (Rust + Axum, TypeScript + pnpm, Python + uv…), las convenciones de un equipo o un conjunto personal que autoraste en otra máquina.

memento pack install engineering-simplicity

Ese comando instala uno de los paquetes incluidos — once recuerdos destilados de The Laws of Simplicity de John Maeda. Cuatro paquetes incluidos vienen de fábrica: engineering-simplicity, pragmatic-programmer (los consejos de Hunt & Thomas), twelve-factor-app (Wiggins / Heroku) y google-sre (los libros de SRE de Google). Previsualiza antes de instalar con memento pack preview <id-or-path>; lista lo que está instalado con memento pack list; elimina en cualquier momento con memento pack uninstall <id> --confirm (simulación por defecto).

Los paquetes también son cómo compartes. Autoriza uno desde tus recuerdos existentes con memento pack create, luego distribúyelo como archivo, URL HTTPS o contribución comunitaria. La etiqueta reservada pack:<id>:<version> sella cada recuerdo instalado por paquete para que la procedencia nunca se desvíe. Guía completa: docs/guides/packs.md. Racional de diseño: ADR-0020.

Primeros pasos

Requisitos previos. Node.js ≥ 22.11 y un toolchain de C/C++ para que better-sqlite3 pueda compilar en plataformas sin un prebuild (herramientas de línea de comandos de Xcode en macOS, build-essential en Debian/Ubuntu).

Ejecuta init una vez para configurar todo:

npx @psraghuveer/memento init

init establece la base de datos por defecto en el directorio de datos de XDG; pasa --db /custom/path/memento.db (o establece MEMENTO_DB=/custom/path/memento.db) si quieres una ubicación no predeterminada.

Para ejecutar el servidor directamente (por ejemplo, para depurar):

npx @psraghuveer/memento serve

El servidor escucha en stdio para solicitudes MCP. Para pasar banderas adicionales (por ejemplo, una ubicación de base de datos personalizada):

npx @psraghuveer/memento serve --db ~/.local/share/memento/memento.db

También puedes apuntar a una base de datos existente con la variable de entorno MEMENTO_DB.

Verifica la instalación ejecutando npx @psraghuveer/memento doctor (agrega --quick para omitir las sondas de DB y embedder; agrega --mcp para también escanear archivos de configuración MCP de clientes conocidos). Para un resumen de una pantalla de lo que hay en tu almacén, npx @psraghuveer/memento status. Para inspeccionar lo que tu instalación puede hacer — comandos registrados, configuración actual, ubicación de la base de datos — sin hablar MCP, ejecuta npx @psraghuveer/memento context. Para probar el transporte MCP de extremo a extremo, npx @psraghuveer/memento ping.

Conectar Memento a un cliente MCP (Claude Desktop, Claude Code, Cursor, Cline, OpenCode, modo agente de VS Code, …) está cubierto paso a paso en docs/guides/mcp-client-setup.md. El resumen es el inicio rápido de tres pasos anterior: init (que auto-instala el fragmento de persona en clientes basados en archivos detectados si dices Y), pega el fragmento del servidor MCP en tu cliente y luego, para clientes solo de interfaz, pega el fragmento de persona manualmente.

Recuperación vectorial (coincidencia de paráfrasis sobre FTS) está activada por defecto. La primera búsqueda activa una descarga de modelo única (~110 MB) en $XDG_CACHE_HOME/memento/models (o ~/.cache/memento/models / %LOCALAPPDATA%\memento\Cache\models); después de eso, tanto los brazos FTS como vectoriales se ejecutan automáticamente. Si el modelo aún no se ha descargado, la búsqueda se degrada elegantemente a solo FTS. Para opciones de configuración y detalles de integración de bibliotecas, consulta docs/guides/embeddings.md.

Operar el almacén día a día — compact, backup, status, programación — está cubierto en docs/guides/operations.md. El flujo de trabajo de conflictos está en docs/guides/conflicts.md. Para preparar a un asistente de IA sobre cómo usar Memento bien, consulta docs/guides/teach-your-assistant.md — y, si tu cliente carga habilidades en formato Anthropic, instala la habilidad incluida como enriquecimiento por intención sobre el fragmento de persona.

Ve y cura tu almacén en un navegador. npx @psraghuveer/memento dashboard lanza una interfaz web local-first que lee contra tu MEMENTO_DB: conteos de memoria por tipo y alcance, rastro de auditoría, triaje de conflictos, inspección de configuración, paquetes instalados. Solo localhost, protegido por un token aleatorio por lanzamiento en la URL que el lanzador entrega al navegador, sin telemetría. El panel es un paquete hermano (@psraghuveer/memento-dashboard) enviado bajo ADR-0018; consulta docs/guides/dashboard.md para el recorrido completo.

¿Atascado? Los modos de fallo comunes (errores de compilación de better-sqlite3, command not found: memento, STORAGE_ERRORs, dependencia de embedder faltante) están cubiertos en docs/guides/troubleshooting.md.

Para el flujo de trabajo de contribuidores (ramificación, convenciones de commits, lista de verificación de PR) consulta CONTRIBUTING.md. Los agentes de IA que trabajan en el código deben leer también AGENTS.md.

Principios rectores

Estos son los cuatro principios contra los que se juzga cada decisión de diseño. Están documentados en detalle en ARCHITECTURE.md.

Primeros principios. Cada constructo existe porque demostramos que lo necesitamos, no porque así es como se hacen las cosas normalmente.
Modular. Cualquier componente puede reemplazarse sin reescribir el resto.
Extensible. Las nuevas variantes no requieren cambios disruptivos.
Configurado por el usuario. El comportamiento se forma por configuración, no por código.

Qué es Memento

Cuatro pilares. Las mismas cuatro palabras usadas en todos lados donde se describe esto.

Local. Un archivo SQLite bajo tu directorio de inicio. Sin nube, sin telemetría, sin llamadas de red salientes por defecto. Totalmente fuera de línea.
Tipado. Cinco tipos de memoria — fact, preference, decision, todo, snippet — con campos específicos por tipo (una decisión lleva su justificación, un todo su fecha de vencimiento, un fragmento su lenguaje). El asistente puede razonar sobre lo que sigue siendo cierto, no solo recuperar blobs de texto.
Auditado. Cada escritura produce un evento en un registro de solo apéndice. Los conflictos salen a la superficie para triaje en lugar de coexistir silenciosamente. Los recuerdos decaen si no los confirmas. Puedes responder "¿por qué está esto aquí?" y "¿cuándo cambió?" en cualquier momento.
Tuyo. Comportamiento configurable (cada peso de recuperación, cada vida media de decaimiento, cada regla de depurador), exportación e importación JSONL, Apache-2.0. Lleva tu memoria entre máquinas, vete en cualquier momento. Sin bloqueo de proveedor.

Además: independiente del LLM (funciona con cualquier modelo al que hable tu cliente), nativo de MCP (Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, agentes personalizados), consciente de la privacidad (el depurador de regex elimina secretos antes de la persistencia; los patrones son configurables por el usuario).

Qué no es Memento

No es un almacén de historial de chat. Registra memoria destilada y estructurada — preferencias, hechos, episodios, lecciones — no transcripciones crudas.
No es un grafo de conocimiento ni una base de datos semántica. Usa las herramientas adecuadas para eso.
No es un servicio en la nube. La memoria vive en tu máquina; los embedders en la nube, la sincronización entre máquinas y la memoria compartida en equipo no son parte del producto.
No es una plataforma de plugins. La arquitectura deja la puerta abierta, pero Memento se envía con una superficie fija para mantener el estándar de calidad.

La lista completa de fuera de alcance y limitaciones actuales está en KNOWN_LIMITATIONS.md.

Cómo encaja todo

┌─────────────────────────────────────────────────────────┐
│  Clients: Claude Desktop, Claude Code, Cursor, Copilot, │
│           OpenCode, custom agents, …                    │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP (stdio)
┌──────────────────────▼──────────────────────────────────┐
│  memento-server (MCP adapter)                           │
└──────────────────────┬──────────────────────────────────┘
                       │ Command registry
┌──────────────────────▼──────────────────────────────────┐
│  memento-core: services, scope resolver, scrubber,      │
│                conflict detector, decay engine          │
└──────────────────────┬──────────────────────────────────┘
                       │ Repository interfaces
┌──────────────────────▼──────────────────────────────────┐
│  SQLite (better-sqlite3) + FTS5 + optional sqlite-vec   │
└─────────────────────────────────────────────────────────┘

Un recorrido arquitectónico completo se encuentra en ARCHITECTURE.md. Cada decisión significativa tiene un Registro de Decisiones de Arquitectura.

Para contribuyentes (humanos o IA)

Se aceptan contribuciones tanto de autores humanos como asistidos por IA. Los tratamos con los mismos estándares.

Lee AGENTS.md si eres un agente de IA o trabajas con uno. Es el conjunto de instrucciones canónico; CLAUDE.md y .github/copilot-instructions.md son referencias breves al mismo.
Lee CONTRIBUTING.md para la configuración de desarrollo, ramas, convenciones de commits y el ciclo de vida de los PR.
Abre un issue de propuesta de diseño antes de cualquier cambio no trivial.
Usa la plantilla de PR. Te pide que justifiques, no solo que describas, el cambio.

Usamos GitHub Discussions para preguntas e ideas; el rastreador de issues es para errores y trabajo aceptado.

Licencia

Apache-2.0. Consulta NOTICE para la atribución.

Paquetes

Memento es un pequeño workspace de paquetes enfocados. La arquitectura está documentada en docs/architecture/ y las decisiones de diseño en docs/adr/; ambos son la fuente de verdad de qué hace Memento y por qué.

Paquete	Notas
`@psraghuveer/memento-schema`	Esquemas de memoria / evento / alcance / depurador / conflicto / configuración / resultado, más esquemas de valores por `ConfigKey`.
`@psraghuveer/memento-core`	Almacenamiento y migraciones, repositorios de memoria + eventos, resolvedor de alcance, depurador, motor de decaimiento con pasada de archivado `compact`, detección de conflictos + flujo de supersesión, hook de embeddings + driver de re-embedding masivo, interfaz `EmbeddingProvider`, pipeline de recuperación vectorial FTS + fuerza bruta + ranker, y el registro de comandos con ruta de ejecución con validación (ADR 0003).
`@psraghuveer/memento-server`	Adaptador MCP — `buildMementoServer` proyecta el registro de comandos `@psraghuveer/memento-core` como herramientas MCP; `serveStdio` lo conecta a stdio. Usado por `memento serve`.
`@psraghuveer/memento-embedder-local`	`EmbeddingProvider` local respaldado por transformers.js + `bge-base-en-v1.5`. Se distribuye como dependencia regular; la inicialización lazy single-flight descarga el modelo en el primer uso. Ver ADR 0006.
`@psraghuveer/memento` (CLI)	El binario `memento` publicado (`npx @psraghuveer/memento` o `npm i -g @psraghuveer/memento`). Comandos de ciclo de vida (`init`, `serve`, `dashboard`, `context`, `doctor`, `verify-setup`, `status`, `ping`, `backup`, `export`, `import`, `pack`, `store migrate`, `completions`, `explain`, `skill-path`, `uninstall`) más una proyección genérica de la superficie del registro (`memento <namespace> <verb>`). Ver docs/reference/cli.md.
`@psraghuveer/memento-dashboard`	Panel web local-first. Servidor Hono en proceso con el motor + SPA de React construida con Vite. Lanzado por `memento dashboard`; se vincula solo a `127.0.0.1`. Ver ADR-0018 y docs/guides/dashboard.md.
`@psraghuveer/memento-landing`	Página de aterrizaje de marketing. SPA estática, desplegada en GitHub Pages en cada push a main que toque `packages/landing/**`. Refleja los design tokens del panel; alternancia claro/oscuro. Privada (no publicada en npm).