wasurenagusa

Научите своего ИИ-агента учиться на ошибках.

wasurenagusa (незабудка) — японский цветок, название которого означает «не забывай меня».

Проблема

ИИ-агенты для написания кода мощны, но страдают амнезией. Каждая сессия начинается с чистого листа — ваши проектные соглашения, прошлые решения и усвоенные уроки исчезают, как только сессия заканчивается.

Существующие решения либо требуют ручного труда, либо просто хранят «сырые» воспоминания, которые разрастаются до тех пор, пока не переполняют контекстное окно.

Related MCP server: memory-bank-mcp

Решение

wasurenagusa — это MCP-сервер, который не просто запоминает — он учится.

1. Автоматически обнаруживает ошибки — отслеживает паттерны повторных попыток, разочарование пользователя и повторяющиеся сбои.

2. Дистиллирует уроки в принципы — LLM сжимает сотни «сырых» записей в несколько применимых правил.

3. Превращает негатив в позитив — генерирует positiveRule вместе с каждым принципом: «не делай X» превращается в «вместо этого делай Y». Исследования показывают, что LLM значительно лучше следуют утвердительным инструкциям, чем запретам (проблема «Розового слона»).

4. Сжимает конфигурацию в темы — LLM группирует разрозненные настройки в связные резюме, сохраняя такие факты, как порты и пути.

5. Внедряет только то, что важно — только консолидированная мудрость + активные настройки. Никакого мусора из шаблонов, никаких дубликатов.

6. Гибридный поиск (полнотекстовый + семантический) — хранилище на базе SQLite с локальным выводом эмбеддингов (внешний API не нужен). Полнотекстовый поиск с поддержкой японского языка + векторный семантический поиск, объединенные и дедуплицированные. Работает полностью офлайн.

7. Умное извлечение по тегам — взвешенные теги, сгенерированные LLM + композитный скоринг (свежесть, вес тега, частота доступа) оптимизируют приоритет извлечения без удаления данных.

8. Стейшинг/восстановление памяти — временно выгружайте воспоминания из активного контекста, чтобы сэкономить место, и восстанавливайте их при необходимости. Идеально для длинных сессий с под-агентами.

Полная автоматизация через хуки Claude Code — никакой настройки после установки.

Реальное влияние

Из ежедневного использования автором в 8 производственных проектах (с обменом памятью между проектами):

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)

Демонстрация

1. Сессия 1: Claude использует порт 3000 — пользователь исправляет его на 8080.

2. Хук остановки: wasurenagusa автоматически анализирует диалог и записывает ошибку.

3. Сессия 2: Claude правильно использует порт 8080 без напоминаний.

Почему wasurenagusa

Большинство инструментов памяти хранят то, что произошло. wasurenagusa учит ваш ИИ почему что-то пошло не так — и гарантирует, что он никогда не повторит ту же ошибку.

Это не банк памяти. Это система обучения.

Как это работает

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

Быстрый старт

💡 Рекомендуется: Вставьте этот README в Claude Code и попросите его настроить wasurenagusa за вас. Он автоматически выполнит все действия ниже.

Предварительные требования

• Node.js 18+

• Claude Code (CLI)

• Внешний API-ключ не требуется для основных функций памяти (эмбеддинги работают локально)

• Опционально: API-ключ для консолидации/анализа LLM — Gemini / OpenAI / Anthropic

1. Установка

npm install -g wasurenagusa-mcp

Или из исходного кода:

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

npm run build автоматически выполняет chmod +x для CLI-точек входа. Ручная настройка прав не требуется.

2. Конфигурация

Создайте ~/.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. Регистрация MCP-сервера

claude mcp add wasurenagusa -- wasurenagusa-mcp

4. Настройка хуков

⚠️ Обязательно — без этого шага память не будет внедряться при запуске сессии. Это самый часто пропускаемый шаг настройки.

Добавьте в ~/.claude/settings.json (или settings.local.json, если предпочитаете разделять хуки):

{
  "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. Начало использования

Запустите Claude Code. Это всё.

• Первая сессия: директория .wasurenagusa/ создается автоматически.

• После первого диалога: хук остановки анализирует и сохраняет важный контекст.

• Со второй сессии: накопленная мудрость автоматически внедряется при старте.

Добавьте .wasurenagusa/ в ваш .gitignore — там хранятся специфичные для проекта данные памяти.

Категории памяти

Инструменты MCP

Команды CLI

Режим вывода

wasurenagusa поддерживает два режима вывода для хука SessionStart, настраиваемых для каждого проекта через .wasurenagusa/config.json.

Конфигурация

Добавьте outputMode в .wasurenagusa/config.json вашего проекта:

{
  "outputMode": "agent"
}

Если файл отсутствует или outputMode не задан, по умолчанию используется "injection" (полная обратная совместимость).

Рекомендуемые правила CLAUDE.md для режима агента

При использовании режима "agent" с командами агентов Claude Code, добавьте эти правила в 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

Продвинутые функции

Уровни векторной памяти

wasurenagusa представляет систему памяти, вдохновленную биологическими принципами, на базе локальных эмбеддингов. Каждое воспоминание преобразуется в 384-мерный вектор, что позволяет выполнять поиск по смыслу, выходящий далеко за рамки простого сопоставления ключевых слов.

Трехуровневая архитектура с порогами косинусного расстояния:

Автоматическое продвижение: Каждый раз, когда воспоминание извлекается через векторный поиск, счетчик доступа увеличивается. После 5 извлечений воспоминание автоматически переходит в intensity: 5, гарантируя, что часто нужные знания получают максимальный вес при консолидации.

Как это работает:

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

Внешний API не требуется — эмбеддинги генерируются локально через @huggingface/transformers. Данные хранятся в SQLite с sqlite-vec для векторной индексации. Работает полностью офлайн.

Автоматическая миграция из v1 — существующие Markdown-файлы памяти автоматически переносятся в SQLite при первом запуске.

Умное извлечение по тегам

Умное извлечение по тегам повышает точность поиска тремя механизмами — без удаления или забывания данных:

1. Взвешенное обогащение тегами при сохранении — при сохранении памяти LLM генерирует описательные теги и присваивает каждому вес (0.0-1.0). Конкретные факты (порты, API) получают высокий вес; общие категории — низкий.

2. Фоновая перемаркировка при смене темы — при обнаружении новой темы фоновый процесс обновляет теги связанных прошлых записей.

3. Композитный скоринг — результаты поиска ранжируются по смеси свежести, веса тега и частоты доступа.

Память между проектами

wasurenagusa автоматически отслеживает 5 последних использованных проектов и ищет релевантный контекст в их памяти.

**Как это работает