wasurenagusa

Enseña a tu agente de codificación de IA a aprender de sus errores.

wasurenagusa (nomeolvides) — una flor japonesa cuyo nombre significa "no me olvides".

El problema

Los agentes de codificación de IA son potentes pero amnésicos. Cada sesión comienza desde cero: tus convenciones de proyecto, decisiones pasadas y lecciones aprendidas con esfuerzo desaparecen en el momento en que termina una sesión.

Las soluciones existentes requieren esfuerzo manual o simplemente almacenan memorias crudas que crecen hasta saturar la ventana de contexto.

Related MCP server: memory-bank-mcp

La solución

wasurenagusa es un servidor MCP que no solo recuerda, sino que aprende.

1. Detecta errores automáticamente — Detecta patrones de reintento, frustración del usuario y fallos repetidos.

2. Destila lecciones en principios — El LLM comprime cientos de entradas crudas en un puñado de reglas accionables.

3. Convierte negativos en positivos — Genera una positiveRule junto a cada principio: "no hagas X" se convierte en "haz Y en su lugar". Las investigaciones muestran que los LLM siguen instrucciones afirmativas significativamente mejor que las prohibiciones (problema del Elefante Rosa).

4. Comprime la configuración en temas — El LLM agrupa configuraciones dispersas en resúmenes coherentes, preservando hechos como puertos y rutas.

5. Inyecta solo lo que importa — Sabiduría consolidada + configuraciones activas solamente. Sin exceso de plantillas, sin entradas duplicadas.

6. Búsqueda híbrida (texto completo + semántica) — Almacenamiento respaldado por SQLite con inferencia de incrustaciones (embeddings) local (no se necesita API externa). Búsqueda de texto completo con soporte para japonés + búsqueda semántica vectorial, fusionada y desduplicada. Funciona completamente offline.

7. Recuperación inteligente mediante etiquetas — Etiquetas ponderadas generadas por LLM + puntuación compuesta (frescura, peso de la etiqueta, frecuencia de acceso) optimizan la prioridad de recuperación sin descartar ningún dato.

8. Almacenamiento/restauración de memoria — Guarda temporalmente memorias fuera del contexto activo para ahorrar espacio en la ventana de contexto, y restáuralas cuando sea necesario. Ideal para sesiones largas con subagentes.

Totalmente automatizado mediante hooks de Claude Code: configuración cero tras la instalación.

Impacto en el mundo real

Basado en el uso diario del autor en 8 proyectos de producción (con intercambio de memoria entre proyectos):

1,581 "dont" entries   →  5-9 principles per project    (LLM consolidation)
  each with positiveRule  →  affirmative-only injection  (Pink Elephant fix)
29 config entries      →  4-5 thematic summaries        (LLM consolidation)
21,800 chars raw data  →  6,200 chars injected           (71% reduction)

Demo

1. Sesión 1: Claude usa el puerto 3000 — el usuario lo corrige a 8080

2. Stop Hook: wasurenagusa analiza automáticamente la conversación y registra el error

3. Sesión 2: Claude usa correctamente el puerto 8080 sin que se lo digan

Por qué wasurenagusa

La mayoría de las herramientas de memoria almacenan lo que sucedió. wasurenagusa enseña a tu IA por qué las cosas salieron mal — y asegura que nunca repita el mismo error.

No es un banco de memoria. Es un sistema de aprendizaje.

Cómo funciona

Session Start (Hook) — injection mode
  → Checks if consolidation is stale
  → Spawns background LLM worker if needed (non-blocking)
  → Spawns background embedding backfill worker (non-blocking)
  → Injects consolidated config + principles (layer 1) + recent 30-day entries (layer 2) + owner profile
  → Vector search injects semantically related short-term memories (layer 3)
  → Cross-project vector search injects related memories from other active projects (layer 4)
  → Only customized settings injected (defaults stripped)

Session Start (Hook) — agent mode
  → Injects dont summary + config index + owner profile (minimal footprint)
  → No vector search at startup (deferred to on-demand recall)

User Prompt (Hook) — agent mode
  → Injects 1-line reminder: "search memory if relevant"
  → Main agent spawns memory-recall sub-agent as needed
  → Sub-agent runs memory_search → returns summary only (no raw data in main context)
  → Survives compaction (re-injected on every user message)

During Session
  → memory_save auto-generates embedding via local inference (no API call)
  → memory_save enriches tags with LLM-assigned weights (0.0-1.0) (when API key available)
  → Theme shift triggers background re-tagging of related past entries
  → memory_search merges keyword + vector semantic + tag-weighted results
  → Vector hits increment access counts → auto-promote to intensity 5 at threshold

Session End (Hook)
  → LLM analyzes the conversation
  → Detects mistakes, frustration, retry patterns
  → Auto-saves lessons learned (with embedding)
  → Deduplicates against existing entries before saving
  → Updates active projects tracker (top 5 recent projects)

Background (async workers)
  → Consolidates "dont" entries → behavioral principles
  → Consolidates "config" entries → thematic summaries
  → Backfills embeddings for entries created before vector layer (20/run)
  → Results used in next session start

Inicio rápido

💡 Recomendado: Pega este README en Claude Code y pídele que configure wasurenagusa por ti. Se encargará de todo lo siguiente automáticamente.

Requisitos previos

• Node.js 18+

• Claude Code (CLI)

• No se requiere API key externa para las funciones principales de memoria (los embeddings se ejecutan localmente)

• Opcional: API key para consolidación/análisis mediante LLM — Gemini / OpenAI / Anthropic

1. Instalación

npm install -g wasurenagusa-mcp

O desde el código fuente:

git clone https://github.com/tsutushi0628/wasurenagusa-mcp.git
cd wasurenagusa-mcp
npm install && npm run build
npm link

npm run build ejecuta automáticamente chmod +x en los puntos de entrada de la CLI. No se requiere configuración manual de permisos.

2. Configuración

Crea ~/.wasurenagusa/.env:

# Set at least one API key
GEMINI_API_KEY=your-key-here
# OPENAI_API_KEY=your-key-here
# ANTHROPIC_API_KEY=your-key-here

3. Registrar servidor MCP

claude mcp add wasurenagusa -- wasurenagusa-mcp

4. Configurar hooks

⚠️ Requerido — Sin este paso, la memoria nunca se inyecta al inicio de la sesión. Este es el paso de configuración que más se suele pasar por alto.

Añade a ~/.claude/settings.json (o settings.local.json si prefieres mantener los hooks separados):

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "wasurenagusa-context",
            "timeout": 5
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "wasurenagusa-context",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "wasurenagusa-analyze",
            "timeout": 30
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "wasurenagusa-context",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

5. Empezar a usar

Inicia Claude Code. Eso es todo.

• Primera sesión: el directorio .wasurenagusa/ se crea automáticamente

• Después de la primera conversación: el Stop Hook analiza y guarda el contexto importante

• A partir de la segunda sesión: la sabiduría acumulada se inyecta automáticamente al inicio

Añade .wasurenagusa/ a tu .gitignore — contiene datos de memoria específicos del proyecto.

Categorías de memoria

Herramientas MCP

Comandos CLI

Modo de salida

wasurenagusa admite dos modos de salida para el Hook SessionStart, configurables por proyecto a través de .wasurenagusa/config.json.

Configuración

Añade outputMode al archivo .wasurenagusa/config.json de tu proyecto:

{
  "outputMode": "agent"
}

Si el archivo no existe o outputMode no está configurado, el valor predeterminado es "injection" (compatibilidad total hacia atrás).

Reglas recomendadas de CLAUDE.md para el modo agente

Cuando uses el modo "agent" con Equipos de Agentes de Claude Code, añade estas reglas al CLAUDE.md de tu proyecto:

- Read/write memories via sub-agents (memory_search / memory_get_detail / memory_save)
- Do not bring raw memory data into the main context
- When system-reminder suggests memory recall, spawn a sub-agent to run memory_search and return summary only

Características avanzadas

Niveles de memoria vectorial

wasurenagusa introduce un sistema de memoria inspirado biológicamente impulsado por embeddings locales. Cada memoria se convierte en un vector de 384 dimensiones, permitiendo una recuperación basada en el significado que va mucho más allá de la coincidencia de palabras clave.

Arquitectura de tres niveles con umbrales de distancia coseno:

Promoción automática: Cada vez que se recupera una memoria mediante búsqueda vectorial, su conteo de acceso aumenta. Después de 5 recuperaciones, la memoria se promociona automáticamente a intensity: 5, asegurando que el conocimiento necesario frecuentemente obtenga el máximo peso en la consolidación. Las memorias inactivas durante mucho tiempo pueden ser "despertadas" por relevancia y eventualmente ganar la máxima intensidad a través de accesos repetidos.

Cómo funciona:

memory_save
  → Text → local inference (Hugging Face Transformers) → embedding → SQLite (sqlite-vec)

memory_search "authentication setup"
  → Full-text search (FTS5, Japanese support) ─┐
  → Embed query → vector similarity search     ─┤→ merge, deduplicate → results
                                                └→ increment access count
                                                   → auto-promote if threshold met

SessionStart Hook
  → Embed project name → short-tier search → inject related memories

No se requiere API externa — los embeddings se generan localmente mediante @huggingface/transformers. Los datos se almacenan en SQLite con sqlite-vec para indexación vectorial. Funciona completamente offline.

Migración automática desde v1 — los archivos de memoria basados en Markdown existentes se migran automáticamente a SQLite en la primera ejecución. No se requieren pasos manuales.

Recuperación inteligente mediante etiquetas

La recuperación inteligente mediante etiquetas mejora la precisión de la búsqueda a través de tres mecanismos, sin eliminar ni olvidar datos nunca:

1. Enriquecimiento de etiquetas ponderadas al guardar — Cuando guardas una memoria, el LLM genera etiquetas descriptivas y asigna a cada una un peso (0.0-1.0). Hechos concretos como números de puerto o endpoints de API reciben pesos altos; las categorías genéricas reciben pesos bajos.

2. Re-etiquetado en segundo plano ante cambios de tema — Cuando se detecta un nuevo tema, un proceso en segundo plano actualiza las etiquetas en entradas pasadas relacionadas para que sigan siendo descubribles bajo el nuevo contexto.

3. Puntuación compuesta — Los resultados de búsqueda se clasifican mediante una mezcla de frescura, peso de la etiqueta y frecuencia de acceso, mostrando primero las memorias más relevantes.

Todas las memorias se conservan con fidelidad total. La recuperación inteligente mediante etiquetas solo optimiza la prioridad de recuperación, nunca descarta datos.

Memoria entre proyectos

wasurenagusa rastrea automáticamente tus 5 proyectos usados más recientemente y busca en sus memorias contexto relevante.

Cómo funciona:

1. Stop Hook registra cada sesión de proyecto en ~/.wasurenagusa/scheduler/active-projects.json

2. SessionStart busca en los almacenes vectoriales de otros proyectos activos (nivel corto ≤ 0.2, solo alta relevancia)

3. memory_search con project: "active" busca en todos los proyectos activos (palabra clave + vector)

**Ejemplo