claude-memory-store

v0.2.4

Published

a month ago

Persistent memory for Claude Code. Powered by MongoDB Atlas.

0High
0Medium
0Low

tim_carter_clausen

claude claude-code claude-memory memory persistent-memory mongodb atlas mcp ai llm vector-search context-window

Claude Memory

The first developer-focused persistent memory system for Claude Code.

Claude forgets everything when the context window clears. Claude Memory fixes that. Your architecture decisions, deploy commands, database configs, team conventions, and project patterns persist across every session — stored in your own MongoDB Atlas instance, searchable in under 50ms.

96% semantic retrieval accuracy on real developer session data. One command to install. Zero config after setup. Your data, your database, forever.

npx claude-memory-store init

The Problem

You spend 10 minutes explaining your deploy process to Claude. Next session — gone. You tell Claude about your database clusters, your migration rules, your team conventions. Context clears — gone. Every session starts from zero.

Claude Code's context window is powerful but temporary. When it fills up or you start a new session, everything disappears.

The Solution

Claude Memory gives Claude persistent, searchable memory powered entirely by MongoDB Atlas:

Architecture decisions — "MongoDB Atlas prod-cluster-east, database api_prod, staging on staging-cluster"
Deploy commands — "docker build → ECR push → Dokploy webhook → health check" (with aliases like "deploy", "ship it")
Team conventions — "always use pnpm", "prefer Vitest over Jest", "strict TypeScript everywhere"
Avoid rules — "never run migrations directly on prod", "never deploy on Fridays"
Open threads — "production index on users collection is missing — causing slow queries"
Developer preferences — follow you across every project, every machine

Every memory item is an individual document with its own vector embedding. Search returns the specific decision you need, not a truncated blob.

Why Claude Memory over alternatives?

Cloud-native — works across all your machines, not a local unauthenticated HTTP server
MongoDB Atlas — enterprise-grade security, encryption at rest, your own database
Verified commands — execute exactly as stored, no improvisation
MCP server included — Claude calls recall() and remember() on its own
96% semantic accuracy — tested against real developer session data
Exponential decay — frequently-used memories live forever, forgotten ones fade naturally
Interactive editor — colorful TUI dashboard with graphs, inline editing, and memory health tracking

How It Works

Claude Memory integrates with Claude Code at four levels:

1. Hooks (Passive — Automatic)

Lifecycle hooks fire automatically during every Claude Code session:

Startup — ultra-minimal banner showing memory stats (zero context cost), runs TTL cleanup
Pre-tool-use — queries Atlas on every prompt, injects relevant context if found (commands → semantic search → thread matching)
Post-tool-use — detects natural language intents ("remember this", "add to threads") and stores automatically
Session end — saves working memory, extracts session insights, increments counters

2. MCP Server (Active — Claude Decides)

Four MCP tools Claude can call on its own:

recall(topic) — search memory for relevant decisions
remember(text) — store a decision with auto-classification
memory_threads() — list open threads
memory_stats() — show memory statistics

3. Skill File (Discoverable — User Types `/`)

Slash commands available when you type / in Claude Code:

/recall <topic> — search memory
/remember <text> — store a decision
/threads — view open threads
/stats — memory statistics

4. CLAUDE.md Instructions (Context — Always Present)

Instructions in your global CLAUDE.md tell Claude it has memory available and when to use it.

The Lazy Injection Strategy

Claude Memory does not dump everything into the context window at startup. Atlas queries take under 50ms — there's no reason to waste context space.

Startup banner: <500 characters (just stats: "3 decisions, 2 patterns, 1 thread")
Continue context: 1-2 line summary of last session
New session: zero context cost
Memory surfaces on-demand via pre-tool-use search when relevant
Maximum injection: 2,000 characters per prompt (configurable)

The full memory dump is only loaded when you explicitly ask for it (? at the startup menu).

Quick Start

Prerequisites

Node.js 18+
MongoDB Atlas M10+ cluster (create account) — required for vector search

Install

npx claude-memory-store init

That single command:

Prompts for your Atlas connection string (auto-detects from CLAUDE_MEMORY_ATLAS_URI env var or .env file)
Tests the connection
Creates the claude_memory database and indexes
Sets up Atlas vector search index with automated Voyage AI embedding (requires M10+)
Installs Claude Code hooks (startup, pre-tool-use, post-tool-use, stop)
Registers the MCP server (recall, remember, threads, stats tools)
Installs the skill file (/recall, /remember, /threads, /stats)
Adds memory instructions to your global CLAUDE.md

That's it. No other setup. No API keys. No external services. Just Atlas.

Verify Installation

claude-memory info      # Show project ID, developer ID, config path
claude-memory stats     # Show memory statistics
claude-memory memory    # Show memory summary

Commands

CLI Commands

# Setup
claude-memory init                           # First-time setup (one command does everything)
claude-memory info                           # Show project/developer IDs and config path

# Memory Access
claude-memory memory                         # Show memory summary
claude-memory stats                          # Show detailed statistics + fading memory warnings
claude-memory recall <topic>                 # Search memory for a topic (semantic vector search)
claude-memory remember <text>                # Store a decision/pattern/rule (auto-classified)
claude-memory remember <text> --developer    # Store as developer preference (cross-project)
claude-memory threads                        # Show open threads with status and age
claude-memory commands                       # Show verified commands with steps and triggers

# Interactive Editor (run in a separate terminal)
claude-memory edit                           # Interactive TUI browser with dashboard + graphs
claude-memory edit --developer               # Interactive editor for developer memory
claude-memory edit --file                    # Edit memory as JSON in $EDITOR
claude-memory edit --file --developer        # Edit developer memory in $EDITOR

# Maintenance
claude-memory clear --working                # Clear session history
claude-memory clear --all                    # Clear all project memory (with confirmation)

MCP Tools (Claude calls these automatically)

| Tool | Parameters | Description | |------|------------|-------------| | recall | topic (string), limit? (1-20, default 5) | Search memory via semantic vector search | | remember | text (string), category? (auto/context/architecture/pattern/avoid/preference) | Store with auto-classification | | memory_threads | �� | List open threads with status, age, and context | | memory_stats | — | Full memory statistics including fading warnings |

Slash Commands (Type `/` in Claude Code)

| Command | Description | |---------|-------------| | /recall <topic> | Search memory | | /remember <text> | Store a decision | | /threads | View open threads | | /stats | Memory statistics |

Interactive Memory Editor

The interactive editor provides a full TUI experience for browsing, editing, and managing your memory. Run it in a separate terminal:

claude-memory edit

Dashboard

On launch, a colorful dashboard renders showing:

Memory usage bar charts — proportional bars for each category with item counts
Health panel — total items, active vs decaying breakdown, overall health gauge
Activity panel — 7-day sparkline charts, access patterns, most/least active categories
Color coding — green (healthy, >70%), yellow (moderate, 40-70%), red (fading, <40%)

Navigation

The editor uses inquirer prompts for keyboard-driven navigation:

Category select — browse Architecture, Patterns, Avoid Rules, Open Threads, Commands (project) or Preferences, Style, Defaults, Dev Avoid (developer)
Item list — select any memory item to view details
Item detail — shows created date, access count, and decay health percentage
Actions — Edit (inline), Delete (with confirmation), Back
Scope toggle — switch between project and developer memory at any time
Dashboard refresh — re-render stats after changes

File Mode

For bulk editing, export all memory as JSON to your editor:

claude-memory edit --file          # Opens in $EDITOR
claude-memory edit --file --developer  # Developer memory only

Edit freely — add, remove, reorder. Changes are diffed and synced back to Atlas on save.

What Gets Stored

Auto-Classification

When you tell Claude to remember something, it classifies automatically:

| Your input | Classification | Example | |------------|---------------|---------| | "never..." / "don't..." / "avoid..." | Avoid rule | "never deploy on Fridays" | | "always use..." / "pattern..." / "convention..." | Pattern | "always use pnpm not npm" | | "architecture..." / "database..." / "schema..." | Architecture decision | "MongoDB Atlas on prod-cluster-east" | | "across all projects..." | Developer preference | "prefer Vitest over Jest everywhere" | | Everything else | Context | (general knowledge) |

Memory Types

| Type | Scope | Description | Decays? | |------|-------|-------------|---------| | Architecture decisions | Per project | Technical decisions and system design | Yes | | Patterns | Per project | Coding conventions and approaches | Yes | | Avoid rules | Per project | Anti-patterns and restrictions | Yes | | Verified commands | Per project | Multi-step workflows with triggers | Yes | | Open threads | Per project | Unresolved issues (unresolved/deferred/watching) | Yes | | Context | Per project | General project knowledge | Yes | | Working memory | Per project | Session snapshots (auto-saved) | Yes | | Developer preferences | Per developer | Personal preferences (all projects) | Yes | | Style rules | Per developer | Code style preferences (all projects) | Yes | | Defaults | Per developer | Default settings (all projects) | Yes | | Developer avoid | Per developer | Personal anti-patterns (all projects) | Yes | | Project metadata | Per project | Session count, cost tracking | Never | | Developer metadata | Per developer | Session count, cost tracking | Never |

Verified Commands

Store multi-step workflows with trigger aliases:

Store: "deploy" command with steps:
  1. docker build -t myteam/api-service .
  2. aws ecr push to us-east-1
  3. curl -X POST https://deploy.example.com/webhook/abc123
  4. curl https://api.example.com/health

Triggers: "deploy", "ship it", "push to prod"

Next session, say "deploy" and Claude gets the full pipeline injected automatically. Commands are the highest trust memory — injected immediately without semantic search fallback.

Open Threads

Track unresolved issues across sessions:

| Status | Meaning | |--------|---------| | unresolved | Actively blocking or needs attention | | deferred | Intentionally postponed | | watching | Monitoring — not blocking |

Threads surface automatically via pre-tool-use when keywords in your prompt match thread descriptions.

Architecture

Powered Entirely by MongoDB Atlas

Claude Memory uses a single MongoDB Atlas collection (claude_memory) with a type discriminator. No Redis. No Postgres. No external APIs. No vector database. Just Atlas.

Why Atlas?

Atlas M10+ — vector search with automated embedding via Voyage AI
Global availability, automatic backups, zero maintenance
Your data stays in your own database — not a third-party service

Individual Document Architecture

Every memory item is its own document:

claude_memory collection:
  ├── type: "working"         — session snapshots (one per session)
  ├── type: "project_meta"    — project metadata (one per project, never expires)
  ├── type: "developer_meta"  — developer metadata (one per developer, never expires)
  ├── type: "context"         — general project context
  ├── type: "architecture"    — individual decisions
  ├── type: "pattern"         — individual patterns
  ├── type: "avoid"           — individual avoid rules
  ├── type: "thread"          — individual open threads
  ├── type: "command"         — individual verified commands
  ├── type: "preference"      — individual developer preferences (cross-project)
  ├── type: "style"           — individual style rules (cross-project)
  ├── type: "dev_default"     — individual defaults (cross-project)
  └── type: "dev_avoid"       — individual developer avoid rules (cross-project)

Each document has its own searchable_text field — Atlas generates vector embeddings per item, so search returns the specific decision you need, not a truncated snippet of a giant concatenated blob.

Exponential Decay with Access-Frequency Weighting

Memories don't use a flat TTL. Instead, they fade naturally using exponential decay:

score = min(1.0, exp(-λ × t) × (1 + ln(accessCount)))

λ = ln(2) / halfLifeDays (configurable, default 7 days)
t = days since last access
accessCount boost = logarithmic scaling (1 + ln(n))

What this means:

| Scenario | Behavior | |----------|----------| | Memory accessed daily | Score stays near 1.0 — effectively immortal | | Memory accessed once, 7 days ago | Score ~0.5 (half-life) | | Memory accessed 5x, 14 days ago | Score ~0.65 (access boost keeps it alive) | | Memory accessed once, 30 days ago | Score ~0.01 — approaching deletion |

Thresholds:

Active (score ≥ 0.2) — healthy, normal behavior
Fading (0.05 ≤ score < 0.2) — shown in /stats as a warning
Expired (score < 0.05) — deleted on next startup cleanup
Exempt — project_meta and developer_meta never expire

TTL Renewal: Every time a search returns a document, its last_accessed timestamp and access_count are updated (fire-and-forget, no latency impact). Active memories renew themselves naturally.

Pre-Tool-Use Injection Pipeline

When you type a prompt, memory is searched in three phases:

Command cache (<1ms) — exact string match against stored command triggers
Semantic search (~50ms) — vector search against all memory types if no command match
Thread matching — keyword overlap (2+ matching words or 1 long word >6 chars)

Results are formatted and injected as [MEMORY:ACTIVE] blocks, trimmed to 2,000 characters maximum.

Natural Language Intent Detection

Claude Memory understands natural language commands in conversation:

| What you say | What happens | |-------------|--------------| | "Remember that we use pnpm" | Stores as pattern | | "Never deploy on Fridays" | Stores as avoid rule | | "Add to open threads: slow query on users" | Creates thread | | "Close the slow query thread" | Closes thread | | "What do we know about deploys?" | Semantic search | | "Forget the old staging config" | Removes (with confirmation) | | "Store that as 'deploy'" | Saves as verified command | | "I always prefer tabs over spaces" | Stores as developer preference |

Secret detection prevents accidentally storing credentials, API keys, tokens, or other sensitive data.

Deduplication

Two-layer dedup prevents duplicate entries:

Semantic dedup — checks cosine similarity ≥ 0.92 before inserting
Unique compound indexes — database-level safety net

Project Identity

Claude Memory identifies projects by hashing the git remote URL (first 16 chars of SHA-256). This means:

Same project = same memory, regardless of machine or directory
Rename the folder? Memory stays
Clone on a different machine? Memory is there
Different developer on the same project? Same project memory, different developer preferences

Developer identity is based on git user email hash — your preferences follow you across all projects.

Startup Conversation

At the start of every session, Claude Memory presents options:

=== CLAUDE MEMORY ===
Sessions: 12  |  Last: today
Memory available — 8 architecture, 3 patterns, 2 avoid

(c) Continue — pick up where you left off
(n) Something new
(f) Specific feature or area
(r) Review / update memory
(?) Show full memory context

| Choice | Context Cost | What's Injected | |--------|-------------|-----------------| | (c) Continue | ~200 chars | Last session summary + open threads | | (n) New | 0 chars | Nothing — memory surfaces on-demand | | (f) Feature | ~500-2000 chars | Semantic search results for that feature area | | (r) Review | ~200 chars | Memory counts by type | | (?) Full | ~2000 chars | Complete memory dump (trimmed) |

Configuration

Config is stored at ~/.claude-memory/config.json:

{
  "atlas_uri": "mongodb+srv://...",
  "team_memory": false,
  "memory_ttl_days": 30,
  "decay_half_life_days": 7,
  "decay_death_threshold": 0.05
}

| Setting | Default | Description | |---------|---------|-------------| | atlas_uri | — | MongoDB Atlas connection string (required) | | team_memory | false | Share project memory across all developers on the same repo | | memory_ttl_days | 30 | Legacy TTL setting (kept for backward compatibility) | | decay_half_life_days | 7 | Half-life for exponential decay (days until score halves) | | decay_death_threshold | 0.05 | Score below which memories are deleted on cleanup |

Internal thresholds (in code):

| Constant | Value | Description | |----------|-------|-------------| | VECTOR_RELEVANCE_THRESHOLD | 0.70 | Minimum cosine similarity for search results | | DUPLICATE_SIMILARITY_THRESHOLD | 0.92 | Minimum similarity to consider a duplicate | | MAX_INJECTION_CHARS | 2000 | Maximum characters injected per prompt |

You can also set CLAUDE_MEMORY_ATLAS_URI as an environment variable or in a .env file — the init command auto-detects both.

Why Atlas M10+?

Claude Memory requires MongoDB Atlas M10+ ($57/month) for vector search. This is a deliberate choice — not a limitation.

We tested keyword/regex search against semantic vector search with real developer queries. The results:

| Query Type | Keyword Search | Vector Search | |------------|---------------|---------------| | Exact matches ("prod-cluster-east") | 80% | 80% | | Partial matches ("staging database") | 100% | 100% | | Synonym queries ("how to undo a release") | 0% | 60% | | Conceptual queries ("security best practices") | 0% | 80% | | Natural questions ("what region is our database in") | 0% | 100% | | Overall | 36% | 84% |

Keyword search fails completely when you phrase things differently from how they were stored. That's how humans talk. A memory store that can't understand "how do I deploy" when you stored "docker build → ECR push → webhook" is useless.

$57/month is cheaper than re-explaining your deploy process every session.

Vector embeddings are generated automatically by Atlas via Voyage AI — no external API keys, no per-query fees. Atlas handles embedding generation and vector search natively.

Installation Details

The init command installs integrations in four locations:

Claude Code Hooks (`~/.claude/settings.json`)

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "command": "claude-memory hook:startup" }] }],
    "PreToolUse":   [{ "hooks": [{ "command": "claude-memory hook:pre-tool-use" }] }],
    "PostToolUse":  [{ "hooks": [{ "command": "claude-memory hook:post-tool-use" }] }],
    "Stop":         [{ "hooks": [{ "command": "claude-memory hook:stop" }] }]
  }
}

MCP Server (`~/.claude.json`)

{
  "mcpServers": {
    "claude-memory": {
      "command": "node",
      "args": ["/path/to/dist/bin/mcp-server.js"]
    }
  }
}

Skill File (`~/.claude/skills/memory/SKILL.md`)

Enables /recall, /remember, /threads, /stats slash commands.

CLAUDE.md Instructions (`~/.claude/CLAUDE.md`)

Tells Claude it has persistent memory and when to proactively use it.

File Structure

src/
  atlas/              — MongoDB Atlas client, indexes, vector search, embeddings
  memory/             — CRUD for all memory types (project, developer, working, commands, threads, fading)
  hooks/              — Claude Code lifecycle hooks (startup, pre-tool-use, post-tool-use, stop)
  startup/            — Startup banner, context injection, feature search
  cache/              — In-memory command cache (<1ms trigger lookups)
  natural-language/   — Intent detection, parsing, routing
  slash-commands/     — /memory, /recall, /remember, /threads, /stats, /edit
  editor/             — Interactive TUI browser, dashboard, charts, file-based editor
  bin/                — CLI entry point + MCP server
  cleanup.ts          — Exponential decay cleanup on startup
  config.ts           — Configuration management + thresholds
  decay.ts            — Exponential decay scoring with access-frequency weighting
  project-id.ts       — Project and developer identity resolution
  types.ts            — TypeScript type definitions
  detector.ts         — Cross-session developer pattern detection
  summarizer.ts       — Session summarization prompts
  acknowledgement.ts  — Post-session review and approval

Development

git clone [email protected]:TheDecipherist/claude-memory.git
cd claude-memory
npm install
npm run build       # Compile TypeScript
npm run dev         # Watch mode
npm test            # Run tests (requires Atlas connection)
npm run lint        # Type check

Testing

Tests run against a real Atlas cluster (no mocks). Set CLAUDE_MEMORY_ATLAS_URI in .env:

CLAUDE_MEMORY_ATLAS_URI=mongodb+srv://...

npm test                                    # Full suite (~270+ tests)
npx vitest run tests/unit/                  # Unit tests (no Atlas needed)
npx vitest run tests/multi-session.test.ts  # Multi-session simulation
npx vitest run tests/scenarios.test.ts      # Real-world developer scenarios
npx vitest run tests/context-budget.test.ts # Context budget guarantees

License

MIT

Built by TheDecipherist — because Claude should remember what you told it yesterday.