<div align="center">

🧠 claude-session-memory

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

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

</div>

---

😤 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.

---

<div align="center">

💰 The Real Cost of Forgetting

</div>

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

<table> <tr> <td width="50%">

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

</td> <td width="50%">

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

</td> </tr> </table>

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 | | ✍️ Automatic capture | A SessionEnd hook saves decisions from every session — no need to remember to ask | | 🔎 Semantic search | Paraphrased questions still find the right decision, even with zero shared keywords | | 🎯 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:

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

✍️ Automatic Capture

init installs a SessionEnd hook so memory fills itself. When a session ends, decisions are extracted (via Haiku) and saved automatically — you don't have to remember to ask Claude to save them.

  Session ends ──▶ SessionEnd hook ──▶ extract decisions ──▶ save to memory

• Idempotent — sessions already captured are skipped, so nothing is double-saved.
• No key? No problem — without an Anthropic API key it stores session metadata only (no extraction), and you can still save decisions explicitly via save_decision.
• The 5-minute auto-import in the web dashboard still works too; the hook just makes capture immediate.

🔎 Semantic Search

query_memory blends keyword search with vector similarity, so questions match by meaning, not just shared words:

"How do users prove their identity to the API?"
        │
        ▼
✅ finds "Adopt stateless token authentication"  (zero keywords in common)

• Runs 100% locally via a small sentence-embedding model (multi-qa-MiniLM-L6-cos-v1, 384-dim) — the model weights (~25MB) download once on first use, then everything stays on your machine.
• Keyword/FTS matches come first (they capture explicit intent like file paths and tags); semantic matches fill any remaining slots.
• Powered by the optional @xenova/transformers dependency. If it's not installed, search gracefully falls back to keyword-only. Run reindex to embed decisions saved before you enabled it.

🔄 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 reindex | 🔎 Build semantic-search embeddings for existing decisions | | 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 ca