@hir4ta/memoria 0.9.1 → 0.9.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memoria",
-  "description": "Claude Codeに長期記憶を与えるプラグイン。auto-compactで失われるコンテキストを自動保存し、セッション復元、技術的な判断の記録、開発者パターンの学習機能を提供。",
-  "version": "0.9.1",
+  "description": "A plugin that provides long-term memory for Claude Code. It automatically saves context lost during auto-compact, offering features for session restoration, recording technical decisions, and learning developer patterns.",
+  "version": "0.9.3",
   "author": {
     "name": "hir4ta"
   },

package/README.ja.md

@@ -0,0 +1,284 @@
+# memoria
+
+Claude Codeの長期記憶を実現するプラグイン
+
+セッションのリアルタイム保存、技術的な判断の記録、Webダッシュボードでの管理を提供します。
+
+## 機能
+
+### コア機能
+- **リアルタイムセッション更新**: 意味のある変化があった時にセッションJSONを自動更新
+- **セッション再開**: `/memoria:resume` で過去のセッションを再開
+- **技術的な判断の記録**: `/memoria:decision` で判断を記録
+- **ルールベースレビュー**: `dev-rules.json` / `review-guidelines.json` に基づくレビュー
+- **週次レポート**: レビュー結果を集計したMarkdownレポートを自動生成
+- **Webダッシュボード**: セッション・判断記録の閲覧・編集
+
+### 開発ワークフロー
+- **ブレインストーミング**: ソクラティック質問 + 記憶参照で設計 (`/memoria:brainstorm`)
+- **計画作成**: 2-5分単位のTDDタスク分割 (`/memoria:plan`)
+- **TDD**: RED-GREEN-REFACTORサイクルの厳格強制 (`/memoria:tdd`)
+- **デバッグ**: 根本原因分析 + エラーパターン参照 (`/memoria:debug`)
+- **二段階レビュー**: 仕様準拠 + コード品質 (`/memoria:review --full`)
+
+## 課題と解決（導入メリット）
+
+### Claude Code 開発で起きがちな課題
+
+- **コンテキストの消失**: セッション終了やAuto-Compactで会話の文脈が失われる
+- **判断の不透明化**: 「なぜこの設計にしたのか」が後から追えない
+- **知見の再利用が難しい**: 過去のやり取りや決定を検索・参照しづらい
+
+### memoria でできること／解消できること
+
+- **リアルタイム保存 + 再開**で、セッションを跨いだ文脈の継続が可能
+- **判断記録**で、理由・代替案を後から追跡
+- **検索とダッシュボード**で、過去の記録を素早く参照
+- **レビュー機能**で、リポジトリ固有の観点に基づいて指摘
+- **週次レポート**で、レビュー観点の改善と共有が容易
+
+### チーム利用のメリット
+
+- `.memoria/` のJSONは**Git管理可能**なので、判断や会話の履歴をチームで共有できる
+- オンボーディングやレビュー時に「背景・経緯」を短時間で把握できる
+
+## インストール
+
+### 前提条件
+
+- **jq**: フックでJSON処理に使用します
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# Windows (Chocolatey)
+choco install jq
+
+# Windows (Scoop)
+scoop install jq
+
+# Windows (winget)
+winget install jqlang.jq
+```
+
+### プラグインのインストール
+
+Claude Code内で以下を実行
+
+```bash
+/plugin marketplace add hir4ta/memoria-marketplace
+/plugin install memoria@memoria-marketplace
+```
+
+Claude Codeを再起動して完了
+
+## アップデート
+
+Claude Code内で以下を実行
+
+```bash
+/plugin marketplace update memoria-marketplace
+```
+
+Claude Codeを再起動
+
+### 自動更新を有効にする（推奨）
+
+1. `/plugin` を実行
+2. Marketplaces タブを選択
+3. `memoria-marketplace` を選択
+4. "Enable auto-update" を有効化
+
+これによりClaude Code起動時に自動でアップデートされます
+
+## 使い方
+
+### 自動動作
+
+| タイミング | 動作 |
+| ----------- | ------ |
+| セッション開始時 | セッションJSONを初期化、関連セッションの提案 |
+| 会話中 | 意味のある変化があった時にセッションJSONを更新 |
+| セッション終了時 | フォールバック処理（未更新の場合）、クリーンアップ |
+
+### コマンド
+
+| コマンド | 説明 |
+| --------- | ------ |
+| `/memoria:resume [id]` | セッションを再開（ID省略で一覧表示） |
+| `/memoria:save` | 現在のセッションを強制保存 |
+| `/memoria:decision "タイトル"` | 技術的な判断を記録 |
+| `/memoria:search "クエリ"` | セッション・判断記録を検索 |
+| `/memoria:review [--staged\|--all\|--diff=branch\|--full]` | ルールに基づくレビュー（--fullで二段階） |
+| `/memoria:report [--from YYYY-MM-DD --to YYYY-MM-DD]` | 週次レビューレポート |
+| `/memoria:brainstorm [トピック]` | ソクラティック質問 + 記憶参照で設計 |
+| `/memoria:plan [トピック]` | 2-5分TDDタスクに分割した計画作成 |
+| `/memoria:tdd` | RED-GREEN-REFACTOR厳格サイクル |
+| `/memoria:debug` | 根本原因分析 + エラーパターン参照 |
+
+### 推奨ワークフロー
+
+```
+brainstorm → plan → tdd → review
+```
+
+1. **brainstorm**: ソクラティック質問 + 記憶参照で設計
+2. **plan**: 2-5分TDDタスクに分割
+3. **tdd**: RED → GREEN → REFACTOR で実装
+4. **review**: 仕様準拠（--full）+ コード品質をレビュー
+
+### ダッシュボード
+
+プロジェクトディレクトリで以下を実行
+
+```bash
+npx @hir4ta/memoria --dashboard
+```
+
+ブラウザで <http://localhost:7777> を開く。
+
+ポート変更:
+
+```bash
+npx @hir4ta/memoria --dashboard --port 8080
+```
+
+#### 画面一覧
+
+- **Sessions**: セッション一覧・詳細・編集・削除
+- **Decisions**: 技術的な判断の一覧・作成・編集・削除
+- **Rules**: 開発ルール・レビュー観点の閲覧・編集
+
+## 仕組み
+
+```mermaid
+flowchart TB
+    subgraph realtime [リアルタイム更新]
+        A[意味のある変化] --> B[セッションJSONを更新]
+        B --> C[interactions配列]
+    end
+
+    subgraph manual [手動操作]
+        D["memoria:save"] --> E[セッションを強制保存]
+        F["memoria:decision"] --> G[判断を明示的に記録]
+    end
+
+    subgraph resume [セッション再開]
+        H["memoria:resume"] --> I[一覧から選択]
+        I --> J[過去の文脈を復元]
+    end
+
+    subgraph search [検索]
+        K["memoria:search"] --> L[セッションと判断を検索]
+    end
+
+    subgraph review [レビュー]
+        P["memoria:review"] --> Q[ルールに基づく指摘]
+        Q --> R[レビュー結果を保存]
+    end
+
+    subgraph report [週次レポート]
+        S["memoria:report"] --> T[レビュー集計レポート]
+    end
+
+    subgraph dashboard [ダッシュボード]
+        M["npx @hir4ta/memoria -d"] --> N[ブラウザで表示]
+        N --> O[閲覧・編集・削除]
+    end
+
+    B --> H
+    E --> H
+    G --> K
+    B --> R
+    R --> T
+    B --> M
+    G --> M
+```
+
+## データ保存
+
+すべてのデータは `.memoria/` ディレクトリにJSON形式で保存
+
+```text
+.memoria/
+├── tags.json         # タグマスターファイル（93タグ、表記揺れ防止）
+├── sessions/         # セッション履歴 (YYYY/MM)
+├── decisions/        # 技術的な判断 (YYYY/MM)
+├── rules/            # 開発ルール / レビュー観点
+├── reviews/          # レビュー結果 (YYYY/MM)
+└── reports/          # 週次レポート (YYYY-MM)
+```
+
+Gitでバージョン管理可能です。`.gitignore` に追加するかはプロジェクトに応じて判断してください。
+
+### セッションJSONスキーマ
+
+セッションは **interactions ベース** のスキーマを使用します。各 interaction は決定サイクル（リクエスト → 思考 → 提案 → 選択 → 実装）を表します。
+
+```json
+{
+  "id": "2026-01-27_abc123",
+  "sessionId": "claude-code-からの-full-uuid",
+  "createdAt": "2026-01-27T10:00:00Z",
+  "context": {
+    "branch": "feature/auth",
+    "projectDir": "/path/to/project",
+    "user": { "name": "tanaka", "email": "tanaka@example.com" }
+  },
+  "title": "JWT認証機能の実装",
+  "goal": "JWTベースの認証機能を実装し、リフレッシュトークンにも対応する",
+  "tags": ["auth", "jwt", "backend"],
+  "interactions": [
+    {
+      "id": "int-001",
+      "topic": "認証方式の選択",
+      "timestamp": "2026-01-27T10:15:00Z",
+      "request": "認証機能を実装したい",
+      "thinking": "JWTとセッションCookieを比較...",
+      "webLinks": ["https://jwt.io/introduction"],
+      "proposals": [
+        { "option": "JWT", "description": "ステートレス、スケーラブル" },
+        { "option": "セッションCookie", "description": "シンプル" }
+      ],
+      "choice": "JWT",
+      "reasoning": "マイクロサービス間の認証共有が容易",
+      "actions": [
+        { "type": "create", "path": "src/auth/jwt.ts", "summary": "JWTモジュール" }
+      ],
+      "filesModified": ["src/auth/jwt.ts"]
+    }
+  ]
+}
+```
+
+### 更新トリガー
+
+Claude Code は意味のある変化があった時にセッションJSONを更新します：
+
+| トリガー | 更新内容 |
+|---------|---------|
+| セッションの目的が明確になった | `title`, `goal` |
+| ユーザーの指示に対応した | `interactions` に追加 |
+| 技術的決定を下した | `proposals`, `choice`, `reasoning` |
+| エラーに遭遇・解決した | `problem`, `choice`, `reasoning` |
+| ファイルを変更した | `actions`, `filesModified` |
+| URLを参照した | `webLinks` |
+| 新しいキーワードが出現 | `tags`（tags.jsonを参照） |
+
+### タグ
+
+タグは `.memoria/tags.json` から選択され、表記揺れを防止します（例: 「フロント」→「frontend」）。マスターファイルには11カテゴリ93タグが含まれています：
+
+- **domain**: frontend, backend, api, db, infra, mobile, cli
+- **phase**: feature, bugfix, refactor, test, docs
+- **ai**: llm, ai-agent, mcp, rag, vector-db, embedding
+- **cloud**: serverless, microservices, edge, wasm
+- その他...
+
+## ライセンス
+
+MIT

package/README.md

@@ -1,44 +1,52 @@
 # memoria
 
-Claude Codeの長期記憶を実現するプラグイン
+Long-term memory plugin for Claude Code
 
-セッションの自動保存、技術的な判断の記録、Webダッシュボードでの管理を提供します
+Provides automatic session saving, technical decision recording, and web dashboard management.
 
-## 機能
+## Features
 
-- **セッション自動保存**: セッション終了時・圧縮前に会話履歴を自動保存
-- **セッション再開**: `/memoria:resume` で過去のセッションを再開
-- **技術的な判断の記録**: セッション終了時に自動検出・保存（手動記録も可能）
-- **ルールベースレビュー**: `dev-rules.json` / `review-guidelines.json` に基づくレビュー
-- **週次レポート**: レビュー結果を集計したMarkdownレポートを自動生成
-- **Webダッシュボード**: セッション・判断記録の閲覧・編集
+### Core Features
+- **Real-time Session Updates**: Session JSON is updated when meaningful changes occur
+- **Session Resume**: Resume past sessions with `/memoria:resume`
+- **Technical Decision Recording**: Record decisions with `/memoria:decision`
+- **Rule-based Review**: Code review based on `dev-rules.json` / `review-guidelines.json`
+- **Weekly Reports**: Auto-generate Markdown reports aggregating review results
+- **Web Dashboard**: View and edit sessions, decisions, and rules
 
-## 課題と解決（導入メリット）
+### Development Workflow (superpowers-style)
+- **Brainstorming**: Socratic questioning + past memory lookup (`/memoria:brainstorm`)
+- **Planning**: 2-5 minute task breakdown with TDD enforcement (`/memoria:plan`)
+- **TDD**: Strict RED-GREEN-REFACTOR cycle (`/memoria:tdd`)
+- **Debugging**: Systematic root cause analysis + error pattern lookup (`/memoria:debug`)
+- **Two-stage Review**: Spec compliance + code quality (`/memoria:review --full`)
 
-### Claude Code 開発で起きがちな課題
+## Problems Solved
 
-- **コンテキストの消失**: セッション終了やAuto-Compactで会話の文脈が失われる
-- **判断の不透明化**: 「なぜこの設計にしたのか」が後から追えない
-- **知見の再利用が難しい**: 過去のやり取りや決定を検索・参照しづらい
+### Common Issues in Claude Code Development
 
-### memoria でできること／解消できること
+- **Context Loss**: Conversation context is lost on session end or Auto-Compact
+- **Opaque Decisions**: "Why did we choose this design?" becomes untraceable
+- **Hard to Reuse Knowledge**: Past interactions and decisions are hard to search and reference
 
-- **自動保存 + 再開**で、セッションを跨いだ文脈の継続が可能
-- **判断記録（自動/手動）**で、理由・代替案を後から追跡
-- **検索とダッシュボード**で、過去の記録を素早く参照
-- **レビュー機能**で、リポジトリ固有の観点に基づいて指摘
-- **週次レポート**で、レビュー観点の改善と共有が容易
+### What memoria Enables
 
-### チーム利用のメリット
+- **Auto-save + Resume** enables context continuity across sessions
+- **Decision Recording** tracks reasoning and alternatives for later review
+- **Search and Dashboard** for quick access to past records
+- **Review Feature** for repository-specific code review
+- **Weekly Reports** for improving and sharing review practices
 
-- `.memoria/` のJSONは**Git管理可能**なので、判断や会話の履歴をチームで共有できる
-- オンボーディングやレビュー時に「背景・経緯」を短時間で把握できる
+### Team Benefits
 
-## インストール
+- `.memoria/` JSON files are **Git-manageable**, enabling team sharing of decisions and session history
+- Quickly understand background and context during onboarding or reviews
 
-### 前提条件
+## Installation
 
-- **jq**: フックでJSON処理に使用します
+### Prerequisites
+
+- **jq**: Used for JSON processing in hooks
 
 ```bash
 # macOS
@@ -57,141 +65,220 @@ scoop install jq
 winget install jqlang.jq
 ```
 
-### プラグインのインストール
+### Plugin Installation
 
-Claude Code内で以下を実行
+Run the following in Claude Code:
 
 ```bash
 /plugin marketplace add hir4ta/memoria-marketplace
 /plugin install memoria@memoria-marketplace
 ```
 
-Claude Codeを再起動して完了
+Restart Claude Code to complete installation.
 
-## アップデート
+## Update
 
-Claude Code内で以下を実行
+Run the following in Claude Code:
 
 ```bash
 /plugin marketplace update memoria-marketplace
 ```
 
-Claude Codeを再起動
+Restart Claude Code.
+
+### Enable Auto-Update (Recommended)
 
-### 自動更新を有効にする（推奨）
+1. Run `/plugin`
+2. Select Marketplaces tab
+3. Select `memoria-marketplace`
+4. Enable "Enable auto-update"
 
-1. `/plugin` を実行
-2. Marketplaces タブを選択
-3. `memoria-marketplace` を選択
-4. "Enable auto-update" を有効化
+This will auto-update on Claude Code startup.
 
-これによりClaude Code起動時に自動でアップデートされます
+## Usage
 
-## 使い方
+### Automatic Behavior
 
-### 自動動作
+| Timing | Action |
+|--------|--------|
+| Session Start | Suggest related sessions, initialize session JSON |
+| During Session | Claude Code updates session JSON on meaningful changes |
+| Session End | Fallback processing if not updated, cleanup |
 
-| タイミング | 動作 |
-| ----------- | ------ |
-| セッション開始時 | 関連セッションの提案 |
-| セッション終了時 | 会話履歴を保存、技術的な判断を自動検出 |
-| 圧縮前 | 進行中のセッションを保存 |
+### Commands
 
-### コマンド
+| Command | Description |
+|---------|-------------|
+| `/memoria:resume [id]` | Resume session (show list if ID omitted) |
+| `/memoria:save` | Force flush current session |
+| `/memoria:decision "title"` | Record a technical decision |
+| `/memoria:search "query"` | Search sessions and decisions |
+| `/memoria:review [--staged\|--all\|--diff=branch\|--full]` | Rule-based code review (--full for two-stage) |
+| `/memoria:report [--from YYYY-MM-DD --to YYYY-MM-DD]` | Weekly review report |
+| `/memoria:brainstorm [topic]` | Design-first Socratic questioning + memory lookup |
+| `/memoria:plan [topic]` | Create implementation plan with 2-5 min TDD tasks |
+| `/memoria:tdd` | Strict RED-GREEN-REFACTOR development cycle |
+| `/memoria:debug` | Systematic debugging with error pattern lookup |
 
-| コマンド | 説明 |
-| --------- | ------ |
-| `/memoria:resume [id]` | セッションを再開（ID省略で一覧表示） |
-| `/memoria:save` | 現在のセッションを手動保存 |
-| `/memoria:decision "タイトル"` | 技術的な判断を記録 |
-| `/memoria:search "クエリ"` | セッション・判断記録を検索 |
-| `/memoria:review [--staged|--all|--diff=branch]` | ルールに基づくレビュー |
-| `/memoria:report [--from YYYY-MM-DD --to YYYY-MM-DD]` | 週次レビューレポート |
+### Recommended Workflow
 
-### ダッシュボード
+```
+brainstorm → plan → tdd → review
+```
 
-プロジェクトディレクトリで以下を実行
+1. **brainstorm**: Design with Socratic questions + past memory lookup
+2. **plan**: Break into 2-5 minute TDD tasks
+3. **tdd**: Implement with RED → GREEN → REFACTOR
+4. **review**: Verify against plan (--full) and code quality
+
+### Dashboard
+
+Run in your project directory:
 
 ```bash
 npx @hir4ta/memoria --dashboard
 ```
 
-ブラウザで <http://localhost:7777> を開く。
+Open <http://localhost:7777> in your browser.
 
-ポート変更:
+Change port:
 
 ```bash
 npx @hir4ta/memoria --dashboard --port 8080
 ```
 
-#### 画面一覧
+#### Screens
 
-- **Sessions**: セッション一覧・詳細・編集・削除
-- **Decisions**: 技術的な判断の一覧・作成・編集・削除
-- **Rules**: 開発ルール・レビュー観点の閲覧・編集
+- **Sessions**: List, view, edit, delete sessions
+- **Decisions**: List, create, edit, delete technical decisions
+- **Rules**: View and edit dev rules and review guidelines
 
-## 仕組み
+## How It Works
 
 ```mermaid
 flowchart TB
-    subgraph auto [自動保存]
-        A[セッション終了] --> B[会話履歴を保存]
-        A --> C[技術的な判断を自動検出]
+    subgraph realtime [Real-time Updates]
+        A[Meaningful Change] --> B[Update Session JSON]
+        B --> C[interactions array]
     end
 
-    subgraph manual [手動保存]
-        D["memoria:save"] --> E[任意のタイミングで保存]
-        F["memoria:decision"] --> G[技術的な判断を明示的に記録]
+    subgraph manual [Manual Actions]
+        D["memoria:save"] --> E[Force flush session]
+        F["memoria:decision"] --> G[Record decision explicitly]
     end
 
-    subgraph resume [セッション再開]
-        H["memoria:resume"] --> I[一覧から選択]
-        I --> J[過去の文脈を復元]
+    subgraph resume [Session Resume]
+        H["memoria:resume"] --> I[Select from list]
+        I --> J[Restore past context]
     end
 
-    subgraph search [検索]
-        K["memoria:search"] --> L[セッションと判断を検索]
+    subgraph search [Search]
+        K["memoria:search"] --> L[Search sessions and decisions]
     end
 
-    subgraph review [レビュー]
-        P["memoria:review"] --> Q[ルールに基づく指摘]
-        Q --> R[レビュー結果を保存]
+    subgraph review [Review]
+        P["memoria:review"] --> Q[Rule-based findings]
+        Q --> R[Save review results]
     end
 
-    subgraph report [週次レポート]
-        S["memoria:report"] --> T[レビュー集計レポート]
+    subgraph report [Weekly Report]
+        S["memoria:report"] --> T[Review summary report]
     end
 
-    subgraph dashboard [ダッシュボード]
-        M["npx @hir4ta/memoria -d"] --> N[ブラウザで表示]
-        N --> O[閲覧・編集・削除]
+    subgraph dashboard [Dashboard]
+        M["npx @hir4ta/memoria -d"] --> N[Open in browser]
+        N --> O[View, edit, delete]
     end
 
     B --> H
     E --> H
-    C --> K
     G --> K
     B --> R
     R --> T
     B --> M
-    C --> M
+    G --> M
 ```
 
-## データ保存
+## Data Storage
 
-すべてのデータは `.memoria/` ディレクトリにJSON形式で保存
+All data is stored in `.memoria/` directory as JSON:
 
 ```text
 .memoria/
-├── sessions/       # セッション履歴 (YYYY/MM)
-├── decisions/      # 技術的な判断 (YYYY/MM)
-├── rules/          # 開発ルール / レビュー観点
-├── reviews/        # レビュー結果 (YYYY/MM)
-└── reports/        # 週次レポート (YYYY-MM)
+├── tags.json         # Tag master file (93 tags, prevents notation variations)
+├── sessions/         # Session history (YYYY/MM)
+├── decisions/        # Technical decisions (YYYY/MM)
+├── rules/            # Dev rules / review guidelines
+├── reviews/          # Review results (YYYY/MM)
+└── reports/          # Weekly reports (YYYY-MM)
 ```
 
-Gitでバージョン管理可能です。`.gitignore` に追加するかはプロジェクトに応じて判断してください。
+Git-manageable. Add to `.gitignore` based on your project needs.
+
+### Session JSON Schema
+
+Sessions use an **interactions-based** schema. Each interaction represents a decision cycle (request → thinking → proposals → choice → implementation).
+
+```json
+{
+  "id": "2026-01-27_abc123",
+  "sessionId": "full-uuid-from-claude-code",
+  "createdAt": "2026-01-27T10:00:00Z",
+  "context": {
+    "branch": "feature/auth",
+    "projectDir": "/path/to/project",
+    "user": { "name": "tanaka", "email": "tanaka@example.com" }
+  },
+  "title": "JWT authentication implementation",
+  "goal": "Implement JWT-based auth with refresh token support",
+  "tags": ["auth", "jwt", "backend"],
+  "interactions": [
+    {
+      "id": "int-001",
+      "topic": "Auth method selection",
+      "timestamp": "2026-01-27T10:15:00Z",
+      "request": "Implement authentication",
+      "thinking": "Comparing JWT vs session cookies...",
+      "webLinks": ["https://jwt.io/introduction"],
+      "proposals": [
+        { "option": "JWT", "description": "Stateless, scalable" },
+        { "option": "Session Cookie", "description": "Simple" }
+      ],
+      "choice": "JWT",
+      "reasoning": "Easy auth sharing between microservices",
+      "actions": [
+        { "type": "create", "path": "src/auth/jwt.ts", "summary": "JWT module" }
+      ],
+      "filesModified": ["src/auth/jwt.ts"]
+    }
+  ]
+}
+```
+
+### Update Triggers
+
+Claude Code updates session JSON when meaningful changes occur:
+
+| Trigger | Update |
+|---------|--------|
+| Session purpose becomes clear | `title`, `goal` |
+| User instruction handled | Add to `interactions` |
+| Technical decision made | `proposals`, `choice`, `reasoning` |
+| Error encountered/resolved | `problem`, `choice`, `reasoning` |
+| File modified | `actions`, `filesModified` |
+| URL referenced | `webLinks` |
+| New keyword appears | `tags` (reference tags.json) |
+
+### Tags
+
+Tags are selected from `.memoria/tags.json` to prevent notation variations (e.g., "フロント" → "frontend"). The master file contains 93 tags across 11 categories:
+
+- **domain**: frontend, backend, api, db, infra, mobile, cli
+- **phase**: feature, bugfix, refactor, test, docs
+- **ai**: llm, ai-agent, mcp, rag, vector-db, embedding
+- **cloud**: serverless, microservices, edge, wasm
+- And more...
 
-## ライセンス
+## License
 
 MIT