pensieve (Esparkman)

冥想盆

Claude Code的持久内存MCP服务器，可记住跨对话边界的决策、偏好和上下文。

*“我用冥想器。一个人只需从脑海中吸取多余的想法，把它们倒进盆里，然后在闲暇时检查它们。”* --阿不思·邓布利多

问题

当Claude Code对话被压缩或清除时：

• Agent“忘记”发现的模式、决策和理解
• 用户重复解释相同的上下文
• 代理人可能会产生幻觉或与之前的决定相矛盾
• 每隔几个小时的深度工作就会失去动力

解决方案

Pensieve通过SQLite提供持久存储，Claude可以通过本机工具调用访问：

• pensieve_remember --保存决策、偏好、发现、实体
• pensieve_recall --查询知识库
• pensieve_session_start --在对话开始时加载上下文
• pensieve_session_end --在结束之前坚持学习

安装

选项1:npx（推荐）

claude mcp add pensieve npx @esparkman/pensieve

就是这样！重新启动Claude Code，工具可用。

选项2：克隆和构建

# Clone the repository
git clone https://github.com/esparkman/pensieve.git ~/Development/pensieve
cd ~/Development/pensieve

# Install dependencies and build
npm install
npm run build

# Add to Claude Code
claude mcp add pensieve node ~/Development/pensieve/dist/index.js

选项3:Docker

# Clone the repository
git clone https://github.com/esparkman/pensieve.git
cd pensieve

# Build the Docker image
docker build -t pensieve .

# Add to Claude Code (mount your project for local database)
claude mcp add pensieve docker run -i --rm \
  -v "$PWD/.pensieve:/app/.pensieve" \
  -v "$HOME/.claude-pensieve:/root/.claude-pensieve" \
  pensieve

注： Docker方法挂载两个卷：

• $PWD/.pensieve --项目本地数据库（如果在git仓库中）
• $HOME/.claude-pensieve --全局回退数据库

验证安装

安装后，重新启动Claude Code并检查是否加载了Pensieve：

# In a new Claude Code session, the tools should be available:
# pensieve_status, pensieve_remember, pensieve_recall, etc.

用法

安装后，Claude Code将可以访问这些工具：

启动会话

每次谈话开始时，克劳德都应该打电话给：

pensieve_session_start()

这将加载上一次会话的摘要、正在进行的工作、关键决策和首选项。

记住事情

pensieve_remember({
  type: "decision",
  topic: "authentication",
  decision: "Use Devise with magic links",
  rationale: "Passwordless is more secure and user-friendly"
})

pensieve_remember({
  type: "preference",
  category: "testing",
  key: "approach",
  value: "system tests for UI flows"
})

pensieve_remember({
  type: "entity",
  name: "Customer",
  description: "End user who places orders",
  relationships: '{"belongs_to": ["Tenant"], "has_many": ["Orders"]}'
})

pensieve_remember({
  type: "discovery",
  category: "component",
  name: "ButtonComponent",
  location: "app/components/base/button_component.rb",
  description: "Primary button component with variants"
})

回忆往事

pensieve_recall({ query: "authentication" })
pensieve_recall({ type: "preferences" })
pensieve_recall({ type: "entities" })
pensieve_recall({ type: "session" })
pensieve_recall({ type: "questions" })

结束会话

在结束对话之前：

pensieve_session_end({
  summary: "Completed invoice list component with filtering",
  work_in_progress: "Invoice detail view partially designed",
  next_steps: "Complete detail view, add PDF export",
  key_files: ["app/components/invoices/invoice_list_component.rb"],
  tags: ["invoices", "ui"]
})

数据库位置

Pensieve将数据存储在SQLite中：

• 项目本地 （如果 .git 或 .pensieve 存在）： .pensieve/memory.sqlite
• 全球 （回退）： ~/.claude-pensieve/memory.sqlite

这意味着每个项目都有自己的内存，但你也有一个全局内存来存储一般偏好。

环境变量覆盖

集 PENSIEVE_DB_PATH 要明确指定数据库位置：

PENSIEVE_DB_PATH=/custom/path/memory.sqlite claude mcp add pensieve ...

安全

秘密检测

Pensieve自动检测和 拒绝储存 潜在的秘密包括：

• API密钥（AWS、GitHub、Stripe等）
• 带密码的数据库连接字符串
• 承载令牌和私钥
• 信用卡号码和SSN

如果检测到秘密，则不保存数据并显示警告。

存储限制

为了防止无限增长：

• 决策：最多1000（最旧的自动修剪）
• 发现：最多500（最旧的自动修剪）
• 会话：超过90天自动删除
• 字段长度：每个字段最大10KB（截断并警告）

数据存储

数据以明文SQLite存储。请勿储存：

• 密码或API密钥
• 个人身份信息
• 财务证书
• 任何敏感的秘密

数据库仅在本地，从不通过网络传输。

工具参考

数据类型

决策

有理由的重要选择。可按主题搜索。

偏好设置

用户约定（编码风格、测试方法、命名模式）。

发现

在代码库中发现的东西（组件、模式、助手）。

实体

领域模型理解（模型、关系、属性）。

会话

工作会议摘要，以保持连续性。

开放式问题

未解决的障碍或需要解决的问题。

Hooks集成

Pensieve包含一个CLI，该CLI与Claude Code的钩子系统集成，用于自动保存上下文。

快速设置

复制示例挂钩配置：

cp node_modules/@esparkman/pensieve/hooks/settings.json ~/.claude/settings.json

或者添加到现有设置中：

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve auto-save" }]
      },
      {
        "matcher": "manual",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve auto-save" }]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve load-context" }]
      },
      {
        "matcher": "resume",
        "hooks": [{ "type": "command", "command": "npx @esparkman/pensieve load-context" }]
      }
    ]
  }
}

CLI命令

CLI选项

# Auto-save with custom summary
pensieve auto-save --summary "Completed auth feature" --wip "Testing in progress"

# Load context as JSON
pensieve load-context --format json

看 钩子/README.md 了解详细的配置选项。

发展

cd ~/Development/pensieve
npm install
npm run dev    # Run with tsx for development
npm run build  # Build TypeScript

许可证

麻省理工学院