claude-memory-manager

Claude Memory Manager

Claude Code 的跨会话记忆——在不同会话之间保留上下文。

Claude Memory Manager 会自动从你的 Claude Code 会话中捕获架构决策、代码更改、Bug 修复和配置选择，并在你启动新会话时智能检索相关上下文。

它的功能

每次使用 Claude Code 时，都会产生有价值的上下文，但会话结束后这些上下文就会丢失：

• 你选择了哪些库，以及选择原因
• Bug 修复及其根本原因
• 配置决策
• 文件结构和命名约定
• 错误解决方案

Claude Memory Manager 通过以下方式解决这个问题：

1. 解析 Claude Code 会话日志（JSONL 文件）
2. 提取有意义的记忆并评估其重要性
3. 嵌入记忆，以便进行语义搜索
4. 将所有内容存储在带有 FTS5 的本地 SQLite 数据库中
5. 通过混合语义搜索和关键词搜索检索相关上下文
6. 通过 MCP 协议向 Claude Desktop 提供上下文

安装

pip install claude-memory-manager

使用本地嵌入模型（无需 API 密钥）：

pip install claude-memory-manager[local]

用于开发：

pip install claude-memory-manager[dev]

快速开始

1. 初始化数据库

claude-memory init

这会在 ~/.claude-memory/memory.db 创建 SQLite 数据库，并保存配置文件。

2. 导入会话日志

# 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 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. 生成上下文摘要

# 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. 连接到 Claude Desktop（MCP）

将以下内容添加到你的 Claude Desktop 配置中（参见 MCP 设置）：

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

CLI 参考

命令	描述
claude-memory init	初始化 SQLite 数据库
claude-memory ingest [PATH]	从指定路径导入会话日志
claude-memory ingest --watch	监视并自动导入新会话
claude-memory search "query"	混合语义搜索和关键词搜索
claude-memory context [PROJECT]	生成上下文摘要
claude-memory list	列出所有已索引的会话
claude-memory stats	数据库统计信息
claude-memory prune --older-than 90d	删除较早的记忆
claude-memory export	将记忆导出为 JSON
claude-memory serve	启动 MCP 服务模式

全局选项

选项	描述
--config PATH	自定义配置文件路径
--verbose / -v	启用调试日志
--version	显示版本

搜索选项

选项	描述
--project / -p	按项目路径筛选
--category / -c	按类别筛选
--limit / -n	最大结果数（默认：5）

类别

记忆分为以下类别：

• decision — 架构和设计决策
• code_change — 重要代码修改
• bug_fix — Bug 的识别与解决
• config — 配置和环境更改
• error_resolution — 遇到并解决的错误
• preference — 用户偏好和约定
• discussion — 一般讨论摘要

MCP 设置

Claude Desktop

1. 找到你的 Claude Desktop 配置文件：

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

2. 添加记忆服务：

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

3. 重启 Claude Desktop。

完整示例请参见 examples/claude-desktop-config.json。

MCP 工具

连接后，Claude Desktop 可以使用以下工具：

工具	描述
memory_search	根据查询搜索记忆，并可选择应用筛选条件
memory_recall	获取项目的格式化上下文摘要
memory_save	直接保存新记忆
memory_stats	获取数据库统计信息

架构

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

数据流

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)

配置

配置按以下优先级加载：

1. 环境变量
2. 配置文件（~/.claude-memory/config.json）
3. 默认值

环境变量

变量	描述	默认值
CLAUDE_SESSIONS_PATH	会话日志路径	~/.claude/projects
CLAUDE_MEMORY_DB_PATH	数据库文件路径	~/.claude-memory/memory.db
CLAUDE_MEMORY_EMBEDDING_PROVIDER	anthropic、voyage 或 local	local
ANTHROPIC_API_KEY	Anthropic API 密钥	—
VOYAGE_API_KEY	Voyage AI API 密钥	—
CLAUDE_MEMORY_MAX_TOKENS	上下文的最大 token 数	2000
CLAUDE_MEMORY_LOG_LEVEL	日志级别	INFO

嵌入提供方

提供方	维度	要求
voyage	1024	VOYAGE_API_KEY
anthropic	1024	ANTHROPIC_API_KEY
local	384	pip install claude-memory-manager[local]

如果没有可用的提供方，则会使用存根提供方（仍可进行关键词搜索，但语义搜索会被禁用）。

常见问题

我的记忆存储在哪里？ 存储在 ~/.claude-memory/memory.db 的 SQLite 数据库中。所有数据都保存在本地。

这会将我的代码发送到任何 API 吗？ 只有在配置 Voyage 或 Anthropic 嵌入提供方时才会。此时，只会发送记忆文本内容（而非完整会话日志）来生成嵌入。使用 local 可完全离线运行。

去重如何工作？ 每条记忆的内容都会经过哈希处理（SHA-256）。如果已存在哈希值相同的记忆，则在导入过程中跳过该记忆。

混合搜索如何工作？ 将余弦相似度向量搜索的结果（权重为 70%）与 SQLite FTS5 关键词搜索的结果（权重为 30%）合并。同时出现在两者中的记忆会合并评分。

我可以导出记忆吗？ 可以：claude-memory export > memories.json 或 claude-memory export -o file.json。

如何清理旧记忆？ claude-memory prune --older-than 90d 会移除超过 90 天的记忆。支持 d（天）、w（周）、m（月）、y（年）。

开发

# 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/

许可证

MIT 许可证。版权归 NyxTools 所有，2026 年。