Timeline Report

Timeline Report

Generate a comprehensive narrative analysis of a project's entire development history using claude-mem's persistent memory timeline.

When to Use

Use when users ask for:

• "Write a timeline report"
• "Journey into [project]"
• "Analyze my project history"
• "Full project report"
• "Summarize the entire development history"
• "What's the story of this project?"

Prerequisites

The claude-mem worker must be running. The project must have claude-mem observations recorded.

Resolve the worker port (do this once at the start and reuse $WORKER_PORT in every curl call below):

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)}"

This honors CLAUDE_MEM_WORKER_PORT env, then ~/.claude-mem/settings.json, then falls back to the per-UID default 37700 + (uid % 100) — matching how the worker itself picks its port. Required for multi-account setups (#2101) and any user who has overridden the default port (#2103).

Workflow

Step 1: Determine the Project Name

Ask the user which project to analyze if not obvious from context. The project name is typically the directory name of the project (e.g., "tokyo", "my-app"). If the user says "this project", use the current working directory's basename.

Worktree Detection: Before using the directory basename, check if the current directory is a git worktree. In a worktree, the data source is the parent project, not the worktree directory itself. Run:

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"

If a worktree is detected, use $parent_project (the basename of the parent repo) as the project name for all API calls. Inform the user: "Detected git worktree. Using parent project '[name]' as the data source."

Step 2: Fetch the Full Timeline

Use Bash to fetch the complete timeline from the claude-mem worker API:

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

This returns the entire compressed timeline -- every observation, session boundary, and summary across the project's full history. The response is pre-formatted markdown optimized for LLM consumption.

Token estimates: The full timeline size depends on the project's history:

• Small project ( 0;

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

-- Monthly breakdown SELECT strftime('%Y-%m', createdat) as month, COUNT(*) as obs, SUM(discoverytokens) as totaldiscovery, COUNT(DISTINCT memorysessionid) as sessions FROM observations WHERE project = 'PROJECTNAME' GROUP BY month ORDER BY month;

-- Explicit recall events SELECT COUNT(*) FROM observations WHERE project = 'PROJECTNAME' AND (sourcetool LIKE '%search%' OR sourcetool LIKE '%timeline%' OR sourcetool LIKE '%get_observations%' OR narrative LIKE '%recalled%' OR narrative LIKE '%from memory%' OR narrative LIKE '%previous session%'); ```

1. Timeline Statistics -- Quantitative summary:

• Date range (first observation to last)
• Total observations and sessions
• Breakdown by observation type (features, bug fixes, discoveries, decisions, changes)
• Most active days/weeks
• Longest debugging sessions

1. Lessons and Meta-Observations -- What patterns emerge from the full history? What would a new developer learn about this codebase from reading the timeline? What recurring themes or principles guided development?

Writing Style

• Write as a technical narrative, not a list of bullet points
• Use specific observation IDs and timestamps when referencing events (e.g., "On Dec 14 (#26766), the root cause was finally identified...")
• Connect events across time -- show how early decisions created later consequences
• Be honest about struggles and dead ends, not just successes
• Target 3,000-6,000 words depending on project size
• Use markdown formatting with headers, emphasis, and code references where appropriate

Important

• Analyze the ENTIRE timeline chronologically -- do not skip early history
• Look for narrative arcs: problem -> investigation -> solution
• Identify turning points where the project's direction fundamentally changed
• Note any observations about the development process itself (tooling, workflow, collaboration patterns)

Here is the complete project timeline:

[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)."

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [thedotmack](https://github.com/thedotmack)
- **Source:** [thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- **License:** Apache-2.0
- **Homepage:** https://claude-mem.ai

Install and usage instructions live in the source repository linked above.