timeline report

Engineering Community

Skill notes

When to Use

Use when users ask for: "Write a timeline report" "Journey into [project]" "Analyze my project history" "Full project report"

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): 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).

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:

Step 2: Fetch the Full Timeline

Use Bash to fetch the complete timeline from the claude-mem worker API: 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 (< 1,000 observations): ~20-50K tokens Medium project (1,000-10,000 observations): ~50-300K tokens

Step 3: Estimate Token Count

Before proceeding, estimate the token count of the fetched timeline (roughly 1 token per 4 characters). Report this to the user: Wait for user confirmation before continuing if the timeline exceeds 100K tokens.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@thedotmack · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
macOS · Linux · Windows
Runtime requirements
Node.js
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
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:

02
Step 2: Fetch the Full Timeline

Use Bash to fetch the complete timeline from the claude-mem worker API: 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 (< 1,000 observations): ~20-50K tokens Medium project (1,000-10,000 observations): ~50-300K tokens

03
Step 3: Estimate Token Count

Before proceeding, estimate the token count of the fetched timeline (roughly 1 token per 4 characters). Report this to the user: Wait for user confirmation before continuing if the timeline exceeds 100K tokens.

04
Step 4: Analyze with a Subagent

Deploy an Agent (using the Task tool) with the full timeline and the following analysis prompt. Pass the ENTIRE timeline as context to the agent. The agent should also be instructed to query the SQLite database at `~/.claude-mem/claude-mem.db` for the Token Economics section. Agent prompt: -- Total discovery tokens SELECT SUM(discovery_tokens) FROM observations WHERE project = 'PROJECT_NAME'; -- Sessions with context available (not the first session)

05
Step 5: Save the Report

Save the agent's output as a markdown file. Default location: Or if the user specified a different output path, use that instead.

06
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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.