Memoria persistente para agentes de programación.
Dale a Claude Code, Codex, Cursor, Windsurf, OpenCode, fx y Pi una memoria local compartida que sobrevive a sesiones, compactaciones y cambios de agente.
Inicio rápido · Por qué mnemo · Agentes · Documentación · Roadmap
--- ## ¿Qué es mnemo? mnemo es una capa de memoria local para desarrollo con agentes. Guarda decisiones, bugs, convenciones, descubrimientos y resúmenes de sesión en SQLite, y los expone de vuelta a los agentes mediante herramientas MCP, hooks y Agent Skills portables. En lugar de repartir conocimiento entre `MEMORY.md`, memorias nativas del editor, transcripciones y notas humanas, mnemo ofrece a todos los agentes soportados una misma fuente de verdad por proyecto. ## Inicio rápido Instala el binario y configura los agentes detectados: ```bash curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash ``` Activa mnemo en un proyecto: ```bash cd tu-proyecto mnemo init --agent=all ``` Comprueba que todo está conectado: ```bash mnemo doctor --agent=all --path=. ``` Guarda y busca memoria manualmente desde CLI: ```bash mnemo save "Usar SQLite FTS5" "La búsqueda queda local, rápida y sin dependencias externas." --type decision --project miapp mnemo search "SQLite" --project miapp ``` ## Por qué mnemo | Problema | mnemo aporta | |---|---| | Los agentes olvidan decisiones entre sesiones | Memoria persistente de proyecto en `~/.mnemo/memory.db` | | Cada agente mantiene una memoria distinta | Una capa compartida para Claude Code, Codex, Cursor, Windsurf, OpenCode, fx y Pi | | Los archivos markdown de memoria se desordenan | Observaciones estructuradas, tags, topic keys y estados de revisión | | Los hooks globales pueden ser peligrosos | Activación opt-in por proyecto mediante `.mnemo`; el resto se ignora | | El setup puede fallar en silencio | `mnemo doctor` y `mnemo setup status` explican qué está configurado | | Se acumulan proyectos o memorias duplicadas | Herramientas de merge de proyectos y curación de memoria | ## Funcionalidades | Funcionalidad | Qué hace | |---|---| | **Activación por proyecto** | Los hooks globales solo actúan cuando existe una marca `.mnemo` válida. | | **Herramientas MCP** | Los agentes pueden usar `mem_save`, `mem_search`, `mem_context`, `mem_current_project`, `mem_doctor` y más. | | **Hooks de sesión** | Registran sesiones, inyectan contexto y capturan aprendizajes automáticamente. | | **Agent Skills portables** | Enseñan a los agentes compatibles cuándo y cómo usar mnemo sin recurrir a memoria nativa. | | **Captura pasiva** | Extrae aprendizajes útiles de transcripciones y salidas de subagentes. | | **Provenance de agentes** | Registra metadatos consultables en SQL sobre agente, origen, tool, modelo y cliente MCP en escrituras que los aportan. | | **Diagnóstico** | `mnemo doctor` comprueba activación, setup global, MCP, hooks, memorias competidoras y salud de migraciones de la base de datos. | | **Seguridad de base de datos** | Las migraciones seguras se aplican automáticamente; `mnemo db migrate --check` valida el store local para CI o troubleshooting. | | **Autoactualización** | Los binarios publicados comprueban nuevas releases en uso interactivo y pueden confirmar, descargar e instalar con `mnemo update`. | | **CLI programable** | La ayuda generada con Cobra mantiene alineados el menú de comandos y sus subcomandos con el ejecutable. | | **Mantenimiento de proyectos** | `mnemo projects list`, `mnemo projects merge` y `mnemo projects rename` ayudan a depurar identidades duplicadas o poco claras. | | **Curación de memoria** | `mnemo memories review` detecta observaciones duplicadas o conflictivas para reparación aprobada. | ## Agentes soportados
curl -sSf https://raw.githubusercontent.com/jmeiracorbal/mnemo/main/install.sh | bash |
| Agente explícito | Solo quieres una integración | `bash -s -- --agent=codex` |
| Todos los agentes | Quieres preparar todas las integraciones | `bash -s -- --agent=all` |
| Plugin de Claude | Usas el marketplace de Claude Code | `claude plugin install mnemo@mnemo` |
| Build desde fuente | Desarrollas mnemo | `go build -o ~/.local/bin/mnemo ./cmd/mnemo/` |
Consulta la guía completa en [docs/INSTALLATION.md](docs/INSTALLATION.md).
### Actualizaciones
Los binarios publicados de mnemo comprueban GitHub Releases durante el uso CLI
interactivo. Si existe una release más nueva, mnemo muestra las versiones
instalada/disponible y pregunta antes de modificar nada:
```bash
mnemo update
mnemo update --yes --agent=all
mnemo update --check --json
```
`mnemo update` descarga el instalador oficial, lo fija a la última release
detectada y refresca los archivos de integración de mnemo para agentes después
de instalar. No actualiza Claude Code, Codex, Cursor ni otras aplicaciones de
agente. Reinicia las sesiones activas de agentes después de actualizar para que
recarguen el binario, hooks y skills refrescados. Las comprobaciones se omiten
en rutas MCP, hooks y salidas JSON para no romper integraciones machine-readable.
## Sincronización cloud
mnemo puede replicar la memoria local en una base de datos Turso/libSQL en la nube, para que varias máquinas o agentes compartan las mismas observaciones. Configura las credenciales una sola vez:
```bash
mnemo setup cloud
```
Las credenciales se guardan en `~/.config/mnemo/cloud.toml` (XDG). Las variables de entorno `MNEMO_CLOUD_URL`, `MNEMO_CLOUD_KEY` y `MNEMO_CLOUD_CLIENT_ID` tienen prioridad sobre el archivo. La sincronización es local-first e idempotente — el store SQLite local sigue siendo la copia operativa.
```bash
mnemo sync run # push y después pull
mnemo sync status # estado local sin contactar la nube
mnemo setup cloud --validate # prueba credenciales sin modificarlas
```
Consulta [docs/CLOUD_SYNC.md](docs/CLOUD_SYNC.md) para la referencia completa.
## Documentación
| Guía | Contenido |
|---|---|
| [Índice de documentación](docs/README.md) | Mapa completo de documentación y notas de investigación. |
| [Instalación](docs/INSTALLATION.md) | Instalador, plugin, activación de proyecto y verificación. |
| [Integración con agentes](docs/AGENT_INTEGRATION.md) | Hooks, rutas globales, marca `.mnemo` y Agent Skills. |
| [Referencia CLI](docs/CLI.md) | Comandos, ejemplos, herramientas MCP y modos de búsqueda. |
| [Troubleshooting](docs/TROUBLESHOOTING.md) | `doctor`, `setup status`, comprobaciones manuales e idempotencia. |
| [Storage](docs/STORAGE.md) | Ubicación SQLite, esquema y flujo sqlc. |
| [Roadmap](ROADMAP.md) | Trabajo planificado de producto y mantenimiento. |
## Principios de diseño
- **Local-first:** la memoria permanece en tu máquina en SQLite.
- **Neutral entre agentes:** una sola autoridad de memoria para todos los agentes soportados.
- **Opt-in por proyecto:** las integraciones globales no actúan sin `.mnemo`.
- **Diagnosticable:** cada superficie de setup puede comprobarse sin modificar nada.
- **Reparable:** duplicados de proyecto y conflictos de memoria son visibles y corregibles desde CLI.
## Licencia
[Apache 2.0](LICENSE): puedes usar, modificar y distribuir libremente, conservando el aviso de copyright e incluyendo [NOTICE](NOTICE) en las distribuciones.