goodvibes-memory

リソース

scripts/
  validate-memory-usage.sh
references/
  schemas.md

GoodVibes Memory Protocol

メモリーシステムは、決定事項、パターン、失敗、好みを構造化された JSON ファイルに記録することで、セッションをまたいだ学習を可能にします。すべてのエージェントは作業を開始する前にメモリーを読み、作業を完了した後に書き込む必要があります。

これが重要な理由

メモリーがない場合：

• エージェントが既知の失敗を繰り返します
• 実証済みのパターンが毎回のセッションで再発見されます
• アーキテクチャ上の決定事項が忘れられたり、守られなかったりします
• プロジェクト固有の好みが反映されません

メモリーがある場合：

• 失敗が防止策とともに記録されます
• パターンが一貫して再利用されます
• 決定事項が今後の作業の指針になります
• 好みによって一貫性が保たれます

ファイル構成

.goodvibes/
|-- memory/           # Structured JSON (machine-readable)
|   |-- decisions.json    # Architectural decisions
|   |-- patterns.json     # Proven approaches
|   |-- failures.json     # Past errors + resolutions
|   |-- preferences.json  # Project conventions
|   +-- index.json        # Index file (optional)
+-- logs/             # Markdown logs (human-readable)
    |-- activity.md       # Completed work log
    |-- decisions.md      # Decision log with context
    +-- errors.md         # Error log with resolution

---

作業を開始する前（読み取りフェーズ）

どのようなタスクを実装する場合も、必ずメモリーファイルを確認してください。キーワード検索を使って、関連する項目を見つけます。

1. failures.json を確認する

目的：既知の失敗を繰り返さないようにします。

方法：

# Use precision_read to read the file
precision_read:
  files:
    - path: .goodvibes/memory/failures.json
  verbosity: standard

# Search for keywords matching your task
# Example keywords: "precision_fetch", "config", "auth", "API", "build"

確認する項目：

• keywords フィールドがタスクに一致する（例：「auth」を検索すると認証関連の失敗が見つかります）
• error フィールドに類似した問題が記載されている
• context フィールドが現在の状況に一致する

見つかった場合：

• resolution を読みます――どのように修正されましたか？
• prevention を読みます――どのように回避できますか？
• 防止策を適用します

2. patterns.json を確認する

目的：新しい方法を考案するのではなく、実証済みのアプローチを使います。

方法：

precision_read:
  files:
    - path: .goodvibes/memory/patterns.json
  verbosity: standard

確認する項目：

• keywords がタスクの種類に一致する
• when_to_use が現在の状況に当てはまる
• name が関連するパターンを示している

見つかった場合：

• description を読みます――どのようなパターンですか？
• example_files を確認します――どこで使われていますか？
• やむを得ない理由がない限り、そのパターンに従います

3. decisions.json を確認する

目的：以前のアーキテクチャ上の決定事項を尊重します。

方法：

precision_read:
  files:
    - path: .goodvibes/memory/decisions.json
  verbosity: standard

確認する項目：

• scope に変更予定のファイルが含まれている
• category が対象の領域に一致する（例：「architecture」「pattern」「library」）
• status が「active」である（「superseded」や「reverted」ではない）

見つかった場合：

• what と why を読み、決定内容を理解します
• タスクが決定事項と矛盾する場合：作業を進める前にオーケストレーターに報告します
• タスクが決定事項に沿う場合：それに従います

4. preferences.json を確認する

目的：プロジェクト固有の規約を適用します。

方法：

precision_read:
  files:
    - path: .goodvibes/memory/preferences.json
  verbosity: standard

確認する項目：

• key が対象の領域に一致する（例：「category.preference_name」）

見つかった場合：

• value の設定を適用します
• reason に記載された根拠を尊重します

検索戦略

手動でのキーワード照合：ファイルを読み、タスクに関連するキーワードを探します。

例：

• タスク：「Clerk を使った認証を追加する」
• 検索するキーワード：auth、clerk、authentication、login、session
• 過去の認証関連の失敗がないか、failures.json を確認します
• 認証パターンがないか、patterns.json を確認します
• 認証ライブラリに関する決定事項がないか、decisions.json を確認します

スコープによる絞り込み：scope に変更予定のファイルが含まれている項目を重点的に確認します。

---

作業完了後（書き込みフェーズ）

タスクの完了、エラーの解決、または決定を行った後は、メモリーに記録します。機械可読形式の JSON と、人が読める形式の Markdown の両方に必ず書き込みます。

書き込むタイミング

状況	書き込み先
タスクがレビューに合格した	activity.md ＋必要に応じて patterns.json／decisions.json
エラーを解決した	errors.md ＋ failures.json
決定を行った	decisions.md ＋ decisions.json
書き込まない	些細な修正、新しいパターンがない場合、決定事項がない場合

タスクのレビュー通過後

1. 必ず activity.md に記録する

形式：

## YYYY-MM-DD: [Brief Title]

**Task**: [What was the goal?]

**Plan**: [Approach taken, or N/A]

**Status**: COMPLETE

**Completed Items**:
- [List of what was accomplished]

**Files Modified**:
- [List of changed files with brief description]

**Review Score**: [X/10]

**Commit**: [commit SHA]

---

2. 必要に応じて patterns.json に追加する（再利用可能なパターンが見つかった場合）

次の場合にのみ追加します：

• 複数のファイルやタスクで再利用できるアプローチである
• 一般的な慣例ではなく、自明ではない
• 特定の問題を効果的に解決できる

スキーマ：

{
  "id": "pat_YYYYMMDD_HHMMSS",
  "name": "PatternNameInPascalCase",
  "description": "What the pattern does and why it works",
  "when_to_use": "Situation where this pattern applies",
  "example_files": ["path/to/file.ts", "another/example.ts"],
  "keywords": ["searchable", "terms"]
}

3. 必要に応じて decisions.json に追加する（アーキテクチャ上の決定を行った場合）

次の場合にのみ追加します：

• 複数のアプローチから選択した
• その決定が今後の作業に影響する
• この単一のタスクを超える範囲に影響する

スキーマ：

{
  "id": "dec_YYYYMMDD_HHMMSS",
  "date": "YYYY-MM-DDTHH:MM:SSZ",
  "category": "library|architecture|pattern|convention",
  "what": "What was decided",
  "why": "Rationale for the decision",
  "scope": ["files/directories affected"],
  "confidence": "high | medium | low",
  "status": "active|superseded|reverted"
}

エラーの解決後

1. 必ず errors.md に記録する

形式：

## YYYY-MM-DD HH:MM - [ERROR_CATEGORY]

**Error**: [Brief description]

**Context**:
- Task: [What were you doing?]
- Agent: [Which agent encountered it?]
- File(s): [Affected files]

**Root Cause**: [Why did it happen?]

**Resolution**: [How was it fixed? Or UNRESOLVED]

**Prevention**: [How to avoid it in the future?]

**Status**: RESOLVED | UNRESOLVED

---

2. 必ず failures.json に追加する（コンテキストをすべて記載）

スキーマ：

{
  "id": "fail_YYYYMMDD_HHMMSS",
  "date": "YYYY-MM-DDTHH:MM:SSZ",
  "error": "Brief error description",
  "context": "What task was being performed",
  "root_cause": "Technical explanation of why it failed",
  "resolution": "How it was fixed (or UNRESOLVED)",
  "prevention": "How to avoid this failure in the future",
  "keywords": ["searchable", "error-related", "terms"]
}

エラーカテゴリ（errors.md 用）：

• TOOL_FAILURE -- 精密ツールまたはネイティブツールの失敗
• AGENT_FAILURE -- エージェントがクラッシュした、またはタスクを完了できなかった
• BUILD_ERROR -- TypeScript のコンパイルまたはビルド手順の失敗
• TEST_FAILURE -- テストスイートの失敗
• VALIDATION_ERROR -- 検証、リンティング、または形式チェックの失敗
• EXTERNAL_ERROR -- API、ネットワーク、依存関係の問題
• UNKNOWN -- エラーカテゴリを特定できなかった

決定後

1. 必ず decisions.md に記録する

形式：

## YYYY-MM-DD: [Decision Title]

**Context**: [What situation required a decision?]

**Options Considered**:
1. **[Option A]**: [Description + trade-offs]
2. **[Option B]**: [Description + trade-offs]

**Decision**: [What was chosen]

**Rationale**: [Why this option was best]

**Implications**: [What this means for future work]

---

2. 必ず decisions.json に追加する

上記の「タスクのレビュー通過後」セクションのスキーマを参照してください。

---

ID 形式

書き込み前に既存のエントリを読む必要がないよう、タイムスタンプベースの ID を使用します：

dec_YYYYMMDD_HHMMSS   # Decisions
pat_YYYYMMDD_HHMMSS   # Patterns
fail_YYYYMMDD_HHMMSS  # Failures
pref_YYYYMMDD_HHMMSS  # Preferences

例：2026-02-15 の 14:30:22 に行った決定の場合、dec_20260215_143022

衝突リスク：2 つのエージェントが同じ秒に同じファイルへ書き込まない限り、無視できる程度です。タイムスタンプで十分な一意性が得られます。

---

初回書き込みの確認

メモリ／ログファイルに初めて書き込む前に、ファイルが存在するか確認します：

JSON ファイルの場合

ファイルが存在しない場合は、空の配列を作成します：

[]

Markdown ファイルの場合

ファイルが存在しない場合は、ヘッダーを付けて作成します：

# [File Name]

Log of [description].

---

最初に precision_read を使用します：

precision_read:
  files:
    - path: .goodvibes/memory/decisions.json
  verbosity: count_only  # Just check existence

exists: false の場合は、追記する前にファイルを作成します。

---

よくある間違い

しないこと

• メモリを読むのを省略しない -- 失敗を繰り返し、決定事項に違反することになります
• 些細な作業を記録しない -- 意味のあるパターン／決定／失敗のみを記録します
• ランダムな ID を使わない -- タイムスタンプベースの ID を使用します（既存のエントリを読む必要はありません）
• 予防策のフィールドを忘れない -- 予防策がない失敗記録は役に立ちません
• JSON のみに記録しない -- 必ず JSON と Markdown の両方に書き込みます
• エントリを重複させない -- パターン／失敗がすでに存在するか確認するため、先にキーワードで検索します

すること

• 最初に failures.json を読む -- 作業を始める前に既知の問題を確認します
• キーワードで検索する -- 手動でのキーワード照合は迅速かつ効果的です
• コンテキストをすべて記載する -- 失敗について、根本原因＋解決策＋予防策を含めます
• タイムスタンプ ID を使う -- 衝突のリスクがなく、既存のエントリを読む必要もありません
• 両方の形式に記録する -- JSON は機械向け、Markdown は人間向けです
• last_updated を更新する -- index.json を変更する際はタイムスタンプを更新します

---

検証

scripts/validate-memory-usage.sh スクリプトを使用して、準拠状況を確認します：

# Validate memory protocol usage
bash plugins/goodvibes/skills/protocol/goodvibes-memory/scripts/validate-memory-usage.sh \
  session-transcript.jsonl \
  .goodvibes/memory/

# Exit code 0 = compliant
# Exit code 1 = violations found

スクリプトでは、次の項目を確認します：

• タスク開始時にメモリファイルを読んでいるか
• タスク完了後にアクティビティを記録しているか
• エラー解決時に失敗を記録しているか
• 再利用可能なアプローチの発見時にパターンを記録しているか

---

クイックリファレンス

読み取りフェーズのチェックリスト

• failures.json を読む -- 類似エラーをキーワード検索する
• patterns.json を読む -- 実証済みのアプローチをキーワード検索する
• decisions.json を読む -- 関連する決定を対象範囲で検索する
• preferences.json を読む -- プロジェクトの規約を適用する

作業フェーズのチェックリスト

• タスク完了後に activity.md に記録する
• 再利用可能なパターンを見つけた場合は patterns.json に追加する
• アーキテクチャ上の決定を行った場合は decisions.json に追加する
• エラーを解決した場合は errors.md と failures.json に記録する
• 選択を行った場合は decisions.md と decisions.json に記録する
• JSON ファイルの last_updated タイムスタンプを更新する
• タイムスタンプベースの ID を使用する（重複を避ける）

---

例

例：認証タスクの開始前に失敗を確認する

# Step 1: Read failures.json
precision_read:
  files:
    - path: .goodvibes/memory/failures.json
  verbosity: standard

# Step 2: Manually search for keywords
# Keywords: "auth", "authentication", "clerk", "oauth", "token"
# Found: fail_20260210_160000 - "Service registry reads empty services"
# Context: OAuth token configuration issue
# Prevention: "Always use nested config format for services"

# Step 3: Apply prevention strategy
# Use nested format when configuring auth service

例：機能の実装後にパターンを記録する

# Step 1: Check if file exists
precision_read:
  files:
    - path: .goodvibes/memory/patterns.json
  verbosity: count_only

# Step 2: Read existing patterns to avoid duplicates
precision_read:
  files:
    - path: .goodvibes/memory/patterns.json
  verbosity: standard

# Step 3: Add new pattern (if not duplicate)
precision_edit:
  files:
    - path: .goodvibes/memory/patterns.json
      operations:
        - type: insert
          search: '"patterns": ['
          content: |
            {
              "id": "pat_20260215_143022",
              "name": "AuthServiceNesting",
              "description": "Auth services require nested config structure",
              "when_to_use": "When configuring auth providers in goodvibes.json",
              "example_files": [".goodvibes/goodvibes.json"],
              "keywords": ["auth", "config", "nested", "services"]
            },

例：エラーの解決を記録する

# Step 1: Log to errors.md
precision_edit:
  files:
    - path: .goodvibes/logs/errors.md
      operations:
        - type: insert_at_line
          line: 1
          content: |
            ## 2026-02-15 14:30 - BUILD_ERROR
            
            **Error**: TypeScript compilation failed with "Cannot find module 'clerk'"
            
            **Context**:
            - Task: Add Clerk authentication
            - Agent: Engineer
            - File(s): src/auth/clerk.ts
            
            **Root Cause**: Missing @clerk/nextjs package in dependencies
            
            **Resolution**: RESOLVED - Added package with `npm install @clerk/nextjs`
            
            **Prevention**: Always check package.json before importing new libraries
            
            **Status**: RESOLVED
            
            ---
            

# Step 2: Add to failures.json
precision_edit:
  files:
    - path: .goodvibes/memory/failures.json
      operations:
        - type: insert
          search: '['
          content: |
            {
              "id": "fail_20260215_143022",
              "date": "2026-02-15T14:30:22Z",
              "error": "TypeScript compilation failed - Cannot find module 'clerk'",
              "context": "Adding Clerk authentication to Next.js app",
              "root_cause": "Missing @clerk/nextjs package in package.json dependencies",
              "resolution": "RESOLVED - Installed package with npm install @clerk/nextjs",
              "prevention": "Before importing from a new package, verify it exists in package.json. Use precision_read to check package.json before adding imports.",
              "keywords": ["typescript", "clerk", "module", "dependency", "package.json", "build-error"]
            },

---

他のスキルとの連携

• precision-mastery：メモリファイルの操作には precision_read/precision_edit を使用します
• error-recovery：エラー復旧の最初の手順として failures.json を確認します
• gather-plan-apply：調査フェーズにメモリの読み取りを含めます
• review-scoring：作業開始前にメモリを参照したかどうかをレビュアーが確認します

---

ファイルの場所

すべてのメモリファイルはプロジェクトルートからの相対パスです。

.goodvibes/
|-- memory/
|   |-- decisions.json
|   |-- patterns.json
|   |-- failures.json
|   +-- preferences.json
+-- logs/
    |-- activity.md
    |-- decisions.md
    +-- errors.md

パスには常に .goodvibes/memory/ と .goodvibes/logs/ を使用してください（プロジェクトルートからの相対パス）。