memory

Memory - 読み取りとアクセスの操作

検索、読み込み、同期、履歴、可視化のサブコマンドを備えた、読み取り側のメモリスキルを統合したものです。

セッションをまたぐ読み取り戦略（Opus 5.5 / CC 2.1.111+）： Opus 5.5 は、セッションをまたいでもファイルシステム上のメモリを確実に読み取れます。セッション開始時にコンテキストを読み込む際は、次の階層的な読み取り順を優先してください。

1. ~/.claude/projects/<slug>/memory/MEMORY.md（永続的なインデックス — 最初に、必ず読み込む）
2. .claude/chain/state.json と最新の NN-*.json 引き継ぎファイル（セッションの継続）
3. ファイルシステムのインデックスで答えが得られない場合は、MCP mcp__memory__search_nodes（型付きグラフのトラバーサル）

レイヤー 1 は低コスト（小さなインデックスファイル）、レイヤー 2 は対象を限定（セッション固有）、レイヤー 3 は選択的（必要な場合のみ）です。ナレッジグラフ全体をコンテキストにダンプするのは避け、まずインデックスを使って検索範囲を絞り込んでください。

引数の解決

SUBCOMMAND = "$ARGUMENTS[0]"  # First token: search, load, history, viz, status
QUERY = "$ARGUMENTS[1]"       # Second token onward: search query or flags
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

使用方法

memory search <query>  # Search knowledge graph
memory load             # Load context at session start
memory history          # View decision timeline
memory viz              # Visualize knowledge graph
memory status           # Show memory system health

---

重要：サブコマンドがない場合は AskUserQuestion を使用

サブコマンドを指定せずに呼び出された場合は、何をしたいかユーザーに尋ねてください。

AskUserQuestion(
  questions=[{
    "question": "What memory operation do you need?",
    "header": "Operation",
    "options": [
      {"label": "search", "description": "Search decisions and patterns in knowledge graph"},
      {"label": "load", "description": "Load relevant context for this session"},
      {"label": "history", "description": "Decision timeline + knowledge-graph viz (--mermaid)"},
      {"label": "status", "description": "Check memory system health"}
    ],
    "multiSelect": false
  }]
)

---

サブコマンド

詳細を読み込むには、各サブコマンドの完全な使用方法、フラグ、出力形式、コンテキストに応じた結果の上限が記載されている Read("references/memory-commands.md") を参照してください。

サブコマンド	目的
search	過去の決定、パターン、エンティティを検索します。--category（metadata.category に対応）、--limit、--agent（agent_id で範囲を限定）、--global フィルターフラグをサポートします
load	セッション開始時に関連するメモリを自動で読み込みます。--project、--global をサポートします
history	表、Mermaid、JSON 形式で決定のタイムラインを出力します。--since、--mermaid をサポートします
viz	ナレッジグラフを Mermaid 図として描画します。Read("references/mermaid-patterns.md") も参照してください
status	メモリシステムのヘルスチェック

---

定期スキャン（cron）

毎晩の KG 陳腐化レポート

.github/workflows/memory-staleness.yml の cron ジョブが、毎晩 04:00 UTC に実行されます。scripts/staleness_cron.py を呼び出して、すべてのメモリ MCP エンティティをスキャンし、最新の観測タイムスタンプが 30 日より前のものを特定して、Markdown レポートを docs/reports/memory-staleness-YYYY-MM-DD.md に書き込みます。

python3 ${CLAUDE_SKILL_DIR}/scripts/staleness_cron.py docs/reports/ \
    --threshold-days 30 --limit 50

自動スキップ条件（すべて終了コード 0、すべて WARN ログに記録）：

スキップ理由	条件
yg-mcp-core not importable	yg-mcp-core>=0.3.0 がインストールされていない（orchestkit は公開されていますが、yg-mcp-core は非公開の pypi.yonyon.ai にあり、HQ 専用です）
memory MCP unreachable	memory MCP サーバーが停止している、または .mcp.json で memory が定義されていない

レポートの内容：

• エンティティの合計数／陳腐化数／最新数
• 陳腐化の度合いで並べ替えた、陳腐化したエントリの上位 N 件（タイムスタンプなしを最初に、その後は古いものから新しいものへ）
• 各行：名前、entityType、経過日数、観測数
• 経過日数の区分ごとの推奨アクション（>90d はレビュー、>180d はアーカイブ候補）

タイムスタンプを解析できないエンティティは陳腐化として扱います。適切な対応は、運用担当者が介入することです（last_read 観測を追記するか、削除してください）。

ユニットテスト可能な純粋関数（parse_iso_timestamp、latest_observation_timestamp、is_stale、build_report_payload、render_markdown）は、同じディレクトリの staleness_lib.py にあります。

Yonatan-HQ/hq-ext-plugin#194（audio_podcast）および orchestkit#1886（post-synth podcast）と #1887（memory writeback）のパターンを反映しています。Yonatan-HQ/core#993（yg-mcp-core 0.3.0）によってブロックが解除されました。

---

ワークフロー

1. サブコマンドを解析する

Extract first argument as subcommand
If no subcommand -> AskUserQuestion
Validate subcommand is one of: search, load, history, viz, status
Parse remaining flags
Check for --agent <agent-id> flag → agent_id: "ork:{agent-id}"

2. サブコマンドを実行する

サブコマンドに基づいて、適切なハンドラーに処理を振り分けます。

3. 結果を報告する

操作に適した形式で出力します。

---

ルール早見表

ルール	影響	対象
entity-extraction-patterns（rules/entity-extraction-patterns.md を読み込む）	高	エンティティタイプ、関係タイプ、グラフクエリのセマンティクス
deduplication-strategy（rules/deduplication-strategy.md を読み込む）	高	Edit-over-Write パターン、アンカーに基づく挿入、検証

---

セッションの再開

詳細を読み込む：CC 2.1.31 の再開時のヒント、終了前のコンテキストの記録、PR・issue・実装の再開ワークフローについては、Read("references/session-resume-patterns.md") を参照してください。

---

関連スキル

• ork:remember - 決定事項とパターンを保存する（書き込み側）

---

エラー処理

• viz 用のグラフが空の場合：remember の使用方法を説明するメッセージを表示する
• サブコマンドが無効な場合：使用方法のヘルプを表示する
• メモリファイルが破損している場合：破損を報告し、修復を提案する
• 検索クエリが空の場合：代わりに最近のエンティティを表示する
• 検索結果がない場合：代替案を提案する