Guide · Agent skill
How to use the Timeline Report agent skill (timeline-report)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The timeline-report skill is an agent skill for Claude that writes a long narrative about a project's full development history, titled 'Journey Into [Project]'. It reads the timeline that claude-mem has recorded for that project and turns it into a story covering origins, architecture changes, breakthroughs and debugging efforts. This guide explains what agent skills are, how to install this one, how to ask for a report, and what you need in place first.
Timeline Reportthedotmack/claude-mem · Apache-2.0 Download the skill Quick start
- 1Install claude-mem. Install claude-mem and make sure its local worker is running. The skill cannot run without it.
- 2Record observations. Use claude-mem during your coding sessions so the project has observations in its timeline.
- 3Download the ZIP. Download the timeline-report ZIP from this page.
- 4Unzip the skill. Unzip into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP under Settings → Capabilities → Skills.
- 5Ask for the report. Say something like 'Journey into my-app' or 'Write a timeline report'.
- 6Confirm the token estimate. For timelines over 100K tokens, review the estimate and reply y or n before the analysis runs.
- 7Review the output. Read the narrative and check it against your own memory of the project before sharing it.
What is an agent skill, and what does this one do?
An agent skill is a folder that contains a SKILL.md file with instructions the agent follows when a matching request comes in. The skill tells the agent how to carry out a specific task, and it may include scripts the agent can run.
The timeline-report skill is built on claude-mem, a persistent memory system that records observations from your coding sessions. When you ask for a project history or a 'journey' report, the agent pulls the full recorded timeline for the project from the local claude-mem memory worker. It then has a sub-agent write a narrative covering the project's genesis, architectural evolution, key breakthroughs, work patterns, technical debt, challenges, memory and continuity, and token economics.
What you need before installing
The skill requires claude-mem to already be installed, with its local worker running, and the project must already have claude-mem observations recorded. Without observations there is no timeline to analyze and the report will be empty or fail.
The shell also needs Node.js (used to read the port setting), curl and git. The skill reads the local claude-mem SQLite database at ~/.claude-mem/claude-mem.db for its token economics section.
- claude-mem installed with its local worker running (default per-user port around 37700)
- Node.js
- curl and git available in the shell
- Access to ~/.claude-mem/claude-mem.db
- Project with recorded claude-mem observations
How to install the timeline-report skill
Download the ZIP for this skill from our page. The skill is a single file, SKILL.md, packaged in the ZIP.
For a personal install, unzip it into ~/.claude/skills/. To install it for one project only, unzip it into the project's .claude/skills/ folder. Either way, the skill folder should contain SKILL.md.
If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Single project: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How to trigger the skill with natural requests
You do not need a special command. Ask in plain language, and the agent will match your request to the skill's description. The skill's description covers requests for a timeline report, project history analysis, development journey, or full project report.
If you say 'this project', the agent uses the basename of the current working directory as the project name. If you are inside a git worktree, the agent uses the parent project's name as the data source and tells you so.
- Write a timeline report for this project
- Journey into my-app
- Analyze my project history
- Summarize the entire development history
- What's the story of this project?
What happens when you run it
The agent first resolves the worker port, then fetches the full timeline from the worker's local API. It estimates the token count of the timeline, which is roughly one token per four characters, and reports the observation count and estimated size.
If the timeline is larger than 100K tokens, the agent waits for your confirmation before continuing. Then a sub-agent analyzes the full timeline and writes the report. The sub-agent is also told to query the claude-mem database for the token economics section.
- Small project (under 1,000 observations): roughly 20-50K tokens
- Medium project (1,000-10,000 observations): roughly 50-300K tokens
- Large project (10,000-35,000 observations): roughly 300-750K tokens
Safety notes: scripts and network use
This skill runs scripts and uses the network. The commands it runs call a server on localhost, reading the worker port from the environment variable CLAUDE_MEM_WORKER_PORT, then ~/.claude-mem/settings.json, and falling back to a per-user default. The skill reads the local SQLite database and runs git commands to detect worktrees.
Review SKILL.md before installing if you want to see every command. Be aware that the report draws on session notes, so it may summarize sensitive content. Avoid sharing the output if the history contains material that should stay private.
- Runs shell commands, including node, curl, git and sqlite3
- Calls the local claude-mem worker over localhost
- Reads ~/.claude-mem/claude-mem.db
- Session notes may contain sensitive content that ends up in the report
Tips for better reports
Confirm the project name when it is not obvious, since the skill needs the exact name used in claude-mem. For very large projects, read the token estimate carefully before approving, because the cost can reach hundreds of thousands of tokens.
If the worker does not respond, the skill suggests checking its health with a search query. Make sure the worker is running before you ask.
- Check the project name matches what claude-mem recorded
- Read the token estimate before confirming large analyses
- Start the worker before asking for the report
What people use it for
- Writing a retrospective of a project you have worked on for months
- Giving a team lead a narrative summary of how a codebase evolved
- Reviewing the debugging sagas and architectural pivots in a project's history
- Producing a 'story of this project' from recorded session history
Frequently asked questions
Is the timeline-report skill free?
The source material lists the licence as Apache-2.0 for the claude-mem repository the skill comes from. The source does not state pricing for the skill itself, but running large analyses consumes tokens, so check the estimate before proceeding.
What do I need to install timeline-report?
You need claude-mem installed with its local worker running, Node.js, curl and git in your shell, and access to ~/.claude-mem/claude-mem.db. The project must also have claude-mem observations recorded.
Where do I put the timeline-report skill?
Unzip the ZIP into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
Why does the report say the project is empty or fails?
The skill needs recorded claude-mem observations for the project. If the response is empty or errors, the worker may not be running or the project name may be wrong. The skill suggests running a search query to check the worker is healthy.
Does the skill send my data to the internet?
The skill calls the claude-mem worker on localhost, so the timeline is fetched from your own machine. The skill does use the network, so review SKILL.md if you need to confirm exactly what is contacted.
How does this compare to writing a project history by hand?
The skill automates reading a recorded timeline and drafting a narrative from it, which takes far less time than reading everything yourself. Because it depends on claude-mem observations, it will not produce anything useful for projects without recorded history, and you should still check the output for accuracy.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use timeline-report if you have used claude-mem on a project for a long time and want a narrative retrospective of how it evolved. Pick something else if the project has no claude-mem observations, is very large and cost-sensitive, or holds session notes you would not want summarized into a shareable document.
Download the skill