How to Add Persistent Memory to Claude Code (30-Second Setup)

If you use Claude Code, you've experienced the frustration: you spend an hour explaining your project's architecture, your testing preferences, your deployment pipeline. Claude gets it. It writes perfect code. Then you close the terminal.

Next session? Blank slate. It's like onboarding a new developer every single time.

This isn't a Claude Code bug. It's a fundamental limitation of how LLM-powered coding tools work. The context window resets between sessions. Your decisions, preferences, and architecture choices vanish into the void.

Yes, there's CLAUDE.md. And it helps. But it's a static file you maintain by hand. It doesn't capture the dozens of micro-decisions you make during a coding session: "we decided to use Zod instead of io-ts," "the auth flow goes through middleware, not route guards," "we tried Redis for sessions but switched to Postgres because..."

Those are exactly the things that make the second session productive. And they're exactly the things that get lost.

The Fix: One JSON Block, Permanent Memory

Smara is a persistent memory layer for AI coding tools. It connects to Claude Code through the MCP protocol (Model Context Protocol) -- the same open standard Anthropic built for connecting AI tools to external data sources. Once connected, Smara automatically captures context as you work and recalls it when relevant.

No manual saving. No tagging. No commands to remember. Just code normally, and your context follows you.

Here's how to set it up.

{
  "mcpServers": {
    "smara": {
      "command": "npx",
      "args": ["-y", "@smara/mcp-server"],
      "env": { "SMARA_API_KEY": "your-key-here" }
    }
  }
}

Don't have an API key yet? Grab a free one from smara.io -- the free tier includes 10,000 memories, which is plenty for most individual projects.

As you interact with Claude Code, Smara silently captures the important stuff in the background:

• Architecture decisions -- "We're using a monorepo with Turborepo"
• Preferences -- "Always use functional components, never class components"
• Debugging context -- "The CORS issue was caused by the API gateway, not the backend"
• Tool choices -- "We switched from Jest to Vitest for faster test runs"
• Project conventions -- "Error codes follow the HTTP-XXX-DOMAIN pattern"

Smara's AI classifier determines what's worth remembering versus transient conversation noise. You don't need to tag, label, or manually save anything. The memories are stored with source metadata so you always know where a piece of context came from.

Here's what it looks like in practice. Say you made an architecture decision last Tuesday:

You: Let's use SQLite for the local cache instead of Redis.
     Redis is overkill for this -- we just need a fast
     key-value store that works offline.

Claude: Makes sense. I'll set up better-sqlite3 with a simple
       key-value schema. For the cache invalidation, I'll use
       TTL-based expiry with a cleanup sweep every 5 minutes.

  # Smara silently stores: "Project uses SQLite (better-sqlite3)
  # for local caching instead of Redis. TTL-based expiry with
  # 5-minute cleanup sweep." -- tagged as architecture decision

Now, a week later, in a brand new session:

You: I need to add a new endpoint that caches API responses.
     What's our caching setup again?

Claude: Based on our previous decisions, we're using SQLite
       via better-sqlite3 for local caching. The pattern is
       TTL-based expiry with a 5-minute cleanup sweep. I'll
       follow that same pattern for the new endpoint.

  # Smara automatically recalled the relevant memory
  # No manual lookup, no searching through CLAUDE.md

No copying and pasting from old sessions. No maintaining a CLAUDE.md file. The context is just there.

How It Works Under the Hood

Smara isn't just a key-value store. Three systems work together to keep your memories relevant and accurate.

Ebbinghaus Decay Scoring

Not all memories are equally relevant. A decision you made yesterday about your database schema matters more than a one-off debugging trick from three months ago. Smara uses Ebbinghaus forgetting curves to score memory relevance over time.

The formula: R = e^(-t/S), where t is time elapsed and S is memory strength. Strength increases every time a memory is accessed or reinforced. Frequently-used context stays top-of-mind. Stale context naturally decays -- but it never disappears. It's still searchable, just ranked lower.

This means when Claude searches your memory, the most relevant and recently-reinforced context surfaces first. It mimics how human memory actually works.

Semantic Search

Smara uses vector embeddings for retrieval, not keyword matching. When you ask about "our caching setup," it finds memories about SQLite, Redis, TTL expiry, and cache invalidation -- even if those exact words aren't in your query. The semantic similarity is what matters.

This is critical for natural conversations. You don't need to remember the exact terms you used weeks ago. Just ask naturally and the right context surfaces.

Contradiction Detection

Codebases evolve. Decisions change. Smara detects when a new memory contradicts an existing one and handles it gracefully. If you decide to switch from SQLite back to Redis, Smara marks the old memory as superseded and stores the new decision with a reference to what changed and why.

This means Claude won't confidently tell you to use SQLite when you switched to Redis last week. It has the full decision history and always reflects the latest state.

Works With Cursor and Windsurf Too

Smara isn't locked to Claude Code. It works with any MCP-compatible AI coding tool. And here's the real power: memories are shared across tools. Save a decision in Claude Code, recall it in Cursor.

Cursor Configuration

{
  "mcpServers": {
    "smara": {
      "command": "npx",
      "args": ["-y", "@smara/mcp-server"],
      "env": { "SMARA_API_KEY": "your-key-here" }
    }
  }
}

Windsurf Configuration

{
  "mcpServers": {
    "smara": {
      "command": "npx",
      "args": ["-y", "@smara/mcp-server"],
      "env": { "SMARA_API_KEY": "your-key-here" }
    }
  }
}

Smara vs. CLAUDE.md: When to Use What

They're not mutually exclusive. Here's a simple rule of thumb:

• CLAUDE.md -- Static project setup instructions. "This is a Next.js 14 app," "Run pnpm dev to start," "Tests are in __tests__/." Things that rarely change and that every new developer (human or AI) needs on day one.
• Smara -- Dynamic, evolving context. Architecture decisions, debugging history, preference changes, tool choices, team conventions. The things that accumulate over weeks and months of development and that CLAUDE.md was never designed to capture.

Use both. Let CLAUDE.md handle the static bootstrap. Let Smara handle everything else.

Frequently Asked Questions