claude-code-memory 0.1.0

Persistent semantic memory for Claude Code — auto-saves and recalls conversation history across sessions.

claude-memory

中文 README

Persistent, semantic, long-term memory for Claude Code. Conversations are auto-saved across sessions and the most relevant snippets are injected into context whenever you start a new prompt — no special syntax, no "remember this" phrasing required.

You      : Do you remember Dandan?
Claude   : Of course — Dandan is your golden Border Collie. 🐶
            (auto-recalled from a chat 3 weeks ago)

How it works

Three Claude Code hooks + a small Python service:

Hook	What it does
UserPromptSubmit	Embeds your prompt and injects the top-K most similar prior turns.
Stop	Persists the current user/assistant turn into SQLite + Chroma.
SessionEnd	Asks Claude Haiku to produce a coarse summary of the session.

Storage:

• SQLite — source of truth for raw turns and summaries
• Chroma — local vector index over both
• Voyage AI (voyage-3) — embeddings

Install

pip install claude-code-memory
claude-memory init

init will:

1. Create ~/.claude/claude-memory/ (data directory)
2. Prompt for your VOYAGE_API_KEY (get one free at https://www.voyageai.com/)
3. Back up your existing ~/.claude/settings.json and add the three hooks
4. Print verification steps

Then open a fresh Claude Code session, chat for a few turns, and run:

claude-memory status

You should see turns and chroma_turns counters going up.

CLI

claude-memory init        Install hooks
claude-memory status      Show data dir, hook registration, DB stats
claude-memory doctor      Verify Python, deps, API key, settings.json
claude-memory uninstall   Remove hooks (keeps your data)

Configuration

All optional, set in ~/.claude/claude-memory/.env:

Variable	Default	Purpose
VOYAGE_API_KEY	—	Required for embeddings
TOP_K	5	Max memories injected per prompt
MIN_SCORE	0.3	Cosine similarity floor (0–1)
CLAUDE_MEMORY_DIR	~/.claude/claude-memory	Where SQLite + Chroma live
CLAUDE_MEMORY_SUMMARY_MODEL	claude-haiku-4-5-20251001	Model used by SessionEnd

Optional: MCP server

You can also expose memory as MCP tools for Claude Code (search_memory, list_recent, stats, forget). Add to ~/.claude.json or .mcp.json:

{
  "mcpServers": {
    "claude-memory": {
      "command": "claude-memory-mcp"
    }
  }
}

Uninstall

claude-memory uninstall            # removes hooks from settings.json
rm -rf ~/.claude/claude-memory     # delete all your stored data (irreversible)

Privacy

• All data stays on your machine in ~/.claude/claude-memory/.
• The only outbound call is to Voyage AI for embeddings (your prompt text) and Anthropic for end-of-session summaries.
• Set CLAUDE_MEMORY_DIR to encrypt at rest with whatever filesystem-level encryption your OS provides.

License

MIT — see LICENSE.