Wasurenagusa MCP

勿忘草

教你的AI编码代理从错误中学习。

](https://www.npmjs.com/package/wasurenagusa-mcp)  ](https://nodejs.org) 

*勿忘草* （勿忘我）-一种日本花，其名字的意思是“不要忘记我”

______________________________________________________________________

问题

人工智能编码代理功能强大，但会失忆。每一次会议都是从头开始的——你的项目惯例、过去的决定和来之不易的经验教训在会议结束时就消失了。

现有的解决方案要么需要手动操作，要么只是存储原始内存，直到它们淹没上下文窗口。

解决方案

wasurenagusa是一个MCP服务器，它不仅 *记住* 它 学习.

1. 自动检测错误 --捕获重试模式、用户挫折和重复失败
2. 将经验教训提炼为原则 --LLM将数百个原始条目压缩为少数可操作的规则
3. 将负数转换为正数 --生成 positiveRule 在每个原则旁边：“不做X”变成了“做Y”。研究表明，LLM遵循肯定的指示明显优于禁令(粉红象问题)
4. 将配置压缩为主题 --LLM将分散的设置组合成连贯的摘要，保留端口和路径等事实
5. 只注射重要的东西 --整合智慧+仅限活动设置。没有模板膨胀，没有重复条目。
6. 混合搜索（全文+语义） -带有本地嵌入推理的SQLite-based存储（不需要外部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)

______________________________________________________________________

演示

What happens behind the scenes

1. 第1节：Claude使用端口3000——用户将其更正为8080
2. 止动钩：wasurenagusa自动分析对话并记录错误
3. 第2节：Claude在没有被告知的情况下正确使用了端口8080

______________________________________________________________________

为什么是留尼古萨

大多数记忆工具都会存储发生的事情。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+
• 克劳德代码（CLI）
• 不需要外部API密钥 用于核心内存功能（嵌入在本地运行）
• 可选：用于LLM合并/分析的API密钥- 双子座 / 开放人工智能 / 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.开始使用

启动克劳德代码。就这样

• 第一次会议： .wasurenagusa/ 目录是自动创建的
• 第一次对话后：Stop Hook分析并保存重要上下文
• 第二节开始：积累的智慧在开始时自动注入

添加 .wasurenagusa/ 到你的 .gitignore --它包含特定于项目的内存数据。

______________________________________________________________________

内存类别

______________________________________________________________________

MCP工具

______________________________________________________________________

CLI命令

______________________________________________________________________

输出模式

wasurenagusa支持SessionStart Hook的两种输出模式，可通过以下方式为每个项目配置 .wasurenagusa/config.json.

配置

添加 outputMode 到你的项目 .wasurenagusa/config.json:

{
  "outputMode": "agent"
}

如果文件不存在或 outputMode 未设置，默认值为 "injection" （完全向后兼容）。

代理模式的推荐CLAUDE.md规则

当使用 "agent" 在Claude Code Agent Teams模式下，将这些规则添加到您的项目中 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个项目，并在他们的记忆中搜索相关上下文。

它是如何工作的：

1. 止动钩 在中记录每个项目会话 ~/.wasurenagusa/scheduler/active-projects.json
2. 会话开始 搜索其他活动项目的向量存储（短层≤0.2，仅高相关性）
3. memory_search 随着 project: "active" 在所有活动项目中搜索（关键字+向量）

例子： 你正在努力 project-a 前面讨论过的身份验证 project-b。当您在中开始会话时 project-a 与主题相关，wasurenagusa会自动从以下位置显示相关的身份验证记忆 project-b.

无需配置——在使用了两个或多个项目后会自动工作。

LLM整合

当内存条目累积时，LLM会自动将其压缩为紧凑的摘要：

• 请勿输入 → 5-9 行为原则评分如下 sourceCount × maxIntensity每个原则都包括原始原则 rule (❌→💡→✅ 格式）和a positiveRule （只有肯定的措辞）。这 positiveRule 默认情况下被注入——研究 粉红象问题 显示LLM在指令中与否定作斗争。
• 配置条目 → 4-5 主题摘要（例如，29个条目→ 5 主题保留所有端口、路径、URL）

在会话启动期间，整合作为独立的后台进程运行，也可以作为 夜间计划作业 （凌晨2点）。结果以JSON格式缓存，并从下一个会话开始使用。通过比较文件修改时间和条目计数来检测静态。

原始条目始终被保留。在会话开始时注入合并版本；原始条目仍可通过以下方式搜索 memory_search.

正向规则转换

每个合并原则都存储两种形式：

为什么？ LLM注意力机制激活否定中提到的概念——“不使用innerHTML”仍然激活“innerHTML。”肯定指令（“使用textContent”）只激活所需的行为。原始用户反馈(dont.md)保持不变；转换仅发生在固结层。

记忆强度（1-5）

每个not条目都带有 强度 代表课程严重程度的分数（1-5）：

自动检测： LLM分析用户消息中的情感信号（感叹号、强烈的语言、重复的更正），并自动分配强度。会话元数据（自上次正反馈以来的轮次、消息长度比）提供了额外的增强信号。

手动超控： 通过 intensity: N 到 memory_save 设置或调整分数。

评分公式： 在合并过程中，每个原则都得到 score = sourceCount × maxIntensity原则按分数降序排列——频繁重复的、高愤怒的课程以更强烈的措辞出现在第一位。

自动存档

每个内存类别都有一个条目限制（默认值：100）。超过时，最旧的条目会自动移动到存档文件中(*-archive.md).日志有单独的30天轮换。您的数据永远不会被删除，只会移出活动搜索路径。

情绪检测

通过文本模式、消息长度变化和没有积极信号来检测用户的沮丧情绪。记录出了什么问题，为什么，以及该怎么做。

自主任务

通过提交任务 task_submit wasurenagusa使用Claude CLI作为子进程运行它们。LLM评估完成条件，并在需要时重试。可用于规范更新、重构和测试生成。

业主简介

第一次运行时，A owner-profile.md 生成模板。填写该表格，让人工智能了解您对自主任务执行的决策偏好。

只有您实际定制的部分才会被注入——默认选择和空字段会自动剥离，从而保持最小的注入量。

夜间整合调度程序

您可以安排所有活动项目的夜间整合，而不是只在会话开始时进行整合，比如“过夜”

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

# Check status
wasurenagusa-scheduler status

# Remove
wasurenagusa-scheduler uninstall

每天在 凌晨2:00，合并最近所有活动项目的don和config条目。这确保了你的人工智能每天早上都以新组织的原则开始，即使你从未关闭过你的会话。

______________________________________________________________________

当前限制

• 仅限克劳德代码 --基于钩子的自动注射需要Claude Code。MCP服务器本身与任何兼容MCP的客户端一起工作，但没有自动注入。

______________________________________________________________________

设计理念

• 默认情况下自主，选择手动 --Hooks使一切自动化。手动工具存在，但是可选的。
• 上下文高效 --LLM合并+智能过滤实现71%的注入减少。两阶段检索（索引然后详细信息）进一步减少了按需消耗。
• SQLite存储 --所有存储在SQLite中的内存都使用SQLite-vec进行向量索引。从v1 Markdown格式自动迁移。
• 外部化提示 --LLM提示直播 prompts/ 作为纯文本。迭代而不重建。

______________________________________________________________________

发展

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

______________________________________________________________________

许可证

麻省理工学院

______________________________________________________________________

Japanese README（日本语）