SpecStory: Project Memory for AI Coding Assistants

AI coding assistants are powerful—but they’re also forgetful.
They forget why decisions were made, drift from agreed conventions, and occasionally contradict themselves from one session to the next.

SpecStory tackles this exact problem by turning ephemeral AI conversations into durable project knowledge and, when configured, live rules that guide tools like Cursor and GitHub Copilot to behave more consistently and intelligently.

At its core, SpecStory transforms “chat with AI” into a traceable, auditable, and reusable part of your codebase.

What SpecStory Does (At a High Level)

SpecStory is a developer tool that runs as an extension inside Cursor and VS Code, working alongside the AI assistants you already use.

It:

• Automatically saves each AI coding session—prompts, responses, diffs, and code blocks—as Markdown files inside your project.
• Lets you curate, merge, annotate, and share conversations as public URLs for teammates or reviewers.
• Can derive AI rules from those conversations and keep Cursor and GitHub Copilot aligned with your evolving architectural and coding decisions.

Instead of treating AI output as disposable, SpecStory treats it as project memory.

Saving AI Chat History as Markdown

Every AI interaction is automatically saved as a separate .md file under:

.specstory/history/

Each file captures:

• What you asked
• How the AI responded
• The code or diff that resulted

Because these files live in your repository:

• They’re searchable with standard tools
• They can be reviewed in PRs
• They preserve the why, not just the what

SpecStory also allows you to share selected conversations via secure public URLs, making it easy to explain decisions to teammates or future maintainers.

How History Helps (and Where It Stops)

It’s important to understand the boundary:

• These Markdown history files do not automatically influence Cursor or GitHub Copilot.
• They are documentation and context, not active instructions.

You can still leverage them effectively by:

• Skimming a relevant history file and pasting key constraints into a new prompt.
• Using Cursor’s @ reference feature to pull specific history files into a chat session.

In short:
History is human-controlled context. You decide when the AI should see it.

Making AI Help Automatic with Derived Rules

This is where SpecStory becomes more than just a logging tool.

When you set:

"specstory.derivedRules.enabled": true

SpecStory analyzes your conversations and maintains live rule files for your AI assistants:

• .cursor/rules/derived-rules.mdc for Cursor
• .github/copilot-instructions.md for GitHub Copilot

Using a built-in system prompt, SpecStory:

• Scans conversations for rule-like statements
  (“always use Riverpod”, “never use Bloc”, “controllers must stay thin”)
• Merges them into existing rules
• Resolves conflicts when newer decisions override older ones

The result is a living ruleset that evolves naturally from how you talk to the AI.

Why This Improves Cursor Autocomplete and Chat

Cursor already treats .cursor/rules/*.mdc as first-class guidance for both autocomplete and chat.

With derived rules enabled:

• You don’t manually maintain rules files
• Decisions made during real work automatically shape future suggestions

This leads to AI assistance that:

• Uses your preferred stack and patterns
• Follows naming, folder structure, and architectural conventions
• Respects agreed quality bars (tests, error handling, typing)

Instead of correcting the AI repeatedly, you teach it once—and SpecStory remembers.

How It Works in Cursor

In Cursor, the workflow is straightforward:

1. You work as usual; chats and code diffs are auto-saved.
2. SpecStory stores them in .specstory/history/.
3. With derived rules enabled, those chats update .cursor/rules/derived-rules.mdc.
4. Cursor uses those rules to guide autocomplete and chat.

Older versions of rules are backed up automatically, so you can inspect or roll back changes if needed.

How It Works in VS Code + GitHub Copilot

SpecStory also supports VS Code workflows:

• Copilot Chat conversations are saved to .specstory/history/.
• You can merge, annotate, and share conversations as URLs.
• With derived rules enabled, SpecStory updates .github/copilot-instructions.md.

GitHub Copilot reads this file as repository-level guidance, meaning:

• Suggestions evolve with your decisions
• Instructions stay current without manual edits
• Copilot behaves more like a teammate who remembers past agreements

When to Use History vs. Derived Rules

Think of it this way:

• History is selective, human-driven memory.
• Derived rules are automated, always-on guardrails.

Together, they reduce drift and repetition.

Conclusion: Reliable AI Assistance Starts With Memory

On its own, SpecStory gives AI assistants something they fundamentally lack today: durable memory and alignment, directly inside your editor.

By turning AI chats into versioned project knowledge and deriving live rules from real conversations, SpecStory ensures that tools like Cursor and GitHub Copilot remember what was decided, why it was decided, and how they should behave going forward. The result is AI assistance that is more consistent, more predictable, and far less prone to architectural drift.

When combined with Beads, the impact becomes even stronger. Beads improves AI reasoning by giving AI coding assistants persistent, structured memory across sessions, storing task graphs directly in your Git repository. This allows the AI to retain long-term context, understand dependencies between tasks, and reason more reliably over time. We’ve explored this concept in more detail in a separate article that focuses specifically on how Beads works and why it matters:
Beads AI Memory: A Structured Memory System to Solve Agent Amnesia

Together, SpecStory and Beads move AI assistance beyond short-term chats. Instead of a chatty but unreliable helper, you get an AI assistant that behaves more like a senior teammate—one that remembers past decisions, reasons within clear constraints, and builds on prior work rather than contradicting it.

That’s the real promise of SpecStory — and why pairing it with Beads unlocks even more reliable AI behavior.