@hir4ta/memoria 0.10.1 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memoria",
   "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.10.1",
+  "version": "0.11.0",
   "author": {
     "name": "hir4ta"
   },

package/README.ja.md

@@ -7,7 +7,8 @@ Claude Codeの長期記憶を実現するプラグイン
 ## 機能
 
 ### コア機能
-- **リアルタイムセッション更新**: 意味のある変化があった時にセッションJSONを自動更新
+- **明示的セッション保存**: `/memoria:save` または「セッション保存して」で保存
+- **APIフォールバック**: Auto-Compact前とセッション終了時にOpenAI APIで自動保存
 - **セッション再開**: `/memoria:resume` で過去のセッションを再開
 - **技術的な判断の記録**: `/memoria:decision` で判断を記録
 - **ルールベースレビュー**: `dev-rules.json` / `review-guidelines.json` に基づくレビュー
@@ -31,7 +32,7 @@ Claude Codeの長期記憶を実現するプラグイン
 
 ### memoria でできること／解消できること
 
-- **リアルタイム保存 + 再開**で、セッションを跨いだ文脈の継続が可能
+- **自動保存 + 再開**で、セッションを跨いだ文脈の継続が可能
 - **判断記録**で、理由・代替案を後から追跡
 - **検索とダッシュボード**で、過去の記録を素早く参照
 - **レビュー機能**で、リポジトリ固有の観点に基づいて指摘
@@ -95,22 +96,47 @@ Claude Codeを再起動
 
 これによりClaude Code起動時に自動でアップデートされます
 
+## 設定（オプション）
+
+APIフォールバックによる自動セッション保存を有効にするには、`/memoria:init` を実行するか、手動で `~/.claude/memoria.json` を作成してください：
+
+```json
+{
+  "openai_api_key": "sk-...",
+  "model": "gpt-5-mini"
+}
+```
+
+| フィールド | 必須 | デフォルト | 説明 |
+|-----------|------|-----------|------|
+| `openai_api_key` | いいえ | - | 設定すると自動保存が有効になる |
+| `model` | いいえ | `gpt-5-mini` | 使用するモデル（gpt-5-mini, gpt-5, gpt-5.2など） |
+
+**`openai_api_key` なし**: `/memoria:save` での手動保存のみ。
+
+**`openai_api_key` あり**: 自動保存が有効になり、以下のタイミングで保存：
+- Auto-Compact前（status: `draft`）
+- セッション終了時（status: `complete`）
+
 ## 使い方
 
-### 自動動作
+### セッション保存
 
-| タイミング | 動作 |
-| ----------- | ------ |
-| セッション開始時 | セッションJSONを初期化、関連セッションの提案 |
-| 会話中 | 意味のある変化があった時にセッションJSONを更新 |
-| セッション終了時 | ログ出力 |
+| 方法 | タイミング | ステータス |
+|------|----------|-----------|
+| **明示的保存** | `/memoria:save` または「セッション保存して」 | `complete` |
+| **PreCompact** | Auto-Compact前（API） | `draft` |
+| **SessionEnd** | セッション終了時（API） | `complete` |
+
+**注意**: PreCompact/SessionEnd のAPIフォールバックには `~/.claude/memoria.json` の設定が必要です。
 
 ### コマンド
 
 | コマンド | 説明 |
 | --------- | ------ |
+| `/memoria:init` | 設定ファイルを初期化（`~/.claude/memoria.json`） |
 | `/memoria:resume [id]` | セッションを再開（ID省略で一覧表示） |
-| `/memoria:save` | 現在のセッションを強制保存 |
+| `/memoria:save` | セッション保存 + 会話からルール抽出 |
 | `/memoria:decision "タイトル"` | 技術的な判断を記録 |
 | `/memoria:search "クエリ"` | セッション・判断記録を検索 |
 | `/memoria:review [--staged\|--all\|--diff=branch\|--full]` | ルールに基づくレビュー（--fullで二段階） |
@@ -217,42 +243,59 @@ Gitでバージョン管理可能です。`.gitignore` に追加するかはプ
 
 ### セッションJSONスキーマ
 
-セッションは **interactions ベース** のスキーマを使用します。各 interaction は決定サイクル（リクエスト → 思考 → 提案 → 選択 → 実装）を表します。
+セッションは **分析向け** のスキーマを使用します。定量データ（metrics）と定性データ（summary）を分離し、files/decisions/errorsを独立配列として集計可能にしています。
 
 ```json
 {
-  "id": "2026-01-27_abc123",
+  "id": "abc12345",
   "sessionId": "claude-code-からの-full-uuid",
   "createdAt": "2026-01-27T10:00:00Z",
+  "endedAt": "2026-01-27T12: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"],
-  "sessionType": "implementation",
-  "interactions": [
+  "summary": {
+    "title": "JWT認証機能の実装",
+    "goal": "JWTベースの認証機能を実装",
+    "outcome": "success",
+    "description": "RS256署名でJWT認証を実装"
+  },
+  "metrics": {
+    "durationMinutes": 120,
+    "filesCreated": 2,
+    "filesModified": 1,
+    "decisionsCount": 2,
+    "errorsEncountered": 1,
+    "errorsResolved": 1
+  },
+  "files": [
+    { "path": "src/auth/jwt.ts", "action": "create", "summary": "JWTモジュール" }
+  ],
+  "decisions": [
     {
-      "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": "シンプル" }
-      ],
+      "id": "dec-001",
+      "topic": "認証方式",
       "choice": "JWT",
+      "alternatives": ["セッションCookie"],
       "reasoning": "マイクロサービス間の認証共有が容易",
-      "actions": [
-        { "type": "create", "path": "src/auth/jwt.ts", "summary": "JWTモジュール" }
-      ],
-      "filesModified": ["src/auth/jwt.ts"]
+      "timestamp": "2026-01-27T10:15:00Z"
     }
-  ]
+  ],
+  "errors": [
+    {
+      "id": "err-001",
+      "message": "secretOrPrivateKey must be asymmetric",
+      "type": "runtime",
+      "resolved": true,
+      "solution": "RS256用にPEM形式に変更"
+    }
+  ],
+  "webLinks": ["https://jwt.io/introduction"],
+  "tags": ["auth", "jwt", "backend"],
+  "sessionType": "implementation",
+  "status": "complete"
 }
 ```
 
@@ -262,17 +305,18 @@ Claude Code は意味のある変化があった時にセッションJSONを更
 
 | トリガー | 更新内容 |
 |---------|---------|
-| セッションの目的が明確になった | `title`, `goal`, `sessionType` |
-| ユーザーの指示に対応した | `interactions` に追加 |
-| 技術的決定を下した | `proposals`, `choice`, `reasoning` |
-| エラーに遭遇・解決した | `problem`, `choice`, `reasoning` |
-| ファイルを変更した | `actions`, `filesModified` |
+| セッションの目的が明確になった | `summary.title`, `summary.goal`, `sessionType` |
+| ファイルを変更した | `files` に追加、`metrics` 更新 |
+| 技術的決定を下した | `decisions` に追加 |
+| エラーに遭遇・解決した | `errors` に追加 |
 | URLを参照した | `webLinks` |
 | 新しいキーワードが出現 | `tags`（tags.jsonを参照） |
 
+**注意**: 明示的に `/memoria:save` を実行するか、APIフォールバックが発動するまでセッションは保存されません。
+
 ### セッションタイプ
 
-`sessionType` フィールドはセッションの種類を分類します。interactions が空でも**必ず設定**してください。
+`sessionType` フィールドはセッションの種類を分類します。
 
 | タイプ | 説明 |
 |--------|------|

package/README.md

@@ -2,12 +2,13 @@
 
 Long-term memory plugin for Claude Code
 
-Provides automatic session saving, technical decision recording, and web dashboard management.
+Provides explicit session saving with API fallback, technical decision recording, and web dashboard management.
 
 ## Features
 
 ### Core Features
-- **Real-time Session Updates**: Session JSON is updated when meaningful changes occur
+- **Explicit Session Saving**: Save with `/memoria:save` or "save session" request
+- **API Fallback**: Auto-save via OpenAI API before Auto-Compact and at session end
 - **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`
@@ -95,22 +96,47 @@ Restart Claude Code.
 
 This will auto-update on Claude Code startup.
 
+## Configuration (Optional)
+
+To enable API fallback for automatic session saving, run `/memoria:init` or manually create `~/.claude/memoria.json`:
+
+```json
+{
+  "openai_api_key": "sk-...",
+  "model": "gpt-5-mini"
+}
+```
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `openai_api_key` | No | - | Enables auto-save at PreCompact/SessionEnd |
+| `model` | No | `gpt-5-mini` | Model to use (gpt-5-mini, gpt-5, gpt-5.2, etc.) |
+
+**Without `openai_api_key`**: Sessions are only saved when you explicitly use `/memoria:save`.
+
+**With `openai_api_key`**: Auto-save is enabled. Sessions are automatically saved:
+- Before Auto-Compact (status: `draft`)
+- At session end (status: `complete`)
+
 ## Usage
 
-### Automatic Behavior
+### Session Saving
 
-| Timing | Action |
-|--------|--------|
-| Session Start | Suggest related sessions, initialize session JSON |
-| During Session | Claude Code updates session JSON on meaningful changes |
-| Session End | Log completion |
+| Method | When | Status |
+|--------|------|--------|
+| **Explicit** | `/memoria:save` or "save session" | `complete` |
+| **PreCompact** | Before Auto-Compact (API) | `draft` |
+| **SessionEnd** | Session end (API) | `complete` |
+
+**Note**: PreCompact/SessionEnd API fallback requires `~/.claude/memoria.json` configuration.
 
 ### Commands
 
 | Command | Description |
 |---------|-------------|
+| `/memoria:init` | Initialize config file (`~/.claude/memoria.json`) |
 | `/memoria:resume [id]` | Resume session (show list if ID omitted) |
-| `/memoria:save` | Force flush current session |
+| `/memoria:save` | Save session + extract rules from conversation |
 | `/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) |
@@ -217,42 +243,59 @@ 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).
+Sessions use an **analysis-friendly** schema. Quantitative data (metrics) and qualitative data (summary) are separated, with files/decisions/errors as independent arrays for easy aggregation.
 
 ```json
 {
-  "id": "2026-01-27_abc123",
+  "id": "abc12345",
   "sessionId": "full-uuid-from-claude-code",
   "createdAt": "2026-01-27T10:00:00Z",
+  "endedAt": "2026-01-27T12: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"],
-  "sessionType": "implementation",
-  "interactions": [
+  "summary": {
+    "title": "JWT authentication implementation",
+    "goal": "Implement JWT-based auth with refresh token support",
+    "outcome": "success",
+    "description": "Implemented JWT auth with RS256 signing"
+  },
+  "metrics": {
+    "durationMinutes": 120,
+    "filesCreated": 2,
+    "filesModified": 1,
+    "decisionsCount": 2,
+    "errorsEncountered": 1,
+    "errorsResolved": 1
+  },
+  "files": [
+    { "path": "src/auth/jwt.ts", "action": "create", "summary": "JWT module" }
+  ],
+  "decisions": [
     {
-      "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" }
-      ],
+      "id": "dec-001",
+      "topic": "Auth method",
       "choice": "JWT",
+      "alternatives": ["Session Cookie"],
       "reasoning": "Easy auth sharing between microservices",
-      "actions": [
-        { "type": "create", "path": "src/auth/jwt.ts", "summary": "JWT module" }
-      ],
-      "filesModified": ["src/auth/jwt.ts"]
+      "timestamp": "2026-01-27T10:15:00Z"
     }
-  ]
+  ],
+  "errors": [
+    {
+      "id": "err-001",
+      "message": "secretOrPrivateKey must be asymmetric",
+      "type": "runtime",
+      "resolved": true,
+      "solution": "Changed to PEM format for RS256"
+    }
+  ],
+  "webLinks": ["https://jwt.io/introduction"],
+  "tags": ["auth", "jwt", "backend"],
+  "sessionType": "implementation",
+  "status": "complete"
 }
 ```
 
@@ -262,17 +305,16 @@ Claude Code updates session JSON when meaningful changes occur:
 
 | Trigger | Update |
 |---------|--------|
-| Session purpose becomes clear | `title`, `goal`, `sessionType` |
-| User instruction handled | Add to `interactions` |
-| Technical decision made | `proposals`, `choice`, `reasoning` |
-| Error encountered/resolved | `problem`, `choice`, `reasoning` |
-| File modified | `actions`, `filesModified` |
+| Session purpose becomes clear | `summary.title`, `summary.goal`, `sessionType` |
+| File modified | Add to `files`, update `metrics` |
+| Technical decision made | Add to `decisions` |
+| Error encountered/resolved | Add to `errors` |
 | URL referenced | `webLinks` |
 | New keyword appears | `tags` (reference tags.json) |
 
 ### Session Types
 
-The `sessionType` field classifies the session type. **Always set this** even if interactions is empty.
+The `sessionType` field classifies the session type.
 
 | Type | Description |
 |------|-------------|

package/hooks/hooks.json

@@ -11,6 +11,17 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.sh"
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": "",

package/hooks/pre-compact.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+#
+# pre-compact.sh - PreCompact hook for memoria plugin
+#
+# Triggered before auto-compact. If session JSON is empty (template state),
+# uses OpenAI API to summarize transcript and save as draft.
+#
+# Input (stdin): JSON with session_id, transcript_path, cwd, trigger
+# Output: JSON with continue (boolean)
+#
+# Requires: ~/.claude/memoria.json with openai_api_key
+
+set -euo pipefail
+
+# Read stdin
+input_json=$(cat)
+
+# Extract fields
+session_id=$(echo "$input_json" | jq -r '.session_id // empty')
+transcript_path=$(echo "$input_json" | jq -r '.transcript_path // empty')
+cwd=$(echo "$input_json" | jq -r '.cwd // empty')
+trigger=$(echo "$input_json" | jq -r '.trigger // "auto"')
+
+# Only process auto-trigger
+if [ "$trigger" != "auto" ]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# If no cwd, use PWD
+if [ -z "$cwd" ]; then
+  cwd="${PWD}"
+fi
+
+# Find session file
+if [ -z "$session_id" ]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+session_short_id="${session_id:0:8}"
+memoria_dir="${cwd}/.memoria"
+sessions_dir="${memoria_dir}/sessions"
+
+# Find session file (new format first, then old format for backwards compatibility)
+session_file=$(find "$sessions_dir" -name "${session_short_id}.json" -type f 2>/dev/null | head -1)
+if [ -z "$session_file" ]; then
+  session_file=$(find "$sessions_dir" -name "*_${session_short_id}.json" -type f 2>/dev/null | head -1)
+fi
+
+if [ -z "$session_file" ] || [ ! -f "$session_file" ]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Check if session needs saving (template state)
+title=$(jq -r '.summary.title // ""' "$session_file")
+files_count=$(jq -r '.files | length' "$session_file")
+status=$(jq -r '.status // "null"' "$session_file")
+
+# Skip if already saved
+if [ "$status" = "complete" ] || [ "$status" = "draft" ]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Skip if already has content
+if [ -n "$title" ] && [ "$files_count" -gt 0 ]; then
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Check for API key in ~/.claude/memoria.json
+config_file="${HOME}/.claude/memoria.json"
+if [ ! -f "$config_file" ]; then
+  echo "[memoria] No config file found at ${config_file}, skipping auto-save" >&2
+  echo '{"continue": true}'
+  exit 0
+fi
+
+api_key=$(jq -r '.openai_api_key // empty' "$config_file")
+if [ -z "$api_key" ]; then
+  echo "[memoria] No openai_api_key in config, skipping auto-save" >&2
+  echo '{"continue": true}'
+  exit 0
+fi
+
+model=$(jq -r '.model // "gpt-5-mini"' "$config_file")
+
+# Check transcript exists
+if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
+  echo "[memoria] No transcript found, skipping auto-save" >&2
+  echo '{"continue": true}'
+  exit 0
+fi
+
+# Run summarization in background (don't block compaction)
+(
+  # Read transcript (JSONL format) - extract user messages, assistant text, and tool usage
+  transcript_content=$(cat "$transcript_path" | jq -r '
+    select(.type == "user" or .type == "assistant") |
+    if .type == "user" then
+      if (.message.content | type) == "string" then
+        "User: " + .message.content
+      else
+        empty
+      end
+    elif .type == "assistant" then
+      .message.content[]? |
+      if .type == "text" then
+        "Assistant: " + .text
+      elif .type == "tool_use" then
+        "Tool: " + .name + (if .input.file_path then " - " + .input.file_path elif .input.command then " - " + (.input.command | split("\n")[0]) else "" end)
+      else
+        empty
+      end
+    else
+      empty
+    end
+  ' 2>/dev/null)
+
+  if [ -z "$transcript_content" ]; then
+    echo "[memoria] Empty transcript, skipping" >&2
+    exit 0
+  fi
+
+  # Get git branch
+  branch=$(jq -r '.context.branch // ""' "$session_file")
+
+  # Prepare prompt for summarization (analysis-friendly structure)
+  prompt="Summarize this Claude Code session as JSON with analysis-friendly structure. Extract:
+
+1. summary: {
+   title: Brief title (max 50 chars),
+   goal: What the user wanted to accomplish,
+   outcome: \"success\" | \"partial\" | \"abandoned\",
+   description: Brief summary (1-2 sentences)
+}
+
+2. metrics: {
+   durationMinutes: estimated session duration,
+   filesCreated: count,
+   filesModified: count,
+   filesDeleted: count,
+   decisionsCount: count,
+   errorsEncountered: count,
+   errorsResolved: count
+}
+
+3. files: Array of file changes, each with:
+   - path: file path
+   - action: \"create\" | \"edit\" | \"delete\"
+   - summary: what was changed
+
+4. decisions: Array of technical decisions, each with:
+   - id: dec-001, dec-002, etc.
+   - topic: decision topic
+   - choice: what was chosen
+   - alternatives: array of other options considered
+   - reasoning: why this choice
+   - timestamp: ISO8601
+
+5. errors: Array of errors encountered, each with:
+   - id: err-001, err-002, etc.
+   - message: error message
+   - type: \"runtime\" | \"build\" | \"lint\" | \"test\" | \"other\"
+   - file: related file (if any)
+   - resolved: true/false
+   - solution: how it was fixed (if resolved)
+   - timestamp: ISO8601
+
+6. webLinks: Array of URLs referenced
+7. tags: Array of relevant tags (e.g., frontend, backend, auth)
+8. sessionType: One of: decision, implementation, research, exploration, discussion, debug, review
+
+Return ONLY valid JSON, no markdown or explanation.
+
+Transcript:
+${transcript_content}"
+
+  # Call OpenAI API
+  response=$(curl -s -X POST "https://api.openai.com/v1/chat/completions" \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer ${api_key}" \
+    -d "$(jq -n \
+      --arg model "$model" \
+      --arg prompt "$prompt" \
+      '{
+        model: $model,
+        messages: [
+          {role: "system", content: "You are a session summarizer. Return only valid JSON."},
+          {role: "user", content: $prompt}
+        ],
+        temperature: 0.3,
+        max_tokens: 10000
+      }')" 2>/dev/null)
+
+  # Extract content from response
+  summary=$(echo "$response" | jq -r '.choices[0].message.content // empty' 2>/dev/null)
+
+  if [ -z "$summary" ]; then
+    echo "[memoria] API call failed or empty response" >&2
+    exit 0
+  fi
+
+  # Parse and validate JSON
+  if ! echo "$summary" | jq -e . >/dev/null 2>&1; then
+    # Try to extract JSON from markdown code block
+    summary=$(echo "$summary" | sed -n '/^```json/,/^```$/p' | sed '1d;$d')
+    if ! echo "$summary" | jq -e . >/dev/null 2>&1; then
+      echo "[memoria] Invalid JSON response from API" >&2
+      exit 0
+    fi
+  fi
+
+  # Update session file with summary (analysis-friendly structure)
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  jq --argjson summary "$summary" --arg status "draft" --arg updatedAt "$now" '
+    .summary = ($summary.summary // .summary) |
+    .metrics = ($summary.metrics // .metrics) |
+    .files = ($summary.files // .files) |
+    .decisions = ($summary.decisions // .decisions) |
+    .errors = ($summary.errors // .errors) |
+    .webLinks = ($summary.webLinks // .webLinks) |
+    .tags = ($summary.tags // .tags) |
+    .sessionType = ($summary.sessionType // .sessionType) |
+    .status = $status |
+    .updatedAt = $updatedAt
+  ' "$session_file" > "${session_file}.tmp" && mv "${session_file}.tmp" "$session_file"
+
+  echo "[memoria] Session saved as draft: ${session_file}" >&2
+
+) &
+
+# Return immediately (don't block compaction)
+echo '{"continue": true}'