How I Use My AI Session History

Step-by-step example of the tool I use, how I use the UI, and how I use it agentically.

I forget why I built things the way I did.

Decisions and dead-ends live in my head for maybe a week. After that, they’re gone. Buried in Slack threads. Lost in git commits that say “refactor auth flow.”

New developers ask the same questions I ask myself six months later:

• Why did we build it this way?

• Did we consider other options?

• What were the trade-offs?

I dig through git history and I try to remember my own reasoning. Usually I just guess.

I started using SpecStory to fix this.

It saves and indexes every AI conversation, organized by project. My daily Claude sessions become searchable history.

Three Ways I Query My History

I use it daily. Not for storage. For retrieval.

1. Browse I drill into specific sessions. Conversations collapse, so I can scan fast.

   

2. Search I find every mention of a library or bug. Here I’m searching for “tip-tap.”

   

3. Ask “Why” This is the part that matters. I chat across my entire project history to understand why I made decisions.

   

The “Why” Behind the Code

Normally I access SpecStory through a local agent (often Claude Code).

One of my apps has a complex React editor (TipTap) embedded inside a Python/HTMX application, which looks messy. A new developer would ask the same thing I ask myself six months later:

“Why is this complex React component inside the main repo? Why wasn’t it extracted into its own module?”

Code shows what. It rarely shows why.

My agent can search SpecStory. So I asked:

“Why is tip-tap editor in the repo instead of broken out into its own module?”

It searched my old sessions and found context I’d forgotten:

• Tight Coupling: The editor relies on app-specific authentication APIs.

• High Cost: Extraction would require extensive work.

• Pending Upgrade: We’re waiting for TipTap V3 before refactoring.

• “Good Enough” Architecture: The current “React island” approach is fine/good enough.

  

It also told me what we did instead. We refactored the monolithic file in place to make it more maintainable.

Four things I learned that I couldn’t find in the GitHub repo:

1. We considered extraction seriously.

2. We deliberately chose to keep it coupled.

3. This part of the codebase is historically fragile.

4. We planned a migration for the future (TipTap V3).

That’s institutional memory.

Turning Insight into Action

The analysis also found a missed opportunity: extracting the Markdown converter piece only.

The agent flagged this component as a good candidate for extraction at the time, but the conversation moved on without a decision.

I wanted to raise this with the team, so I asked the agent to create a proposal summarizing the pros, cons, and reasoning.

I got a one-page summary:

• What: A utility to convert TipTap HTML to Markdown.

• Why: Identified as valuable, but skipped for other priorities.

• Pros: Zero coupling, high reuse, low effort.

• Cons: Minimal maintenance for a separate package.

• Plan: A clear 3-step execution strategy.

Vague architectural question to something we can make a decision about.

How It Works

I built this workflow using SpecStory’s API and a simple local setup. Claude Code gets tools to query my project history directly.

The setup:

• CLI Tools: Scripts that call list_projects, list_sessions, and get_session from the SpecStory API.

• Agent Instructions: A CLAUDE.md file that teaches the agent how to use these tools.

The agent fetches context on its own. It sees the project history, filters sessions, and reads transcripts to answer my questions.

The Setup

• Install the SpecStory CLI.

• Run your AI agent through the CLI using specstory run to sync automatically. Or run your agent normally and use specstory sync when you finish.

Conversations save locally in a .specstory directory and to the cloud.

Beyond Code

Before ending I want to briefly cover one more use case I rely on SpecStory for:

Sharing My Work

“Look through the features we shipped this week and write a blog post about them.”

SpecStory captures the reasoning behind each feature which mean the output content has that context. Nobody cares what you did unless they know why it matters. Most people who stumble across your blog or content won’t know why something matters unless you provide that context in your writing.

I get better drafts, faster. Because the “why” is already saved.