🧠 claude-session-memory

Give Claude Code a memory. Never re-explain architectural decisions again.

Save decisions. Auto-load context. Prove the ROI. 100% local.

😤 The Problem

Every new Claude Code session starts from scratch.

Session 1: "Let's use JWT for authentication because our microservices need stateless auth..."

Session 14: "Why are we using JWT?" — Claude has no idea.

Session 27: You're explaining the same decision for the fifth time.

CLAUDE.md helps but it's static, non-queryable, and becomes a dumping ground.

💰 The Real Cost of Forgetting

Every time Claude doesn't know your project context, you pay for it — in tokens, in time, and in wrong answers.

  Without memory                          With memory
  ─────────────────                       ─────────────────
  You: "Add auth to /orders"              You: "Add auth to /orders"
        │                                       │
        ▼                                       ▼
  Claude: "What auth system                Claude calls query_memory("auth")
   do you use? JWT? Sessions?                    │
   OAuth? What middleware?"                      ▼
        │                                 Claude: "Adding JWT middleware
        ▼                                  using your existing auth pattern
  You: [5 minutes re-explaining]           from decision #12..."
        │                                       │
        ▼                                       ▼
  Claude: "Got it. And what                ✅ Correct implementation
   database? What ORM?"                      on first try
        │
        ▼
  You: [3 more minutes explaining]
        │
        ▼
  Claude builds it wrong anyway
   because context was incomplete

Without memory (session 30)

🔄 Re-explain 3-5 decisions per session
💬 10-15 extra back-and-forth messages
❌ Wrong assumptions from missing context
🔥 Token burn on repeated explanations
⏱️ ~15 min wasted per session

With memory (session 30)

✅ Claude recalls all 47 decisions instantly
💬 Skip straight to implementation
🎯 Correct assumptions from day one
📉 Fewer tokens, faster completions
⏱️ Time saved compounds every session

The math: If you run 3 Claude Code sessions/day and waste ~15 min each re-explaining context, that's 5+ hours/week. With a team of 4, that's 20 hours/week — gone. Project memory eliminates this entirely.

💡 The Solution

An MCP server that gives Claude Code a queryable SQLite database of your project's architectural decisions — plus automatic session intelligence that loads the right context at the right time.

✨ Why Use It

Benefit	What it means for you
🧠 Auto session continuity	Claude knows what you worked on last session — branch, decisions, files changed
🎯 Smart context loading	Relevant decisions are surfaced automatically based on your current branch and files
💰 Proven ROI	Track token savings, time saved, and hit rate — with real numbers
🔁 Never re-explain decisions	Claude remembers what you decided and why, across every session
📋 Session review	Get prompted to save decisions before ending a session — nothing slips through
🔒 100% local and private	SQLite on your machine, zero network calls, zero telemetry

⚡ Quick Start

npx claude-session-memory init

Restart Claude Code. That's it. 🎉

🧠 Session Intelligence

Every session is smarter than the last:

  Session Start (get_stats)              Session End (review_session)
  ─────────────────────────              ────────────────────────────
  ✅ Last session context                ✅ Decisions saved this session
     Branch, decisions, files               What you captured
  ✅ Relevant decisions                  ✅ Files changed without decisions
     Matched by branch + files              What you might have missed
  ✅ Token savings ROI                   ✅ Suggestions
     Queries, hit rate, time saved          "Consider saving for auth.ts"

How context matching works:

File matching — decisions linked to files you're currently modifying
Branch keywords — feature/auth → finds decisions tagged auth
Recent fallback — always shows latest decisions if no specific match

🔄 How It Works

┌─────────────────────────────────────────────────────────┐
│  Claude Code Conversation                               │
│                                                         │
│  You: "Let's use PostgreSQL with Prisma ORM"            │
│                                                         │
│  Claude: "That sounds like an architectural decision.   │
│  Want me to save it?"                                   │
│                                                         │
│  You: "Yes"                                             │
│           │                                             │
│           ▼                                             │
│  ┌─────────────────┐    ┌──────────────────────────┐    │
│  │  save_decision   │───▶│  .claude/project-memory.db│   │
│  └─────────────────┘    └──────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

             ···  Next session  ···

┌─────────────────────────────────────────────────────────┐
│  You: "Why did we choose PostgreSQL?"                   │
│           │                                             │
│           ▼                                             │
│  ┌─────────────────┐    ┌──────────────────────────┐    │
│  │  query_memory    │◀──│  .claude/project-memory.db│   │
│  └─────────────────┘    └──────────────────────────┘    │
│           │                                             │
│           ▼                                             │
│  Claude: "You chose PostgreSQL 16 with Prisma ORM      │
│  because of ACID compliance, JSON support, and strong   │
│  community. Alternatives considered: MySQL, MongoDB."   │
└─────────────────────────────────────────────────────────┘

🛠️ MCP Tools

Tool	Description
`save_decision`	💾 Save an architectural decision with title, rationale, alternatives. Auto-detects duplicates via Jaccard similarity
`query_memory`	🔍 Search decisions using natural language. Logs every query for ROI tracking
`list_recent`	📋 List recent decisions across sessions
`update_decision`	♻️ Deprecate or supersede a decision
`get_stats`	🧠 Session intelligence — last session context, relevant decisions for current work, token savings ROI
`review_session`	📋 Review current session before ending — shows files changed without decisions, suggests what to save
`sync_claude_md`	📝 Export active decisions into your CLAUDE.md with auto-managed markers

💬 Query Examples

"Why did we choose JWT?"
"What decisions affect src/auth.ts?"
"Show me recent decisions"
"Compare Pinia vs Vuex"
"Show deprecated decisions"
"What are the alternatives to Redis?"

🖥️ CLI Commands

Command	Description
`npx claude-session-memory init`	🏁 Initialize project memory
`npx claude-session-memory workspace-setup [dir]`	🔗 Share context memory across all sub-projects in a workspace
`npx claude-session-memory export`	📤 Export decisions (JSON/Markdown/CSV)
`npx claude-session-memory import <file>`	📥 Import decisions from JSON
`npx claude-session-memory sync-claudemd`	📝 Sync active decisions into CLAUDE.md
`npx claude-session-memory stats`	📊 Show memory statistics

Workspace Setup

If you have a monorepo or workspace with multiple sub-projects (each with their own .git), use workspace-setup to share context memory across all of them:

npx claude-session-memory workspace-setup /path/to/workspace
npx claude-session-memory workspace-setup --dry-run   # Preview changes
npx claude-session-memory workspace-setup --force      # Overwrite existing configs

This symlinks the root .mcp.json into every git sub-project so they all share the same decision history.

Export Formats

npx claude-session-memory export                          # JSON (default)
npx claude-session-memory export --format markdown        # Human-readable
npx claude-session-memory export --format csv             # Spreadsheet
npx claude-session-memory export --output ./backup.json   # Custom path

🧹 Smart Deduplication

When saving a new decision, the server automatically compares it against existing ones using Jaccard similarity on tokenized text:

Similarity	Action
> 0.8	Auto-supersedes the older decision — you don't need to clean up
0.6 – 0.8	Returns a warning with similar decisions so you can decide
< 0.6	Saved without warnings

No configuration needed — dedup runs on every save_decision call.

⏳ Confidence Decay

Decisions tagged temporary or experimental automatically fade over 30 days:

Day  0  → confidence 1.0 (full strength)
Day 15  → confidence 0.5 (half strength)
Day 30  → confidence 0.0 (fully faded)

Faded decisions (confidence < 0.3) are excluded from CLAUDE.md sync but remain queryable. Regular decisions never decay regardless of age.

📝 CLAUDE.md Sync

Auto-generate a structured decisions section in your CLAUDE.md:

npx claude-session-memory sync-claudemd

Or call sync_claude_md as an MCP tool during a conversation. The output is injected between markers:

<!-- DECISIONS:START -->
## Architectural Decisions
_Auto-generated from project memory — 5 active decisions_

### Auth
- **Use JWT for authentication** — Stateless and scalable [auth, security]

### Database
- **Use PostgreSQL with Prisma** — ACID compliance [database]
<!-- DECISIONS:END -->

Any content outside the markers is preserved. If no markers exist, they're appended. If no CLAUDE.md exists, one is created.

📊 Token Savings & ROI

Every query_memory call is tracked. The dashboard shows real metrics:

Metric	What it measures
Total Queries	How often Claude queries your memory
Hit Rate	% of queries that returned useful results
Tokens Saved	Estimated tokens saved vs re-explaining (~300/query)
Time Saved	Estimated minutes saved (~2 min/query)

View these in the web dashboard at /analytics or via get_stats in any session.

🏗️ Architecture

claude-session-memory
├── Storage:      SQLite + FTS5 full-text search, WAL mode
├── Transport:    MCP stdio (spawned by Claude Code)
├── Intelligence: Session continuity, context matching, ROI tracking
├── Dashboard:    Built-in web UI with analytics and AI coach
├── Dependencies: better-sqlite3, @modelcontextprotocol/sdk, commander
└── Privacy:      100% local — zero network calls, zero telemetry

📋 Requirements

Node.js >= 18
Claude Code

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

📄 License

MIT — use it however you like.

What using project memory actually feels like

Session 1 — You save your first decision. Nothing special yet.
Session 5 — Claude stops asking what database you use. It knows.
Session 20 — Claude auto-loads your last session's context and relevant decisions before you say a word.
Session 50 — Dashboard shows 500+ tokens saved, 100+ minutes reclaimed. A new teammate asks "how does auth work?" — full history, instantly.

The more you use it, the more valuable it becomes.

Built with ❤️ for the Claude Code community

Stop re-explaining. Start remembering.

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
docs/claude-code-memory-mocks		docs/claude-code-memory-mocks
src		src
templates		templates
tests		tests
web		web
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
schema.sql		schema.sql
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🧠 claude-session-memory

😤 The Problem

💰 The Real Cost of Forgetting

💡 The Solution

✨ Why Use It

⚡ Quick Start

🧠 Session Intelligence

🔄 How It Works

🛠️ MCP Tools

💬 Query Examples

🖥️ CLI Commands

Workspace Setup

Export Formats

🧹 Smart Deduplication

⏳ Confidence Decay

📝 CLAUDE.md Sync

📊 Token Savings & ROI

🏗️ Architecture

📋 Requirements

🤝 Contributing

📄 License

What using project memory actually feels like

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

🧠 claude-session-memory

😤 The Problem

💰 The Real Cost of Forgetting

💡 The Solution

✨ Why Use It

⚡ Quick Start

🧠 Session Intelligence

🔄 How It Works

🛠️ MCP Tools

💬 Query Examples

🖥️ CLI Commands

Workspace Setup

Export Formats

🧹 Smart Deduplication

⏳ Confidence Decay

📝 CLAUDE.md Sync

📊 Token Savings & ROI

🏗️ Architecture

📋 Requirements

🤝 Contributing

📄 License

What using project memory actually feels like

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages