Claude Memory Manager

Claude Memory Manager

Cross-session memory for Claude Code — never lose context between sessions.

Claude Memory Manager automatically captures architectural decisions, code changes, bug fixes, and configuration choices from your Claude Code sessions, then intelligently retrieves relevant context when you start new sessions.

What It Does

Every time you use Claude Code, valuable context is created and lost when the session ends:

• Which libraries you chose and why
• Bug fixes and their root causes
• Configuration decisions
• File structure and naming conventions
• Error resolutions

Claude Memory Manager solves this by:

1. Parsing your Claude Code session logs (JSONL files)
2. Extracting meaningful memories with importance scoring
3. Embedding memories for semantic search
4. Storing everything in a local SQLite database with FTS5
5. Retrieving relevant context via hybrid semantic + keyword search
6. Serving context to Claude Desktop via MCP protocol

Installation

pip install claude-memory-manager

For local embeddings (no API key needed):

pip install claude-memory-manager[local]

For development:

pip install claude-memory-manager[dev]

Quick Start

1. Initialize the Database

claude-memory init

This creates the SQLite database at ~/.claude-memory/memory.db and saves a config file.

2. Ingest Session Logs

# Ingest all sessions from the default path (~/.claude/projects/)

claude-memory ingest

Ingest from a specific path

claude-memory ingest /path/to/sessions

Watch for new sessions and auto-ingest

claude-memory ingest --watch

3. Search Memories

# Search across all memories

claude-memory search "authentication setup"

Filter by project

claude-memory search "database schema" --project /path/to/project

Filter by category

claude-memory search "cors" --category config

4. Generate Context Summary

# List all indexed projects

claude-memory context

Generate summary for a specific project

claude-memory context /path/to/project

With custom token limit

claude-memory context /path/to/project --max-tokens 3000

5. Connect to Claude Desktop (MCP)

Add to your Claude Desktop config (see MCP Setup):

{

"mcpServers": { "claude-memory": { "command": "claude-memory-mcp", "args": [] } } }

CLI Reference

Global Options

Search Options

Categories

Memories are classified into these categories:

• decision — Architectural and design decisions
• code_change — Significant code modifications
• bug_fix — Bug identification and resolution
• config — Configuration and environment changes
• error_resolution — Errors encountered and solved
• preference — User preferences and conventions
• discussion — General discussion summaries

MCP Setup

Claude Desktop

1. Find your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

1. Add the memory server:

{

"mcpServers": { "claude-memory": { "command": "claude-memory-mcp", "args": [] } } }

1. Restart Claude Desktop.

See examples/claude-desktop-config.json for a complete example.

MCP Tools

Once connected, Claude Desktop can use these tools:

Architecture

claude-memory-manager/

src/claude_memory/ cli.py # Click CLI commands mcp_server.py # MCP stdio server config.py # Configuration management core/ extractor.py # Memory extraction from conversations embedder.py # Embedding generation + caching indexer.py # Pipeline: parse -> extract -> embed -> store retriever.py # Hybrid semantic + keyword search summarizer.py # Context summary generation parsers/ jsonl_parser.py # Claude Code session log parser diff_parser.py # Unified diff parser storage/ database.py # SQLite + FTS5 operations models.py # Pydantic data models migrations.py # Schema versioning integrations/ anthropic_embeddings.py # Voyage AI API local_embeddings.py # sentence-transformers utils/ formatting.py # CLI output formatting license.py # License validation

Data Flow

Session Logs (.jsonl)

| [JSONL Parser] -----> ParsedSession | [Extractor] --------> Memory objects (categorized, scored) | [Embedder] ----------> Embeddings (bytes for SQLite BLOB) | [Indexer] -----------> SQLite DB (with FTS5 index) | [Retriever] ---------> Search results (hybrid ranked) | [Summarizer] --------> Context summary (markdown)

Configuration

Configuration is loaded from (in priority order):

1. Environment variables
2. Config file (~/.claude-memory/config.json)
3. Defaults

Environment Variables

Embedding Providers

If no provider is available, a stub provider is used (keyword search still works, but semantic search is disabled).

FAQ

Where are my memories stored? In a SQLite database at ~/.claude-memory/memory.db. All data stays local.

Does this send my code to any API? Only if you configure the Voyage or Anthropic embedding provider. In that case, only memory text content (not full session logs) is sent to generate embeddings. Use local for fully offline operation.

How does deduplication work? Each memory's content is hashed (SHA-256). If a memory with the same hash already exists, it is skipped during ingestion.

How does hybrid search work? Results from cosine-similarity vector search (70% weight) are combined with SQLite FTS5 keyword search results (30% weight). Memories appearing in both get combined scores.

Can I export my memories? Yes: claude-memory export > memories.json or claude-memory export -o file.json.

How do I prune old memories? claude-memory prune --older-than 90d removes memories older than 90 days. Supports d (days), w (weeks), m (months), y (years).

Development

# Clone and install in development mode

git clone https://github.com/nyxtools/claude-memory-manager.git cd claude-memory-manager pip install -e ".[dev]"

Run tests

pytest

Type check

mypy src/

Lint

ruff check src/ tests/

License

MIT License. Copyright (c) 2026 NyxTools.