wasurenagusa-mcp 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tsutushi0628
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,355 @@
+# wasurenagusa-mcp
+
+**wasurenagusa**（忘れな草） — 「私を忘れないで」という花言葉を持つ花。
+
+**Claude Code に記憶を与える MCP サーバー。同じミスは、もう繰り返さない。**
+
+> 「ポートは3000って言ったよね？」「さっき決めたでしょ？」
+>
+> Claude Code との会話で、同じことを何度も説明した経験はありませんか。
+> wasurenagusa は、AI アシスタントに「記憶」を与える MCP サーバーです。
+> 設定情報、やってはいけないこと、過去の決定事項を自動で記録・自動で注入。
+> あなたは普段通りに会話するだけ。裏側で LLM が会話を分析し、重要な情報を蓄積していきます。
+
+---
+
+## wasurenagusa が解決する3つの「忘れる」
+
+### 1. プロジェクトの知識
+
+Claude Code はセッションが変わるたびに、すべてを忘れる。
+API の URL、ポート番号、「ログを読んでから質問して」というルール、先週決めたアーキテクチャ。
+
+wasurenagusa は **Hooks 連携で完全自動化** されている。
+セッション開始時に設定とルールが自動注入され、会話終了時に重要な情報が自動保存される。
+ユーザーが手動で何かする必要は、一切ない。
+
+### 2. ドキュメントの最新化
+
+コードは毎日変わるのに、Spec ドキュメントは書いた日のまま放置される。
+wasurenagusa は夜間にコード変更を検知し、ドキュメントを自動で更新する。
+
+### 3. トークン枠を使い切り
+
+Claude Code の 5 時間レート制限。寝ている間の枠は、普通なら無駄になる。
+wasurenagusa のスケジューラは、アイドル時間を使って自律タスクを自動実行する。
+Spec ドキュメントの更新、リファクタリング、テスト追加 ── `task_submit` で投入したタスクを Claude が 24/365 で処理し、LLM が完了条件を評価してリトライまでやる。
+
+---
+
+## 仕組み
+
+```
+[セッション開始]
+    │  SessionStart Hook
+    ▼
+wasurenagusa-context 実行
+  → config + dont を自動注入（設定・ルール・過去のミス）
+    │
+    ▼
+[会話中] ─── AIが必要に応じて memory_search → memory_get_detail を自律呼び出し
+    │
+    ▼
+[Claude 応答完了]
+    │  Stop Hook
+    ▼
+wasurenagusa-analyze 実行
+  → LLM で会話を自動分析
+  → 重要情報を自動保存（怒り検知・リトライパターン検出含む）
+  → 変更ファイルをログに記録（Spec 自動更新用）
+```
+
+**ユーザーの操作: ゼロ。**
+
+---
+
+## 他のメモリ MCP との違い
+
+| | wasurenagusa | 一般的なメモリ MCP |
+|---|---|---|
+| 保存方式 | LLM が会話を自動分析・自動保存 | ユーザーが手動で保存指示 |
+| 注入方式 | SessionStart Hook で自動注入 | 毎回手動で読み込み指示 |
+| トークン効率 | 段階的開示で 70-90% 削減 | 全件フル返却でコンテキスト圧迫 |
+| 感情検知 | 怒り・悲しみ・諦めを自動検出 | なし |
+| AI 自己学習 | リトライパターンを自動検出・記録 | なし |
+| dont 統合 | 数十件 → 数個の原則に自動圧縮 | エントリが増え続けてノイズ化 |
+
+---
+
+## 主要機能
+
+### 自動記憶（Hooks 連携）
+
+- **SessionStart Hook**: セッション開始時に config（設定）と dont（やってはいけないこと）を自動注入
+- **Stop Hook**: 会話終了時に LLM で分析し、重要情報を自動保存
+
+### 感情検知
+
+ユーザーの怒り・悲しみ・失望・諦めを検知し、「❌何をした → 💡なぜダメか → ✅どうすべきか」の 3 点セットで記録。
+テキストパターンだけでなく、メッセージ長の急減少やポジティブ反応の長期不在といったメタ情報でも検出する。
+
+### AI リトライパターン検出
+
+同じ API を 3 回以上実行、同じエラーが 3 回以上発生 ── AI 自身の失敗パターンも自動で学習し、「正しいやり方」を記録する。
+
+### 段階的開示（トークン最適化）
+
+検索結果はインデックス（ID・タイトル・タグ）のみ返し、必要な項目だけフル取得する 2 段階設計。
+従来の全件返却と比較して **トークン消費を 70-90% 削減**。
+
+### 重複検出
+
+LLM ベースのセマンティック重複検出。同じテーマの新しい情報は既存エントリを自動で置換する。
+
+### dont 統合
+
+dont エントリが増えすぎた場合、LLM で 5-6 個の行動原則に自動統合。
+元エントリは保持したまま、コンテキスト注入サイズを 36KB → 3-4KB に圧縮する。
+
+### 自律タスク実行
+
+`task_submit` でタスクを投入すると、スケジューラが Claude CLI をサブプロセスとして起動し自動実行する。
+LLM が実行結果を完了条件と照合し、未達ならリトライする。Spec 更新、リファクタリング、テスト追加など汎用的に使える。
+
+### Spec 自動更新（スケジューラ）
+
+自律タスクの代表的なユースケース。夜間の 5 時間ウィンドウで、変更されたコードに対応する Spec ドキュメントを自動更新。
+タスクがない場合は keep-alive ping でレート制限枠をリセットする。
+
+### Owner Profile
+
+MCP サーバー初回起動時に `.wasurenagusa/owner-profile.md` が自動生成される。
+優先順位、設計方針、コミュニケーションスタイルなど 20 の質問に答えておくと、AI が自律タスク実行時にその基準で判断する。
+
+---
+
+## セットアップ
+
+### 前提条件
+
+- Node.js 18+
+- Claude Code（CLI）
+- Gemini API キー（[Google AI Studio](https://aistudio.google.com/) で取得）
+
+### 1. クローンとビルド
+
+```bash
+git clone git@github.com:tsutushi0628/wasurenagusa-mcp.git
+cd wasurenagusa-mcp
+npm install
+npm run build
+```
+
+### 2. CLI コマンドを PATH に通す
+
+```bash
+npm link
+```
+
+これで `wasurenagusa-context`、`wasurenagusa-analyze`、`wasurenagusa-spec-update` がグローバルに使えるようになる。
+
+### 3. 環境変数の設定
+
+```bash
+cp .env.example .env
+```
+
+`.env` を編集:
+
+```
+GEMINI_API_KEY=your_gemini_api_key_here
+MEMORY_DIR=.wasurenagusa
+SLACK_WEBHOOK_URL=                    # オプション: Slack通知を有効にする場合
+```
+
+| 変数 | 必須 | 説明 |
+|------|------|------|
+| `GEMINI_API_KEY` | 必須 | Gemini API キー |
+| `MEMORY_DIR` | 任意 | メモリ保存先ディレクトリ（デフォルト: `.wasurenagusa`） |
+| `SLACK_WEBHOOK_URL` | 任意 | 自律タスクの完了/失敗を Slack に通知 |
+
+### 4. Claude Code に MCP サーバーを登録
+
+```bash
+claude mcp add wasurenagusa -- node /path/to/wasurenagusa-mcp/dist/index.js
+```
+
+### 5. Hooks の設定
+
+`~/.claude/settings.local.json`（または プロジェクトの `.claude/settings.local.json`）に以下を追加:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "wasurenagusa-context",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "wasurenagusa-analyze",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 6. 動作確認
+
+Claude Code を起動する。初回は `.wasurenagusa/` ディレクトリが自動作成され、`owner-profile.md` のテンプレートが配置される。
+
+```
+.wasurenagusa/
+├── owner-profile.md    ← 初回自動生成。編集するとAIの自律判断に反映
+├── config.md           ← 会話から自動蓄積
+├── dont.md             ← 会話から自動蓄積
+├── decisions.md        ← 会話から自動蓄積
+├── snippets.md         ← 会話から自動蓄積
+└── logs/               ← 日付別ログ
+```
+
+最初の会話を終えると、Stop Hook が起動して LLM が会話を分析し、重要情報が自動保存される。
+2 回目以降のセッションでは、蓄積された情報が SessionStart Hook で自動注入される。
+
+> **重要**: `.wasurenagusa/` にはプロジェクト固有の記憶データが保存される。あなたのプロジェクトの `.gitignore` に追加しておくこと。
+>
+> ```bash
+> echo '.wasurenagusa/' >> .gitignore
+> ```
+
+### 7. （オプション）プロジェクト初期設定
+
+自律タスク機能（Spec 自動更新など）を使う場合は、Claude Code 上で `project_init` ツールを実行する。
+プロジェクトの品質基準・フェーズ・判断基準を選択式で登録できる。
+
+### 8. （オプション）Spec 自動更新スケジューラ
+
+夜間にドキュメントを自動更新するには、cron や launchd で `wasurenagusa-spec-update` を定期実行する。
+
+```bash
+# 例: 毎日深夜1時に実行（cron）
+0 1 * * * cd /path/to/your-project && wasurenagusa-spec-update
+```
+
+---
+
+## メモリカテゴリ
+
+| カテゴリ | 説明 | 保存先 |
+|---------|------|--------|
+| **config** | API URL、ポート番号、認証情報の場所 | `.wasurenagusa/config.md` |
+| **dont** | やってはいけないこと、過去のミス | `.wasurenagusa/dont.md` |
+| **decision** | 技術選定、アーキテクチャ決定 | `.wasurenagusa/decisions.md` |
+| **log** | 実装完了、エラー解決の記録 | `.wasurenagusa/logs/YYYY-MM-DD.md` |
+| **snippet** | よく使うコマンド、クエリ | `.wasurenagusa/snippets.md` |
+
+---
+
+## MCP ツール
+
+| ツール名 | 実行方式 | 説明 |
+|---------|---------|------|
+| `memory_get_context` | AI 自律 | config + dont を一括取得 |
+| `memory_search` | AI 自律 | 軽量インデックス検索（ID・タイトル・タグのみ） |
+| `memory_get_detail` | AI 自律 | 指定 ID のフル詳細を取得 |
+| `memory_save` | 手動（オプション） | 明示的な記憶保存 |
+| `memory_delete` | 手動 | エントリ削除（ID 指定、複数一括可） |
+| `task_submit` | AI 自律 | 自律タスクの投入 |
+| `task_status` | AI 自律 | タスク状態の確認 |
+| `task_action_list` | AI 自律 | 実行可能アクション一覧 |
+| `project_init` | 手動 | プロジェクト初期設定 |
+
+---
+
+## CLI コマンド
+
+| コマンド | 用途 | 呼び出し元 |
+|---------|------|-----------|
+| `wasurenagusa-context` | config + dont をstdoutに出力 | SessionStart Hook |
+| `wasurenagusa-analyze` | 会話を LLM 分析し自動保存 | Stop Hook |
+| `wasurenagusa-spec-update` | Spec ドキュメント自動更新 | cron / systemd timer |
+
+---
+
+## 技術スタック
+
+| 技術 | 用途 |
+|------|------|
+| TypeScript | 実装言語 |
+| MCP SDK (`@modelcontextprotocol/sdk`) | MCP プロトコル |
+| Gemini API (`@google/generative-ai`) | 会話分析・重複検出・dont統合 |
+| Markdown | ストレージ形式 |
+| STDIO | トランスポート |
+
+---
+
+## ディレクトリ構成
+
+```
+wasurenagusa-mcp/
+├── src/
+│   ├── index.ts              # MCP サーバーエントリポイント
+│   ├── config.ts             # 設定管理
+│   ├── types.ts              # 型定義
+│   ├── cli/
+│   │   ├── context.ts        # SessionStart Hook 用 CLI
+│   │   ├── analyze.ts        # Stop Hook 用 CLI
+│   │   └── spec-update.ts    # Spec 自動更新 CLI
+│   ├── tools/                # MCP ツール定義
+│   ├── storage/              # Markdown ストレージ
+│   ├── analyzer/             # Gemini 連携・会話分析
+│   ├── autonomous/           # 自律タスク実行
+│   ├── consolidator/         # dont 統合
+│   ├── scheduler/            # Spec 更新スケジューラ
+│   ├── notifier/             # Slack 通知
+│   └── utils/                # ユーティリティ
+├── prompts/                  # Gemini プロンプト（外部化）
+├── docs/
+│   └── spec.md               # 完全実装仕様書
+├── .env.example
+├── package.json
+└── tsconfig.json
+```
+
+---
+
+## 開発
+
+```bash
+# ビルド
+npm run build
+
+# テスト
+npm test
+
+# テスト（ウォッチモード）
+npm run test:watch
+```
+
+---
+
+## 設計思想
+
+- **自律自動が基本、手動はオプション** — ユーザーに手動操作を強いない。Hooks で完全自動化
+- **コンテキストを圧迫しない軽量設計** — 段階的開示で必要な情報だけ取得
+- **プロンプト外部化** — `prompts/` に LLM プロンプトをテキストファイルとして配置。デプロイなしで改善可能
+- **ローカル実行** — セットアップ簡単。外部サービスは Gemini API のみ
+
+---
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,224 @@
+# wasurenagusa
+
+**Teach your AI coding agent to learn from its mistakes.**
+
+> *wasurenagusa* (忘れな草) — "forget-me-not" in Japanese.
+
+---
+
+## The Problem
+
+AI coding agents are geniuses that forget everything the moment a session ends. Your project conventions, past failures, your preferences — all gone. Every new session starts from zero.
+
+The native solution (CLAUDE.md) silently stops working after 200 lines. Your AI stops following rules and you don't even know why.
+
+## The Solution
+
+wasurenagusa is an MCP server that gives AI agents human-like memory:
+
+1. **Auto-detect mistakes** — Detects retry patterns, user frustration, and repeated failures
+2. **Auto-consolidate lessons** — LLM compresses hundreds of "don't do this" entries into a few core principles
+3. **Auto-inject on session start** — Every new session begins with the accumulated wisdom of all past sessions
+
+**Zero manual effort.** Hooks handle everything automatically.
+
+### Real-world results
+
+From the author's daily use across 8 projects:
+
+```
+508 mistake entries  →  7 principles (auto-consolidated)
+788 KB of raw data   →  3 KB injected per session (99.6% reduction)
+```
+
+---
+
+## How It Works
+
+```
+Session Start (Hook)
+  → wasurenagusa injects config + consolidated principles
+
+During Session
+  → AI calls memory_search / memory_save as needed
+
+Session End (Hook)
+  → LLM analyzes the conversation
+  → Detects mistakes, frustration, retry patterns
+  → Auto-saves important context
+
+Background (optional)
+  → Consolidates growing "dont" entries into principles
+  → Runs autonomous tasks (spec updates, refactoring)
+```
+
+---
+
+## What Makes This Different
+
+| | wasurenagusa | claude-mem | Cipher | CLAUDE.md |
+|---|---|---|---|---|
+| Auto-detect mistakes | Yes (retry + sentiment) | No | No | No |
+| Auto-consolidate to principles | Yes (LLM-powered) | No | No | No |
+| Zero-effort via hooks | Yes | Yes | No | No |
+| Human-readable storage | Yes (Markdown) | No | No | Yes |
+| Token-efficient retrieval | Yes (70-90% savings) | Yes | No | No |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 18+
+- Claude Code (CLI)
+- Gemini API key ([Google AI Studio](https://aistudio.google.com/))
+
+### 1. Install & Build
+
+```bash
+git clone https://github.com/tsutushi0628/wasurenagusa-mcp.git
+cd wasurenagusa-mcp
+npm install && npm run build
+npm link
+```
+
+### 2. Set API Key
+
+```bash
+cp .env.example .env
+# Edit .env → set GEMINI_API_KEY
+```
+
+### 3. Register MCP Server
+
+```bash
+claude mcp add wasurenagusa -- node /path/to/wasurenagusa-mcp/dist/index.js
+```
+
+### 4. Configure Hooks
+
+Add to `~/.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "wasurenagusa-context",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "wasurenagusa-analyze",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 5. Start Using
+
+Launch Claude Code. That's it.
+
+- First session: `.wasurenagusa/` directory is created automatically
+- After first conversation: Stop Hook saves important context
+- Second session onward: context is auto-injected at start
+
+> Add `.wasurenagusa/` to your `.gitignore` — it contains project-specific memory data.
+
+---
+
+## Memory Categories
+
+| Category | What it stores | File |
+|----------|---------------|------|
+| **config** | API URLs, ports, auth locations | `config.md` |
+| **dont** | Mistakes, anti-patterns, user frustrations | `dont.md` |
+| **decision** | Architecture decisions, tech choices | `decisions.md` |
+| **log** | Implementation records, resolved errors | `logs/YYYY-MM-DD.md` |
+| **snippet** | Frequently used commands & queries | `snippets.md` |
+
+---
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_get_context` | Get config + dont (auto-called at session start) |
+| `memory_search` | Lightweight index search (ID, title, tags only) |
+| `memory_get_detail` | Get full detail by ID |
+| `memory_save` | Explicitly save a memory |
+| `memory_delete` | Delete entries by ID |
+| `task_submit` | Submit autonomous task (24/7 execution) |
+| `task_status` | Check task status |
+| `project_init` | Initialize project settings |
+
+---
+
+## Advanced Features
+
+### Dont Consolidation
+
+When "dont" entries pile up, the LLM automatically compresses them into 5-7 behavioral principles. Raw entries are preserved; only the consolidated summary is injected at session start.
+
+### 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.
+
+### 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.
+
+### 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.
+
+---
+
+## Current Limitations
+
+- **Gemini only** — Currently requires a Gemini API key. OpenAI/Anthropic provider support is planned.
+- **Claude Code only** — Hook-based auto-injection is Claude Code specific. The MCP server itself works with any MCP-compatible tool, but without auto-injection.
+- **No memory size limits** — Long-running projects may accumulate large memory files. Consolidation mitigates this for "dont" entries, but logs can grow unbounded.
+
+---
+
+## Design Philosophy
+
+- **Autonomous by default, manual by choice** — Never require manual operation. Hooks automate everything.
+- **Token-conscious** — Two-stage retrieval (index → detail) reduces context consumption by 70-90%.
+- **Human-readable storage** — All memory stored as Markdown. No database, no vendor lock-in.
+- **Externalized prompts** — LLM prompts live in `prompts/` as plain text files. Iterate without redeploying.
+
+---
+
+## Development
+
+```bash
+npm run build    # Compile TypeScript
+npm test         # Run tests
+npm run test:watch
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+[日本語 README](./README.ja.md)

package/dist/analyzer/conversation-meta.d.ts

@@ -0,0 +1,10 @@
+export interface ParsedMessage {
+    role: string;
+    text: string;
+}
+export interface ConversationMeta {
+    avgUserMessageLength: number;
+    currentMessageLength: number;
+    turnsSinceLastPositive: number;
+}
+export declare function computeConversationMeta(messages: ParsedMessage[]): ConversationMeta;

package/dist/analyzer/conversation-meta.js

@@ -0,0 +1,25 @@
+const POSITIVE_PATTERNS = /ありがとう|いいね|よさそう|完璧|おけ|ok|good|great|nice|👍|🎉|素晴らしい|助かる/i;
+export function computeConversationMeta(messages) {
+    const userMessages = messages.filter(m => m.role === "user");
+    if (userMessages.length === 0) {
+        return { avgUserMessageLength: 0, currentMessageLength: 0, turnsSinceLastPositive: 0 };
+    }
+    const current = userMessages[userMessages.length - 1];
+    const currentLength = current.text.length;
+    // 直近5件のユーザーメッセージで平均を計算
+    const recent = userMessages.slice(-5);
+    const avgLength = recent.reduce((sum, m) => sum + m.text.length, 0) / recent.length;
+    // 最後のポジティブ反応からの経過ターン数
+    let turnsSincePositive = 0;
+    for (let i = userMessages.length - 1; i >= 0; i--) {
+        if (POSITIVE_PATTERNS.test(userMessages[i].text)) {
+            break;
+        }
+        turnsSincePositive++;
+    }
+    return {
+        avgUserMessageLength: Math.round(avgLength),
+        currentMessageLength: currentLength,
+        turnsSinceLastPositive: turnsSincePositive,
+    };
+}

package/dist/analyzer/gemini-client.d.ts

@@ -0,0 +1,2 @@
+import type { GenerativeModel } from "@google/generative-ai";
+export declare function createGeminiModel(): GenerativeModel;

package/dist/analyzer/gemini-client.js

@@ -0,0 +1,9 @@
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { config } from "../config.js";
+export function createGeminiModel() {
+    if (!config.geminiApiKey) {
+        throw new Error("GEMINI_API_KEY is not set");
+    }
+    const genAI = new GoogleGenerativeAI(config.geminiApiKey);
+    return genAI.getGenerativeModel({ model: config.geminiModel });
+}

package/dist/analyzer/gemini.d.ts

@@ -0,0 +1,9 @@
+import { AnalysisResult, AnalysisInput, DuplicateCheckInput } from "../types.js";
+import { GenerateTextFn } from "../llm/provider.js";
+export declare class Analyzer {
+    private generateText;
+    constructor(generateText?: GenerateTextFn);
+    analyze(input: AnalysisInput): Promise<AnalysisResult>;
+    checkDuplicate(input: DuplicateCheckInput): Promise<string | null>;
+    private defaultResult;
+}