memory-mcp

memory-mcp

为 Claude Code 提供持久记忆 + 自动 Git 快照。永不丢失上下文，永不丢失代码。

🧠 45 memories | 📊 2.8K tokens | 📸 23 snapshots | ⏱️ 5m ago

为什么选择 memory-mcp？

问题	解决方案
每次会话都要重新解释项目	自动记录决策、模式和架构
上下文窗口已满，知识丢失	双层记忆：CLAUDE.md（即时）+ 深度搜索
搞坏了东西，却想不起之前什么有效	每次保存时创建 Git 快照，可即时回滚
不清楚 Claude 对项目「了解」多少	可视化面板展示所有上下文
担心云端存储	100% 本地文件，保存在你的 Git 仓库中

与众不同之处

• Git 快照 — 每次保存记忆都会提交整个项目。随时回滚。
• 双层记忆 — CLAUDE.md 即时加载，深度存储可在对话中搜索。
• 由大模型驱动 — Haiku 提取重要信息、合并重复内容并清理过时信息。
• 可视化面板 — 查看上下文：令牌数、不同类型的记忆和快照历史。
• 零操作负担 — 无需运行命令，一切都在后台静默运行。

快速开始

# Install globally
npm install -g claude-code-memory

# Interactive setup (API key + hooks)
memory-mcp setup

# Initialize a project
memory-mcp init ~/Projects/my-app

就这样。开始编码吧。记忆会自动积累。

工作原理

graph TB
    subgraph "Phase 1: Silent Capture"
        A[Claude Code Session] -->|User sends message| B[Claude responds]
        B -->|Hook fires: Stop/PreCompact/SessionEnd| C[extractor.js]
        C --> D[Read transcript from cursor]
        D --> E[Chunk if >6000 chars]
        E --> F[Send to Haiku LLM]
        F -->|Extract memories as JSON| G[Dedup via Jaccard similarity]
        G --> H[Save to .memory/state.json]
        H --> I[Decay confidence scores]
        I --> J{Consolidation needed?}
        J -->|>80 memories or every 10 extractions| K[Haiku merges/drops]
        J -->|No| L[Sync CLAUDE.md]
        K --> L
    end

    subgraph "Phase 2: Recovery"
        M[New session starts] -->|Built-in behavior| N[Claude reads CLAUDE.md]
        N --> O[Claude has full project context]
    end

    subgraph "Phase 3: Deep Recall"
        O --> P{Need specific context?}
        P -->|memory_search| Q[Keyword search across memories]
        P -->|memory_ask| R[Haiku synthesizes answer from top 30 matches]
        P -->|memory_related| S[Tag-based retrieval]
    end

    subgraph "Data Store"
        H -.-> T[(.memory/state.json<br/>Full memory store)]
        L -.-> U[(CLAUDE.md<br/>~150 line summary)]
        T -.->|MCP tools read| Q
        T -.->|MCP tools read| R
        T -.->|MCP tools read| S
    end

    style A fill:#4a9eff,color:#fff
    style F fill:#ff6b6b,color:#fff
    style K fill:#ff6b6b,color:#fff
    style R fill:#ff6b6b,color:#fff
    style T fill:#ffd93d,color:#000
    style U fill:#6bcb77,color:#000

双层记忆架构：

层	用途	大小
CLAUDE.md	在会话开始时自动读取。包含约 150 行最重要的上下文。	精简
.memory/state.json	完整的记忆存储。可在对话中通过 MCP 工具搜索。	不限

通过钩子静默捕获：

Claude Code 钩子会在每次回复后（Stop）、上下文压缩前（PreCompact）以及会话结束时（SessionEnd）触发。快速大模型（Haiku）会读取对话记录并提取：

• 架构 — 系统的组织结构
• 决策 — 选择 X 而非 Y 的原因
• 模式 — 约定和做事方式
• 注意事项 — 不明显的陷阱
• 进度 — 已完成的事项和正在进行的工作
• 上下文 — 业务背景、截止日期和偏好

智能记忆管理：

• Jaccard 相似度去重（避免重复记忆）
• 置信度衰减（进度信息在 7 天后衰减，上下文信息在 30 天后衰减）
• 由大模型驱动的整合（合并重叠记忆，清理过时记忆）
• 按行数限制 CLAUDE.md（控制在约 150 行以内，并将最重要的信息排在前面）

更新

更新现有安装：

npm install -g claude-code-memory --force

更新钩子（例如，修复漏洞后）：

memory-mcp setup

要求

• Claude Code 命令行
• Node.js 18+
• Anthropic API 密钥（用于基于 Haiku 的提取器，每次提取约 $0.001）

CLI 命令

memory-mcp setup              Interactive first-time setup
memory-mcp init [dir]          Initialize memory for a project
memory-mcp status [dir]        Show memory status and health
memory-mcp statusline [dir]    Compact one-line status (great for shell prompts)
memory-mcp context [dir]       Show context metrics and token usage
memory-mcp context --html      Generate visual HTML dashboard
memory-mcp search <query>      Search memories by keyword
memory-mcp ask <question>      Ask a question, get answer from memory
memory-mcp consolidate [dir]   Merge duplicates, prune stale memories
memory-mcp key [api-key]       Set or check Anthropic API key
memory-mcp snapshots [dir]     List git snapshot history
memory-mcp snapshot-enable     Enable automatic git snapshots
memory-mcp snapshot-disable    Disable git snapshots
memory-mcp help                Show help

上下文面板

使用 memory-mcp context 可视化记忆用量：

Context Dashboard

  Project: my-app

  Total Context
  2.8K estimated tokens

  Tier 1 CLAUDE.md (auto-loaded)
  █████████████████░░░░░░░░░░░░░ 1.0K
  45 lines, 44 in memory block

  Tier 2 .memory/state.json (searchable)
  ██████████████████████████████ 1.8K
  29 active, 5 archived, 24 superseded

  Memories by Type
  architecture ███░░░░░░░░░░░░░░░░░   8 memories (291 tokens)
  decision     ██████░░░░░░░░░░░░░░  18 memories (540 tokens)
  gotcha       ████░░░░░░░░░░░░░░░░  10 memories (332 tokens)
  progress     ██████░░░░░░░░░░░░░░  19 memories (538 tokens)

  Git Snapshots
  ● Enabled on __memory-snapshots
  42 commits → origin

使用 memory-mcp context --html 生成交互式浏览器面板。

Git 快照

与工作会话关联的自动项目版本管理。每次提取记忆时，都会将整个项目提交到隐藏分支。

# Enable during init (you'll be prompted)
memory-mcp init ~/Projects/my-app

# Or enable later
memory-mcp snapshot-enable

# View snapshot history
memory-mcp snapshots

# Compare two snapshots
memory-mcp snapshot-diff abc123 def456

# Restore to a previous state
memory-mcp snapshot-restore abc123

# Disable (preserves existing snapshots)
memory-mcp snapshot-disable

工作原理：

• 提交到 __memory-snapshots 分支（在常规工作流中不可见）
• 可选推送到远程仓库（例如 origin）
• 提交消息包含提取的记忆内容
• 捕获整个项目状态，而不只是记忆文件

使用场景：

• 在引入破坏性更改后回滚
• 查看项目在特定会话期间的状态
• 同时跟踪项目演进和上下文变化

MCP 工具（由 Claude 在对话过程中使用）

配置为 MCP 服务后，Claude 可以在会话期间使用以下工具：

工具	描述
memory_search	在所有记忆中进行关键词搜索
memory_related	按标签或领域获取记忆
memory_ask	提出问题，获取由大模型根据记忆综合生成的答案
memory_save	手动保存一条记忆
memory_recall	使用筛选条件列出所有记忆
memory_delete	删除一条记忆
memory_consolidate	触发记忆整合
memory_consciousness	生成完整的意识文档
memory_stats	显示记忆统计信息
memory_init	设置项目名称和描述

存储内容

记忆分为六种类型：

architecture   "Next.js 14 app router with Supabase backend, Stripe for billing"
decision       "Chose server components for public pages because of SEO requirements"
pattern        "All API routes validate input with zod and return NextResponse"
gotcha         "Supabase RLS policy on word_lists requires user_id OR org_id, not both"
progress       "Auth complete, billing webhook handling in progress"
context        "Client wants launch by March, focus on core features only"

文件结构

初始化后，项目将包含：

your-project/
├── CLAUDE.md              ← auto-updated memory summary (read on session start)
├── .memory/
│   ├── state.json         ← full memory store
│   └── cursor.json        ← tracks what's been processed
├── .mcp.json              ← MCP server configuration
└── .claude/
    └── settings.json      ← hook configuration

CLAUDE.md 格式

记忆块会插入标记之间，同时保留现有的 CLAUDE.md 内容：

# MyProject
A brief description

_Last updated: 2026-01-27 | 45 active memories, 62 total_

## Architecture
- Next.js 14 app router with Supabase backend
- Auth via NextAuth with Google and email providers

## Key Decisions
- Chose server components for SEO pages
- Using Supabase RLS instead of API-level auth

## Patterns & Conventions
- All API routes use zod validation
- Tailwind only, no CSS modules

## Gotchas & Pitfalls
- RLS policy requires user_id OR org_id, not both

## Current Progress
- Auth: complete
- Billing: in progress

## Context
- Launch target: March

_For deeper context, use memory_search, memory_related, or memory_ask tools._

全局安装与按项目安装

全局安装（推荐）：钩子会自动适用于所有项目。

memory-mcp setup  # select "global" when prompted

按项目安装：为每个项目配置钩子和 MCP。

memory-mcp init /path/to/project

配置

API 密钥按以下顺序读取：

1. ANTHROPIC_API_KEY 环境变量
2. ~/.memory-mcp/config.json
3. ~/.config/anthropic/api_key
4. ~/.anthropic/api_key

费用

提取器使用 Claude Haiku 提取并整合记忆。典型费用：

• 每次提取约 $0.001（每次 Claude 回复后）
• 每次整合约 $0.005（每约 10 次提取后）
• 完整一天的编码：约 $0.05–0.10

许可证

MIT