wasurenagusa

Teach your AI coding agent to learn from its mistakes.

wasurenagusa (forget-me-not) — a Japanese flower whose name means "don't forget me."

The Problem

AI coding agents are powerful but amnesiac. Every session starts from scratch — your project conventions, past decisions, and hard-learned lessons vanish the moment a session ends.

Existing solutions either require manual effort or simply store raw memories that grow until they overwhelm the context window.

The Solution

wasurenagusa is an MCP server that doesn't just remember — it learns.

1. Detects mistakes automatically — Catches retry patterns, user frustration, and repeated failures

2. Distills lessons into principles — LLM compresses hundreds of raw entries into a handful of actionable rules

3. Converts negatives to positives — Generates positiveRule alongside each principle: "don't do X" becomes "do Y instead." Research shows LLMs follow affirmative instructions significantly better than prohibitions (Pink Elephant problem)

4. Compresses config into themes — LLM groups scattered settings into coherent summaries, preserving facts like ports and paths

5. Injects only what matters — Consolidated wisdom + active settings only. No template bloat, no duplicate entries.

6. Hybrid search (full-text + semantic) — SQLite-backed storage with local embedding inference (no external API needed). Full-text search with Japanese support + vector semantic search, merged and deduplicated. Works completely offline.

7. Smart tag retrieval — LLM-generated weighted tags + composite scoring (freshness, tag weight, access frequency) optimize retrieval priority without discarding any data.

8. Memory stash/restore — Temporarily stash memories out of the active context to save context window space, then restore them when needed. Ideal for long sessions with sub-agents.

Fully automated via Claude Code hooks — zero configuration after setup.

Real-world impact

From the author's daily use across 8 production projects (with cross-project memory sharing between them):

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. Session 1: Claude uses port 3000 — user corrects it to 8080

2. Stop Hook: wasurenagusa auto-analyzes the conversation and records the mistake

3. Session 2: Claude correctly uses port 8080 without being told

Why wasurenagusa

Most memory tools store what happened. wasurenagusa teaches your AI why things went wrong — and ensures it never repeats the same mistake.

It's not a memory bank. It's a learning system.

How It Works

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

Quick Start

💡 Recommended: Paste this README into Claude Code and ask it to set up wasurenagusa for you. It'll handle everything below automatically.

Prerequisites

• Node.js 18+

• Claude Code (CLI)

• No external API key required for core memory features (embedding runs locally)

• Optional: API key for LLM consolidation/analysis — Gemini / OpenAI / Anthropic

1. Install

npm install -g wasurenagusa-mcp

Or from source:

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

npm run build automatically runs chmod +x on CLI entry points. No manual permission setup needed.

2. Configure

Create ~/.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. Register MCP Server

claude mcp add wasurenagusa -- wasurenagusa-mcp

4. Set Up Hooks

⚠️ Required — Without this step, memory is never injected at session start. This is the most commonly missed setup step.

Add to ~/.claude/settings.json (or settings.local.json if you prefer to keep hooks separate):

{
  "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. Start Using

Launch Claude Code. That's it.

• First session: .wasurenagusa/ directory is created automatically

• After first conversation: Stop Hook analyzes and saves important context

• Second session onward: accumulated wisdom is auto-injected at start

Add .wasurenagusa/ to your .gitignore — it contains project-specific memory data.

Memory Categories

MCP Tools

CLI Commands

Output Mode

wasurenagusa supports two output modes for the SessionStart Hook, configurable per project via .wasurenagusa/config.json.

Configuration

Add outputMode to your project's .wasurenagusa/config.json:

{
  "outputMode": "agent"
}

If the file doesn't exist or outputMode is not set, the default is "injection" (full backward compatibility).

Recommended CLAUDE.md rules for agent mode

When using "agent" mode with Claude Code Agent Teams, add these rules to your project's CLAUDE.md:

- 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

Advanced Features

Vector Memory Tiers

wasurenagusa introduces a biologically-inspired memory system powered by local embeddings. Every memory is converted to a 384-dimensional vector, enabling meaning-based retrieval that goes far beyond keyword matching.

Three-tier architecture with cosine distance thresholds:

Automatic promotion: Every time a memory is retrieved via vector search, its access count increments. After 5 retrievals, the memory auto-promotes to intensity: 5 — ensuring frequently-needed knowledge gets maximum weight in consolidation. Long-dormant memories can be "woken up" by relevance and eventually earn top intensity through repeated access.

How it works:

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 external API required — embeddings are generated locally via @huggingface/transformers. Data is stored in SQLite with sqlite-vec for vector indexing. Works completely offline.

Automatic migration from v1 — existing Markdown-based memory files are automatically migrated to SQLite on first run. No manual steps required.

Smart Tag Retrieval

Smart Tag Retrieval improves search precision through three mechanisms — without ever deleting or forgetting data:

1. Weighted tag enrichment at save time — When you save a memory, the LLM generates descriptive tags and assigns each a weight (0.0-1.0). Concrete facts like port numbers or API endpoints receive high weights; generic categories receive low weights.

2. Background re-tagging on theme shift — When a new topic is detected, a background worker updates tags on related past entries so they stay discoverable under the new context.

3. Composite scoring — Search results are ranked by a blend of freshness, tag weight, and access frequency — surfacing the most relevant memories first.

All memories are preserved at full fidelity. Smart Tag Retrieval only optimizes retrieval priority, never discards data.

Cross-Project Memory

wasurenagusa automatically tracks your top 5 most recently used projects and searches across their memories for relevant context.

How it works:

1. Stop Hook records each project session in ~/.wasurenagusa/scheduler/active-projects.json

2. SessionStart searches other active projects' vector stores (short tier ≤ 0.2, high-relevance only)

3. memory_search with project: "active" searches across all active projects (keyword + vector)

Example: You're working on project-a and previously discussed authentication in project-b. When you start a session in project-a and the topic is related, wasurenagusa automatically surfaces the relevant auth memories from project-b.

No configuration needed — works automatically after two or more projects have been used.

LLM Consolidation

When memory entries accumulate, the LLM automatically compresses them into compact summaries:

• Dont entries → 5-9 behavioral principles scored by sourceCount × maxIntensity. Each principle includes both the original rule (❌→💡→✅ format) and a positiveRule (affirmative-only phrasing). The positiveRule is injected by default — research on the Pink Elephant problem shows LLMs struggle with negation in instructions.

• Config entries → 4-5 thematic summaries (e.g., 29 entries → 5 themes preserving all ports, paths, URLs)

Consolidation runs as a detached background process during session start, and optionally as a nightly scheduled job (2:00 AM). Results are cached as JSON and used from the next session onward. Staleness is detected by comparing file modification times and entry counts.

Raw entries are always preserved. The consolidated version is injected at session start; original entries remain searchable via memory_search.

Positive Rule Conversion

Every consolidated principle stores two forms:

Why? LLM attention mechanisms activate concepts mentioned in negations — "don't use innerHTML" still activates "innerHTML." Affirmative instructions ("use textContent") activate only the desired behavior. The raw user feedback (dont.md) is preserved unchanged; conversion happens only at the consolidation layer.

Memory Intensity (1-5)

Every dont entry carries an intensity score (1-5) representing the severity of the lesson:

Auto-detection: The LLM analyzes user messages for emotional signals (exclamation marks, strong language, repeated corrections) and assigns intensity automatically. Conversation metadata (turns since last positive feedback, message length ratio) provides additional boost signals.

Manual override: Pass intensity: N to memory_save to set or adjust the score.

Scoring formula: During consolidation, each principle gets score = sourceCount × maxIntensity. Principles are sorted by score descending — frequently repeated, high-anger lessons appear first with stronger wording.

Auto-Archiving

Each memory category has an entry limit (default: 100). When exceeded, oldest entries are automatically moved to archive files (*-archive.md). Logs have separate 30-day rotation. Your data is never deleted — just moved out of the active search path.

Sentiment Detection

Detects user frustration through text patterns, message length changes, and absence of positive signals. Records what went wrong, why, and what to do instead.

Autonomous Tasks

Submit tasks via task_submit and wasurenagusa runs them using Claude CLI as a subprocess. The LLM evaluates completion conditions and retries if needed. Useful for spec updates, refactoring, and test generation.

Owner Profile

On first run, an owner-profile.md template is generated. Fill it in to teach the AI your decision-making preferences for autonomous task execution.

Only sections you've actually customized are injected — default selections and empty fields are automatically stripped, keeping injection minimal.

Nightly Consolidation Scheduler

Instead of only consolidating at session start, you can schedule nightly consolidation across all active projects — like "sleeping on it overnight."

# Install (macOS: launchd, Linux: crontab)
wasurenagusa-scheduler install

# Check status
wasurenagusa-scheduler status

# Remove
wasurenagusa-scheduler uninstall

Runs daily at 2:00 AM, consolidating dont and config entries for all recently active projects. This ensures your AI starts every morning with freshly organized principles, even if you never close your sessions.

Current Limitations

• Claude Code only — Hook-based auto-injection requires Claude Code. The MCP server itself works with any MCP-compatible client, but without auto-injection.

Design Philosophy

• Autonomous by default, manual by choice — Hooks automate everything. Manual tools exist but are optional.

• Context-efficient — LLM consolidation + smart filtering achieves 71% injection reduction. Two-stage retrieval (index then detail) further reduces on-demand consumption.

• SQLite storage — All memory stored in SQLite with sqlite-vec for vector indexing. Auto-migrated from v1 Markdown format.

• Externalized prompts — LLM prompts live in prompts/ as plain text. Iterate without rebuilding.

Development

npm run build        # Compile TypeScript
npm test             # Run tests
npm run test:watch   # Watch mode

License

MIT

Japanese README (日本語)