skillmem

skillmem

Habilidades auto-mejorables para Claude Code: tu agente aprende, recuerda, refuerza y olvida.

skillmem le da a Claude Code una capa local y persistente de habilidades y memoria. Después de cada tarea no trivial, el agente puede registrar cómo se hizo como una habilidad; antes de la siguiente tarea, recuerda las relevantes; las habilidades que siguen demostrando ser útiles se fortalecen, y las que nadie usa se desvanecen — igual que funciona la memoria humana.

• $0 por escritura y por lectura — sin llamadas a LLM, sin nube, sin claves de API. SQLite simple en tu disco.
• Búsqueda híbrida bilingüe, totalmente local — FTS5 BM25 + derivación Snowball (EN/RU) + un modelo de embeddings ONNX multilingüe. Una consulta en ruso encuentra una habilidad en inglés y viceversa, todo en CPU, sin conexión.
• Modelo de fuerza de Ebbinghaus — reinforce aumenta la fuerza de una habilidad, la decadencia programada desvanece las no utilizadas, y los barridos del ciclo de vida mueven las habilidades muertas a un archivo respaldado (nunca se eliminan).
• Historial a prueba de manipulaciones — cada edición se agrega a una cadena de hash SHA256; skillmem verify detecta cualquier manipulación posterior.
• Integración profunda con Claude Code — 6 hooks + 8 herramientas MCP instaladas con un solo comando.
• Multiplataforma — macOS (launchd), Windows (schtasks), Linux (temporizadores de usuario systemd, cron como alternativa).
• Sin bloqueo de proveedor — export-all vuelca todo a markdown plano con frontmatter YAML; reimportar el volcado produce los mismos registros.

Por qué

Los agentes repiten sus errores porque cada sesión comienza desde cero. Las herramientas de "memoria" existentes almacenan hechos; skillmem almacena procedimientos — desencadenante, pasos, resultado, lecciones — y los clasifica según la frecuencia con la que realmente ayudaron. La ruta de escritura no cuesta nada, por lo que el agente puede permitirse aprender de cada tarea.

Inicio rápido

macOS / Linux:

bash install.sh                 # installs python + uv if needed, venv, symlinks

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File install.ps1

O desde un checkout:

uv venv && uv pip install -e '.[semantic]'
source .venv/bin/activate       # or prefix the commands below with `uv run`
skillmem init --claude-code     # wires MCP server + hooks into Claude Code
skillmem doctor                 # health check: DB, schema, semantic status

init --claude-code registra el servidor MCP en ~/.claude.json y los hooks en ~/.claude/settings.json (idempotente, con copias de seguridad). Usa --hooks minimal solo para el hook Stop→migrate, o --hooks none solo para MCP.

Plugin de Claude Code y Registro MCP (próximamente)

El repositorio ya incluye un plugin de Claude Code (.claude-plugin/ + hooks/hooks.json — servidor MCP y todos los hooks en una sola instalación) y un manifiesto del Registro MCP (server.json). Ambos se activarán una vez que el paquete skillmem se publique en PyPI; hasta entonces, usa los instaladores anteriores. Una vez activos:

/plugin marketplace add liza-studio/skillmem
/plugin install skillmem@liza-studio

El plugin requiere el paquete Python skillmem en PATH y reemplaza el cableado de skillmem init --claude-code — usa uno u otro, no ambos (ver docs/PUBLISHING.md).

Claude Desktop (aplicación de chat)

El servidor MCP también funciona en la aplicación de chat Claude Desktop — agrégalo a claude_desktop_config.json (Configuración → Desarrollador → Editar configuración):

{
  "mcpServers": {
    "skillmem": { "command": "skillmem-mcp" }
  }
}

Obtienes las 8 herramientas mem_* bajo demanda (búsqueda, aprender, recordar, reforzar…). Los hooks automáticos (auto-recuperación en cada mensaje, resumen de sesión) son un mecanismo de Claude Code y no se ejecutan en la aplicación de chat.

Cómo funciona

 learn ──▶ recall ──▶ reinforce ──▶ decay
   │          │            │           │
   │          │            │           └─ daily job: unused skills lose strength;
   │          │            │              fully faded ones are archived (backed up)
   │          │            └─ strength +0.15 when a skill proves useful
   │          └─ hybrid BM25 + vector search, strength-weighted ranking
   └─ after a hard task: trigger / steps / outcome / lessons

1. learn — después de una tarea que requirió depuración real, el agente llama a mem_learn con un slug, desencadenante, pasos, resultado y lecciones.
2. recall — antes de la siguiente tarea, mem_recall (o los hooks automáticos) muestra las habilidades más relevantes, fusionando señales léxicas y semánticas mediante Fusión de Rango Recíproco.
3. reinforce — cuando una habilidad recordada ayudó, mem_reinforce aumenta su fuerza, de modo que las habilidades probadas tengan mayor prioridad la próxima vez.
4. decay — una ejecución programada de skillmem decay aplica el olvido estilo Ebbinghaus; las habilidades sin uso durante meses pasan a stale, y luego a un estado archived (excluidas de la recuperación, restaurables con un comando, con instantánea a JSONL primero).

Herramientas MCP

Herramienta	Qué hace
mem_search	Búsqueda híbrida de texto completo (FTS5 BM25 + recuperación vectorial opcional) sobre todas las memorias
mem_get	Obtiene una memoria por slug, con historial y wikilinks
mem_list	Lista memorias por tipo/proyecto, más recientes primero
mem_write	Inserta una nueva memoria; rechaza sobrescrituras silenciosas y casi duplicados
mem_update	Actualiza una memoria existente; la versión anterior se conserva en el historial encadenado por hash
mem_learn	Registra una habilidad posterior a la acción (desencadenante / pasos / resultado / lecciones)
mem_recall	Encuentra habilidades relevantes para una tarea, ponderadas por fuerza; auto-refuerza
mem_reinforce	Aumenta explícitamente la fuerza de una habilidad después de que demostró ser útil

Hooks

Evento	Hook	Qué inyecta
SessionStart	mcp-guard	Advierte cuando faltan servidores MCP configurados frente a una línea base
SessionStart	inject	Resumen compacto solo con títulos de tus memorias user/feedback
SessionStart	session-history	Resúmenes de las últimas 3 sesiones en este proyecto
UserPromptSubmit	verify-gate	Recordatorio "busca antes de afirmar" en mensajes sensibles al tiempo (desencadenantes bilingües EN/RU)
UserPromptSubmit	auto-recall	Comentarios y habilidades relevantes coincidentes con el mensaje
PreToolUse	tool-recall	Habilidades/advertencias coincidentes con el comando Bash o la ruta del archivo editado
Stop	session-recap	Destila la sesión en una nota markdown mediante claude -p (el idioma del resumen refleja la sesión)
Stop	migrate	Indexa nuevas notas de sesión en la base de datos

Todos los hooks son de mejor esfuerzo: una base de datos dañada o un modelo faltante nunca bloquean Claude Code.

Aspectos destacados de la CLI

skillmem learn skill-x -t "..." --trigger "..." --steps "..." --outcome success
skillmem recall "deploy the bot to prod"
skillmem skills                  # list skills with strength bars
skillmem decay --days 14         # manual decay + lifecycle sweep
skillmem search "hash chain" --kind feedback
skillmem verify --strict         # check the tamper-evidence chain
skillmem export-all ./vault      # markdown round-trip, no lock-in
skillmem import-vault ~/Obsidian/Notes
skillmem schedule install        # decay daily 04:15, export weekly Sun 04:30

Desinstalación

skillmem uninstall               # removes MCP entry, hooks, scheduled jobs; keeps the DB
skillmem uninstall --purge-db    # ...and deletes the database

Los cambios de configuración se realizan atómicamente con copias de seguridad con marca de tiempo, y el JSON corrupto nunca se sobrescribe.

Puntos de referencia

Calidad de recuperación en LongMemEval (Wu et al., ICLR 2025), conjunto oracle completo, recuperación híbrida (FTS5 BM25 + derivación Snowball + embeddings paraphrase-multilingual-MiniLM-L12-v2, fusión RRF), k=5, solo CPU:

Tipo de pregunta	n	hit@5	MRR
General	479	0.871	0.622
single-session-assistant	56	0.982	0.746
knowledge-update	72	0.944	0.676
single-session-user	64	0.938	0.719
multi-session	125	0.848	0.568
single-session-preference	30	0.833	0.465
temporal-reasoning	132	0.780	0.579

Mediana de 0.76 s por consulta en una CPU de portátil, sin llamadas a LLM, sin red. El pipeline es determinista: las ejecuciones repetidas producen números idénticos. Reproduce con python bench/longmemeval.py --sample 0 -k 5 (ver bench/README.md para el archivo oracle y las reglas de reporte — no publicamos porcentajes simples sin indicar el modo de recuperación y el modelo de embeddings, y animamos a otras herramientas a hacer lo mismo).

Licencia

Apache-2.0 — ver LICENSE.

---

Construido por Liza Studio.