timeline-report

タイムラインレポート

claude-mem の永続的なメモリタイムラインを使用して、プロジェクトの開発履歴全体を包括的に分析した物語を生成します。

使用する場面

ユーザーから次のように依頼された場合に使用します。

• 「タイムラインレポートを書いて」
• 「[project] の歩みをたどって」
• 「プロジェクトの履歴を分析して」
• 「プロジェクト全体のレポートを作成して」
• 「開発履歴全体を要約して」
• 「このプロジェクトの経緯を教えて」

前提条件

claude-mem ワーカーが実行中である必要があります。プロジェクトの claude-mem の観察記録が保存されている必要があります。

ワーカーのポートを解決する（最初に一度だけ実行し、以下のすべての curl 呼び出しで $WORKER_PORT を再利用してください）。

WORKER_PORT="${CLAUDE_MEM_WORKER_PORT:-$(node -e "const fs=require('fs'),p=require('path'),os=require('os');const uid=(typeof process.getuid==='function'?process.getuid():77);const fallback=String(37700+(uid%100));try{const s=JSON.parse(fs.readFileSync(p.join(os.homedir(),'.claude-mem','settings.json'),'utf-8'));process.stdout.write(String(s.CLAUDE_MEM_WORKER_PORT||fallback));}catch{process.stdout.write(fallback);}" 2>/dev/null)}"

この処理では、CLAUDE_MEM_WORKER_PORT 環境変数、次に ~/.claude-mem/settings.json を参照し、どちらも設定されていない場合は UID ごとのデフォルト値 37700 + (uid % 100) を使用します。これはワーカー自身がポートを選択する方法と一致しています。複数アカウントのセットアップ（#2101）や、デフォルトのポートを変更したユーザー（#2103）では必須です。

ワークフロー

ステップ 1：プロジェクト名を特定する

文脈から明らかでない場合は、分析対象のプロジェクトをユーザーに尋ねます。通常、プロジェクト名はプロジェクトのディレクトリ名です（例：「tokyo」、「my-app」）。ユーザーが「このプロジェクト」と言った場合は、現在の作業ディレクトリのベース名を使用します。

ワークツリーの検出： ディレクトリのベース名を使う前に、現在のディレクトリが git ワークツリーかどうかを確認します。ワークツリーの場合、データソースはワークツリーディレクトリ自体ではなく、親プロジェクトです。次を実行します。

git_dir=$(git rev-parse --git-dir 2>/dev/null)
git_common_dir=$(git rev-parse --git-common-dir 2>/dev/null)
if [ "$git_dir" != "$git_common_dir" ]; then
  # We're in a worktree — resolve the parent project name
  parent_project=$(basename "$(dirname "$git_common_dir")")
  echo "Worktree detected. Parent project: $parent_project"
else
  parent_project=$(basename "$PWD")
fi
echo "$parent_project"

ワークツリーが検出された場合は、すべての API 呼び出しで親リポジトリのベース名である $parent_project をプロジェクト名として使用します。ユーザーには「git ワークツリーを検出しました。データソースとして親プロジェクト「[name]」を使用します。」と伝えます。

ステップ 2：タイムライン全体を取得する

Bash を使用して、claude-mem ワーカー API から完全なタイムラインを取得します。

curl -s "http://localhost:${WORKER_PORT}/api/context/inject?project=PROJECT_NAME&full=true"

これにより、プロジェクトの履歴全体にわたるすべての観察記録、セッションの境界、要約を含む、圧縮されたタイムライン全体が返されます。レスポンスは LLM での利用に最適化された、あらかじめフォーマット済みの Markdown です。

トークン数の目安： タイムライン全体のサイズは、プロジェクトの履歴によって異なります。

• 小規模なプロジェクト（観察記録が 1,000 件未満）：約 20～50K トークン
• 中規模なプロジェクト（観察記録が 1,000～10,000 件）：約 50～300K トークン
• 大規模なプロジェクト（観察記録が 10,000～35,000 件）：約 300～750K トークン

レスポンスが空、またはエラーが返された場合、ワーカーが実行されていないか、プロジェクト名が間違っている可能性があります。curl -s "http://localhost:${WORKER_PORT}/api/search?query=*&limit=1" を試して、ワーカーが正常に動作しているか確認してください。

ステップ 3：トークン数を推定する

続行する前に、取得したタイムラインのトークン数を推定します（文字数 4 文字あたり約 1 トークン）。その数をユーザーに伝えます。

Timeline fetched: ~X observations, estimated ~Yk tokens.
This analysis will consume approximately Yk input tokens + ~5-10k output tokens.
Proceed? (y/n)

タイムラインが 100K トークンを超える場合は、続行する前にユーザーの確認を待ちます。

ステップ 4：サブエージェントで分析する

完全なタイムラインと以下の分析プロンプトを指定して、Agent（Task ツールを使用）を起動します。タイムライン全体をエージェントのコンテキストとして渡します。また、「トークンエコノミクス」セクションについて調べるため、~/.claude-mem/claude-mem.db の SQLite データベースも照会するようエージェントに指示してください。

エージェントプロンプト：

You are a technical historian analyzing a software project's complete development timeline from claude-mem's persistent memory system. The timeline below contains every observation, session boundary, and summary recorded across the project's entire history.

You also have access to the claude-mem SQLite database at ~/.claude-mem/claude-mem.db. Use it to run queries for the Token Economics & Memory ROI section. The database has an "observations" table with columns: id, memory_session_id, project, text, type, title, subtitle, facts, narrative, concepts, files_read, files_modified, prompt_number, discovery_tokens, created_at, created_at_epoch, content_hash, generated_by_model, relevance_count, merged_into_project, agent_type, agent_id, metadata.

Write a comprehensive narrative report titled "Journey Into [PROJECT_NAME]" that covers:

## Required Sections

1. **Project Genesis** -- When and how the project started. What were the first commits, the initial vision, the founding technical decisions? What problem was being solved?

2. **Architectural Evolution** -- How did the architecture change over time? What were the major pivots? Why did they happen? Trace the evolution from initial design through each significant restructuring.

3. **Key Breakthroughs** -- Identify the "aha" moments: when a difficult problem was finally solved, when a new approach unlocked progress, when a prototype first worked. These are the observations where the tone shifts from investigation to resolution.

4. **Work Patterns** -- Analyze the rhythm of development. Identify debugging cycles (clusters of bug fixes), feature sprints (rapid observation sequences), refactoring phases (architectural changes without new features), and exploration phases (many discoveries without changes).

5. **Technical Debt** -- Track where shortcuts were taken and when they were paid back. Identify patterns of accumulation (rapid feature work) and resolution (dedicated refactoring sessions).

6. **Challenges and Debugging Sagas** -- The hardest problems encountered. Multi-session debugging efforts, architectural dead-ends that required backtracking, platform-specific issues that took days to resolve.

7. **Memory and Continuity** -- How did persistent memory (claude-mem itself, if applicable) affect the development process? Were there moments where recalled context from prior sessions saved significant time or prevented repeated mistakes?

8. **Token Economics & Memory ROI** -- Quantitative analysis of how memory recall saved work:
   - Query the database directly for these metrics using `sqlite3 ~/.claude-mem/claude-mem.db`
   - Count total discovery_tokens across all observations (the original cost of all work)
   - Count sessions that had context injection available (sessions after the first)
   - Calculate the compression ratio: average discovery_tokens vs average read_tokens per observation
   - Identify the highest-value observations (highest discovery_tokens -- these are the most expensive decisions, bugs, and discoveries that memory prevents re-doing)
   - Identify explicit recall events (observations where narrative mentions "recalled", "from memory", "previous session")
   - Estimate passive recall savings: each session with context injection receives ~50 observations. Use a 30% relevance factor (conservative estimate that 30% of injected context prevents re-work). Savings = sessions_with_context × avg_discovery_value_of_50_obs_window × 0.30
   - Estimate explicit recall savings: ~10K tokens per explicit recall query
   - Calculate net ROI: total_savings / total_read_tokens_invested
   - Present as a table with monthly breakdown
   - Highlight the top 5 most expensive observations by discovery_tokens -- these represent the highest-value memories in the system (architecture decisions, hard bugs, implementation plans that cost 100K+ tokens to produce originally)

   Use these SQL queries as a starting point:
   ```sql
   -- Total discovery tokens
   SELECT SUM(discovery_tokens) FROM observations WHERE project = 'PROJECT_NAME';

   -- Sessions with context available (not the first session)
   SELECT COUNT(DISTINCT memory_session_id) FROM observations WHERE project = 'PROJECT_NAME';

   -- Average tokens per observation
   SELECT AVG(discovery_tokens) as avg_discovery, AVG(LENGTH(title || COALESCE(subtitle,'') || COALESCE(narrative,'') || COALESCE(facts,'')) / 4) as avg_read FROM observations WHERE project = 'PROJECT_NAME' AND discovery_tokens > 0;

   -- Top 5 most expensive observations (highest-value memories)
   SELECT id, title, discovery_tokens FROM observations WHERE project = 'PROJECT_NAME' ORDER BY discovery_tokens DESC LIMIT 5;

   -- Monthly breakdown
   SELECT strftime('%Y-%m', created_at) as month, COUNT(*) as obs, SUM(discovery_tokens) as total_discovery, COUNT(DISTINCT memory_session_id) as sessions FROM observations WHERE project = 'PROJECT_NAME' GROUP BY month ORDER BY month;

   -- Explicit recall events
   SELECT COUNT(*) FROM observations WHERE project = 'PROJECT_NAME' AND (narrative LIKE '%recalled%' OR narrative LIKE '%from memory%' OR narrative LIKE '%previous session%');

9. タイムライン統計 — 定量的な要約：

   • 期間（最初の観察記録から最後の観察記録まで）
   • 観察記録とセッションの総数
   • 観察記録の種類別内訳（機能、バグ修正、発見、決定、変更）
   • 最も活発だった日や週
   • 最長のデバッグセッション

10. 教訓とメタ観察 — 履歴全体からどのようなパターンが見えてくるでしょうか？ タイムラインを読んだ新しい開発者は、このコードベースについて何を学ぶでしょうか？ 開発を導いた繰り返し現れるテーマや原則は何でしょうか？

執筆スタイル

• 箇条書きではなく、技術的な物語として記述してください
• 出来事に言及する際は、具体的な観察 ID とタイムスタンプを使用してください（例：「12月14日（#26766）に、根本原因がついに特定されました……」）
• 時系列で出来事を結び付け、初期の決定が後にどのような結果をもたらしたかを示してください
• 成功だけでなく、苦労や行き詰まりについても率直に記述してください
• プロジェクトの規模に応じて、3,000～6,000 語を目安にしてください
• 必要に応じて、見出し、強調、コードへの参照を使った Markdown 形式で記述してください

重要

• プロジェクトのタイムライン全体を時系列で分析してください。初期の経緯も省略しないでください
• 物語の展開を見つけてください。問題から調査、解決へとたどってください
• プロジェクトの方向性が根本的に変わった転換点を特定してください
• ツール、ワークフロー、コラボレーションのパターンなど、開発プロセス自体に関する気づきも記述してください

プロジェクトの完全なタイムラインは次のとおりです。

[TIMELINE CONTENT GOES HERE]

### Step 5: Save the Report

Save the agent's output as a markdown file. Default location:

./journey-into-PROJECT_NAME.md

Or if the user specified a different output path, use that instead.

### Step 6: Report Completion

Tell the user:
- Where the report was saved
- The approximate token cost (input timeline + output report)
- The date range covered
- Number of observations analyzed

## Error Handling

- **Empty timeline:** "No observations found for project 'X'. Check the project name with: `curl -s \"http://localhost:${WORKER_PORT}/api/search?query=*&limit=1\"`"
- **Worker not running:** "The claude-mem worker is not responding on port ${WORKER_PORT}. Start it with your usual method or check `ps aux | grep worker-service`."
- **Timeline too large:** For projects with 50,000+ observations, the timeline may exceed context limits. Suggest using date range filtering: `curl -s "http://localhost:${WORKER_PORT}/api/context/inject?project=X&full=true"` -- the current endpoint returns all observations; for extremely large projects, the user may want to analyze in time-windowed segments.

## Example

User: "Write a journey report for the tokyo project"

1. Fetch: `curl -s "http://localhost:${WORKER_PORT}/api/context/inject?project=tokyo&full=true"`
2. Estimate: "Timeline fetched: ~34,722 observations, estimated ~718K tokens. Proceed?"
3. User confirms
4. Deploy analysis agent with full timeline
5. Save to `./journey-into-tokyo.md`
6. Report: "Report saved. Analyzed 34,722 observations spanning Oct 2025 - Mar 2026 (~718K input tokens, ~8K output tokens)."