Tom Yahav

Posted on Mar 7

I Built a Memory Layer for Claude Code — It Saves Me Hours Every Week

#claude #opensource #productivity #ai

Every Claude Code session starts from scratch. No matter how many times you've explained your architecture, your tech stack, or why you chose JWT over sessions — Claude forgets all of it the moment the session ends.

I got tired of re-explaining the same decisions. So I built something about it.

The Problem That Costs You More Than You Think

Here's a conversation I was having three times a week:

Me: "Add authentication to the /orders endpoint"

Claude: "What authentication system are you using?"

Me: "JWT. We decided this in session 1."

Claude: "Got it. And what database?"

Me: "PostgreSQL with Prisma. We've been over this."

Claude: "And what middleware pattern?"

Me: [10 minutes later, still explaining context]

Sound familiar?

Every re-explanation burns tokens (which cost money), time (which you don't get back), and patience (which is finite).

I did some rough math on my own usage:

~3 Claude Code sessions per day
~15 minutes wasted per session re-explaining context
That's 5+ hours per week — just on context that Claude should already know

For a team of 4 developers, that's 20 hours per week. Gone.

The Fix: Give Claude a Memory

claude-session-memory is an open-source MCP server that gives Claude Code a persistent, queryable memory.

It works like this:

Session 1 — You make a decision, Claude saves it:

You: "Let's use JWT for authentication — stateless,
      scalable for our microservices."

Claude: "Saved as architectural decision #1."

Session 14 — You ask about it, Claude remembers:

You: "Why are we using JWT?"

Claude: "You chose JWT for authentication (decision #1)
        because of stateless scalability for microservices.
        Alternatives considered: session cookies, OAuth2."

Session 27 — You just build:

You: "Add auth to the /orders endpoint"

Claude: [queries memory, finds JWT decision,
         knows your middleware pattern, builds it correctly]

No re-explaining. No wasted tokens. No wrong assumptions.

Setup: 30 Seconds

npx claude-session-memory init

Restart Claude Code. Done.

That one command:

Creates a local SQLite database in .claude/project-memory.db
Registers the MCP server in your .claude/settings.json
Generates a memory-instructions template so Claude knows how to use it

What It Actually Does

Under the hood, it's an MCP server with 6 tools:

Tool	What it does
`save_decision`	Save an architectural decision with rationale, alternatives, and tags
`query_memory`	Search past decisions using natural language
`list_recent`	See recent decisions across sessions
`update_decision`	Deprecate or supersede outdated decisions
`get_stats`	Memory overview (runs automatically at session start)
`sync_claude_md`	Export decisions into your CLAUDE.md

When Claude starts a new session, get_stats fires automatically. Claude sees something like:

Decisions:  47 total (42 active, 3 deprecated, 2 superseded)
Sessions:   31
Last activity: 2 hours ago
Top tags: auth (8), database (6), api (5), performance (4)

Now Claude knows this project has history — and it will query that history before making assumptions.

Smart Features That Keep It Clean

Automatic Deduplication

Every time you save a decision, the server compares it against existing ones using Jaccard similarity:

> 80% similar — Auto-supersedes the older version (no cleanup needed)
60-80% similar — Returns a warning so you can decide
< 60% — Saved without warnings

This means you can freely save decisions without worrying about duplicates piling up.

Confidence Decay

Tag a decision as temporary or experimental, and it automatically fades over 30 days:

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

Faded decisions are excluded from auto-generated docs but remain queryable. Regular decisions never decay.

CLAUDE.md Sync

Export your active decisions directly into CLAUDE.md:

npx claude-session-memory sync-claudemd

It injects a structured section 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 -->

Everything outside the markers is preserved. This means Claude gets your most important decisions loaded into context automatically — zero-cost recall.

The Compounding Effect

This is the part that surprised me.

The first few sessions feel normal. You save some decisions, query a couple things. Fine.

But around session 20, something shifts. You stop explaining things. You say "add caching" and Claude already knows your stack, your patterns, your conventions. It just builds correctly.

By session 50, a new team member can open Claude Code in your project and ask "how does authentication work?" — and get the full decision history, rationale, alternatives, and trade-offs. Instantly.

The value compounds with every session. The more decisions you save, the smarter every future session becomes.

What It Doesn't Do

Let me be upfront about what this is not:

Not a cloud service — Everything is local SQLite. Zero network calls, zero telemetry.
Not a CLAUDE.md replacement — It complements CLAUDE.md by making it queryable and auto-generated.
Not magic — You still need to save decisions (though Claude learns to suggest saving them proactively).

A Full Dashboard — Not Just a CLI

You don't have to live in the terminal to use this. There's a built-in web dashboard:

npx claude-session-memory web

This launches a local Vue 3 + Tailwind app at http://localhost:3850 where you can:

Browse all decisions with full-text search, status filters, and tag filtering
View decision details — rationale, alternatives, consequences, linked files, and history
Explore sessions — see which decisions were made in each Claude Code session
Track analytics — work patterns, decision quality metrics, codebase knowledge coverage
Get AI coaching — an AI-powered insights panel that analyzes your decision patterns and suggests improvements
Import past sessions — scan your ~/.claude/projects/ directory and bulk-import decisions from old transcripts
Manage settings — database info, API key storage, maintenance tools

Everything runs locally. The dashboard reads from the same SQLite database that the MCP server uses — so what you see in the browser is always in sync with what Claude sees in conversation.

Monorepo? One Command.

If you have a workspace with multiple sub-projects:

npx claude-session-memory workspace-setup /path/to/workspace

This symlinks the MCP config into every git sub-project, so they all share the same decision history. Your auth decisions in one service are instantly available when working on another.

Real Query Examples

Once you have a few sessions worth of decisions, you can ask things like:

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

The query router handles natural language — you don't need exact syntax.