pensieve

Pensieve

一份由 Agent 驱动、可跨会话留存的个人记忆。

你每天都会与 AI 助手（Claude Code）交谈，但它会忘记不同会话之间的所有内容。Pensieve 是由你掌控的长期记忆：在对话中的任何时候，你都可以说 “把这个添加到 pensieve” 来记录内容，也可以说 “我对 X 了解些什么？” 来找回内容——它会在那里，井然有序、保持更新，而且归你所有。

这个比喻是：刻意抽取一缕思绪，存入容器中，以便日后重温。

这是一个小型 Python + SQLite 引擎，提供两个入口：Agent 使用的 MCP 服务，以及供你使用的 命令行。你的记忆保存在 ~/.pensieve 这个单独的文件中。

---

理念

Pensieve 中的每项决策都由五个理念塑造：

1. 信息湖，而非项目管理器。 它存储你知道的内容，并让你随时回忆。它有意不包含任务、状态或截止日期——Agent 通过阅读推断状态，存储只保存信息。

2. 输入和回忆都由你主动决定。 Pensieve 绝不会自行操作。只有你说*“记住这个”时，它才会写入；只有你提出请求*时，它才会回忆。不会静默保存，也不会在会话开始时自动加载你的记忆。你始终掌控哪些内容进入、哪些内容取出。

3. 结构自然形成，无需预先设计。 你不必构建分类体系。只需保留少数几个顶层信息流（你实际参与的领域），并在其中记录笔记。笔记中提及的人物、组织和主题会自动成为实体；反复出现的实体则会逐渐形成自己的线索。组织结构是使用的结果。

4. 笔记是原子，其他一切都引用笔记。 一条笔记可以独立存在，也可以同时属于多个信息流。实体和线索是笔记的视图，而非笔记的所有者——因此，移除某个主题不会销毁同时涉及其他内容的笔记。

5. 指向现实世界，不要复制它。 将代码仓库、文件或 URL 作为资源附加——它是一个通过引用访问的指针，并附带一行“如何使用我”的提示。Pensieve 会存储这个指针，并在需要时读取；它不会爬取你的磁盘，也不会自行打开链接。

想深入了解背后的原因——设计决策、完整模型和权衡取舍？ docs/philosophy.md。

---

模型

项目	含义
信息流	工作或生活中的顶层领域——career、personal、side-projects。由你主动创建，数量不多。
笔记	一条独立的信息——你记录内容的基本单位。可以同时属于多个信息流。
实体	笔记涉及的人物／组织／主题。由笔记（通过标记）产生；不会凭空创建。
线索	某个反复出现并形成独立主题的实体，归属于某个信息流。
资源	通过引用访问的指针（代码仓库／文件／目录／URL／图片／文档）和使用提示，可附加到信息流、线索或笔记。

有三种回忆方式：按名称（find）、按内容（search——全文检索、词干提取、排序），以及按时间（recent——近期有哪些变化）。

---

安装

需要 Python 3.12+。

推荐：从 PyPI 安装

Pensieve 是一个标准的 MCP 服务，因此最快的入门方式是使用 pipx （或 uv）：

pipx install pensieve-mcp     # or: uv tool install pensieve-mcp

这会将 pensieve（CLI）和 pensieve-mcp（MCP 服务）添加到 PATH。然后将 Agent 指向它。对于 Claude Code：

claude mcp add --scope user pensieve -- pensieve-mcp

对于其他任何 MCP 客户端，将 pensieve-mcp 命令注册为 stdio 服务即可。无需安装即可临时运行时，也可以使用 uvx pensieve-mcp。

Pensieve 已列入官方 MCP Registry，条目为 io.github.praveen-ilangovan/pensieve，因此支持注册表的客户端可以直接发现并安装它。

注意： PyPI 软件包是引擎（CLI + MCP 服务）。负责判断的 Claude skill（capture/fetch 工作流）随代码仓库提供，而不在 wheel 中——如果需要它， 请使用下面的脚本安装，它会将 skill 安装到 ~/.claude/skills/pensieve/。

从源代码设置 Agent

git clone [email protected]:praveen-ilangovan/pensieve.git
cd pensieve
./install.sh          # Claude Code (backward-compatible default)
./install.sh codex    # Codex
./install.sh all      # both

install.sh 会预先检查必备条件（如果缺少任何条件，则不会进行任何更改），确保已安装 pipx，安装 Pensieve（将 pensieve + pensieve-mcp 添加到 PATH），安装所选的 Agent skill，并在该 Agent 的用户配置中注册 MCP 服务。Claude 的 skill 位于 ~/.claude/skills/pensieve/；Codex 的用户级 $pensieve skill 会以符号链接的形式放在 ~/.agents/skills/pensieve/，因此在每个代码仓库中都可使用。它具有幂等性——可随时重新运行以获取更新。

Codex 的 MCP 注册会固定设置 PENSIEVE_HOME=~/.pensieve，确保即使从此代码仓库启动 Codex（其 .env 有意将开发命令指向 .local/manual），Codex 读写的仍是与 Claude 相同的个人存储。引擎和 MCP 工具保持不变；Codex skill 提供了与现有 Claude 适配器相同的审慎捕获/回忆流程。

然后重启所选的 Agent，并在任意目录中询问：

“我有哪些流？检查一下 pensieve。”

你的记忆保存在 ~/.pensieve 中。

---

使用方法（配合 Agent）

Pensieve 通过 Agent 发挥作用——你自然地表达，Agent 负责判断并调用工具。下面的内容只是与 Claude Code 对话。

设置领域（只需刻意设置一次）：

“创建一个名为 Career 的 pensieve 流，用来记录我的求职和工作相关内容。”

捕获——任何时候出现值得保留的内容：

“把这件事添加到 pensieve：和 Maya 通了电话，聊了平台岗位；她正在审阅我的作品集。”

Agent 会筛选出值得长期保留的内容，将其归入合适的流，并识别出“Maya”是值得跟踪的人物——无需你管理这些事项。如果一条笔记涉及两个领域（例如，某场演讲同时与 career 和 side-project 相关），它会在两个领域中各归档同一条笔记。

回忆——根据问题选择合适的角度：

“我知道哪些关于 Maya 的事？”·“我们对薪酬做了什么决定？”·“帮我梳理一下——最近有什么变化？”

指向实时上下文——让 Agent 知道去哪里读取：

“将我的项目仓库 ~/projects/acme 添加为 side-projects 流中的资源——提示：先读取 README.md。”之后再说：“调出 acme 仓库。”（只有在你提出要求时，它才会跟随该指针。）

提升——当某件事反复出现时，Agent 会提出建议：

“Maya 在 5 条笔记中出现过——要不要在 Career 下为她建立单独的主题？”

移除 / 恢复——所有操作都是软删除，且可撤销：

“移除那条笔记。”/“等等，把它恢复。”/“我不再需要 X 流了。”

---

使用方法（CLI）

同一个引擎也提供 CLI，方便快速检查，或在不使用 Agent 的情况下编写脚本 （pensieve stream list、pensieve search "…" 等）。完整的命令参考及示例： docs/cli.md。

---

底层工作原理

• SQLite 存储（~/.pensieve），首次使用时通过 Alembic 自动迁移。
• 通过 SQLite FTS5 + Porter 词干提取器进行全文搜索（因此搜索「pricing」也能找到「priced」）。
• 简洁的 端口/适配器 核心：服务依赖存储 端口，该端口有两个可互换的后端（SQLite + 内存替身），并通过一致性测试确保两者行为一致。
• MCP 服务和 CLI 是精简的「操作」层；判断（保留什么、如何解析实体、何时提升）由 Agent 技能（adapters/claude/）负责。

---

参与开发

make install         # poetry env + pre-commit hooks
make test            # unit + integration
make eval            # deterministic engine evaluators
make check           # ruff (lint+format) + mypy
make manual ARGS="stream list"   # run the CLI against the local dev store

此仓库是一个自包含的开发环境——不会触及你真实的 ~/.pensieve。 仓库内的 MCP 服务和 CLI 使用本地开发存储（.env → .local/manual）；全局安装（./install.sh）才会指向 ~/.pensieve。

设计说明位于 plans/（每个切片一个文件，另有 plans/roadmap.md）和 docs/ （philosophy.md——理念与模型，cli.md——命令）。

---

状态

已投入使用，并且每天都在使用：流 · 线程 · 笔记 · 实体 · 提升 · 资源 · 搜索 · 最近度 · 多流笔记 · 软删除/恢复——既可通过 CLI，也可通过 MCP 使用。 由真实 Agent 逐个切片构建并验证。后续计划请参阅 plans/roadmap.md。