context-stash

Persistent Memory for AI Coding Agents

The missing piece in AI-assisted software development: Give AI agents durable memory of why changes were made.

npm install -g context-stash

πŸ˜” The Problem: AI Forgets

  • Reintroduced bugs the AI fixed yesterday
  • Repeated questions about design decisions
  • Breaking changes that ignore constraints
  • Lost context between sessions and models

✨ The Solution: A Reasoning Ledger

  • Persistent memory that survives sessions
  • Cross-file references for shared context
  • Human-readable Markdown format
  • Works with any MCP-compatible AI agent

How It Works

πŸ€– AI Agent Makes a code change creates .context/00012.md ## Fix: Null Check Reasoning & context stored as Markdown references src/user.ts // refer to context 00012 src/auth.ts // refer to context 00012 src/service.ts // refer to context 00012 later... πŸ€– Future AI Retrieves context Understands WHY

Why context-stash?

🧠

Persistent Memory

Context survives sessions, models, and tools. No more starting from scratch.

πŸ”—

Cross-File References

One decision can explain changes in multiple filesβ€”just like humans think.

πŸ“–

Human-Readable

Plain Markdown files that anyone can read, audit, and edit.

πŸ”’

Immutable by Design

Historical reasoning stays accurate. Create new entries instead of editing old ones.

🌍

Universal

Works with any MCP-compatible AI agent: Claude, Copilot, Cursor, and more.

πŸš€

Git-Native

Version control for both code and reasoning. Track decisions over time.

The Difference

❌ Without context-stash πŸ€– Day 1: AI fixes bug πŸ€– Day 2: AI reintroduces bug No memory of why it was fixed βœ… With context-stash πŸ€– Day 1: AI fixes bug Creates context entry πŸ€– πŸ’‘ Day 2: AI reads context Understands and preserves fix

Simple to Use

1. Initialize your project

cd /path/to/your/project
context-stash --init

2. Configure your AI agent

{
  "mcpServers": {
    "context-stash": {
      "command": "context-stash",
      "args": ["--serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

3. AI agents use it automatically

// AI creates context when making changes
context.create({
  markdown: "## Fix: Race Condition\n\nAdded mutex lock..."
})
// Returns: { "file": "00012.md" }

// AI references it in code
// refer to context 00012
function updateBalance() { ... }

Ready to give your AI agents memory?

npm install -g context-stash

What to Store

πŸ›

Bug Fixes

What broke, why it broke, and how you fixed it

🎯

Design Decisions

Why you chose approach A over approach B

⚠️

Workarounds

Why the "proper" solution wasn't feasible

πŸ”„

Refactoring

What assumptions changed and why

🧱

Constraints

What limitations influenced the design

πŸ’‘

Intent

What the code is trying to accomplish