Project Memory

项目记忆

Project Memory 将一个项目的计划、证据、决策、成果和认可的经验教训保存在本地 SQLite 数据库中。助手通过三个 MCP 工具读取和写入这些记录。你可以在本地控制面板中查看相同的记录；该面板为只读，你则在聊天中决定哪些内容获得批准、认可并合并。

它适用于软件产品、咨询项目，也适用于在 n8n 中构建的工作流自动化。工作项可以是代码、文档、交付成果或导出的工作流。

公开测试版。 需要 Python 3.11 或更高版本。运行时仅使用 Python 标准库。没有遥测、托管数据库或账户。Agent 检查和委派的工作通过你已安装的 Codex 或 Claude Code CLI 运行，并计入相应账户的用量。

安装

安装 uv，然后在你想要记录的项目中运行：

uvx [email protected] setup --client codex --trust

对于 Claude Code，请将 --client codex 替换为 --client claude。设置过程会保留现有记录和设置，连接 MCP 服务和生命周期钩子，并打开控制面板。--trust 会在该客户端中批准项目集成；省略此参数即可自行批准连接。之后启动一个新的助手会话。无界面安装时，请添加 --no-view。

如需使用永久命令：

uv tool install project-memory-mcp==0.6.0b16
project-memory doctor
project-memory view

如需直接从 GitHub 安装已发布的 wheel，而非从 PyPI 安装：

uvx --from https://github.com/Dankaro-projects/project-memory/releases/download/v0.6.0b16/project_memory_mcp-0.6.0b16-py3-none-any.whl project-memory setup --client claude --trust

其他本地 MCP 客户端使用 setup --client mcp 和 stdio 服务。设置与生命周期介绍了客户端配置、插件、升级、备份和移除。

启动项目

新项目从三个模板之一开始：

project-memory init ~/projects/pricing-tool --template product --client codex

模板	适用场景	入门文档	阶段
product	软件产品	docs/brief.md、docs/research.md、docs/architecture.md、docs/stories.md	目标与简报、研究、需求审批、架构、用户故事与验收、构建、评审与发布
engagement	咨询项目	engagement/brief.md、engagement/stakeholders.md、engagement/research.md、engagement/findings.md、deliverables/README.md	范围与简报、利益相关方与假设、研究与证据、分析与综合、建议与交付成果、客户评审、交接
automation	工作流自动化，n8n 导出文件放在 workflows/ 中	automation/process.md、automation/systems.md、automation/solution-design.md、workflows/README.md	流程探索、系统与凭据清单、解决方案设计、工作流故事与测试数据、构建工作流、使用示例数据测试、部署与交接

init 会创建文件夹；除非传入 --no-git，否则还会初始化 git；写入尚不存在的入门文档；连接你指定的客户端；并将每个阶段记录为一个工作项。再次运行时不会重复创建内容，也绝不会覆盖你编辑过的文档。

启动对话

每个模板都附带七个启动问题。助手会使用 memory_get kickoff 读取这些问题，例如询问产品解决什么问题、利益相关方是谁，或流程使用哪些系统。它会使用 memory_write answer_kickoff 记录你的回答，根据回答填写入门文档，并提出需求建议。只有你可以批准需求基线。在获得批准之前，控制面板会显示启动清单，其中包括未解答的问题、仍需开展的研究、仍为空的入门文档以及各个阶段。

日常循环

告诉助手你想要的结果、约束条件，以及怎样才算完成。随后，它会记录一项工作，包含其目标、完成标准、下一步行动以及允许修改的文件；在后续会话中，它会根据这份记录继续工作，并记录每项决策及其证据、备选方案、不确定性和预期影响。采取行动后，它会记录实际发生的情况。即使之后成功，失败也会保留在记录中。

你负责批准需求、接受或拒绝建议的经验教训、扩大允许访问的路径范围，以及决定合并哪些内容。记录一份文档并不代表批准其内容，制定计划也不等于授权开展工作。

控制面板

在项目中运行 project-memory view，或让助手打开 Project Memory。面板读取同一个数据库，并在打开期间刷新。其布局类似 Notion 工作区：侧边栏中包含各种视图；数据库表格支持视图、筛选、排序和分组；点击条目后，会在列表旁以页面形式打开。面板支持浅色或深色主题。

视图	内容
现在	用一句话概述项目进度、启动检查清单，以及进行中、已暂停、就绪和已完成的工作及其各自的下一步，还有近期决策
计划	以包含嵌套子项和进度的提纲形式展示阶段、史诗、故事、研究项、交付成果和工作流的层级，并以图库形式展示各阶段
工作	工作项的表格和看板，以及每个工作项的页面，展示计划、允许访问的路径、依赖项、Agent 运行、溯源关系和历史记录
架构	来自源代码、导出的 n8n 工作流，以及系统、利益相关者和交付成果等已编写条目的组件
依赖项	工作依赖关系图（包含受阻链条），以及已声明的软件包表格
决策	决策及其结果，以及从需求到结果的溯源关系
学习	已接受的防护规则及其再次出现的记录、等待你接受的经验教训、尚无经验教训的失败，以及范围扩展记录
Agent	主机可用性、Agent 检查、委派运行，以及合并或丢弃的决策
记录	搜索所有类型的记录、已捕获的文档和主机回执
需求	当前需求、其版本及其批准证据

project-memory view --output review.html --include-bodies --no-open 则会写入离线快照。请参阅控制面板指南。

在 Obsidian 中阅读记录

project-memory export --obsidian <vault> 会将记录写入一个包含 frontmatter 和 wikilinks 的 Markdown 笔记文件夹，Obsidian 会将其作为知识库打开。每个工作项都是一个文件夹，其中包含自己的决策、结果和计划；来源、经验教训和需求修订则位于其旁边的共享文件夹中。这样，Obsidian 的关系图、反向链接和搜索便可用于项目历史，而面板仍是你做出决策的地方。

导出是单向的。数据库是事实来源，导出内容仅占用知识库中的一个文件夹，不会触及其他内容；在该文件夹中编辑的笔记会在下次运行时丢失。会话写入记录后，会话停止钩子会在独立进程中刷新知识库。

Agent 检查和委派工作

配置 Codex 或 Claude Code 后，Project Memory 可以启动独立运行的短时主机进程。Agent 检查会读取记录和项目，并针对某项结果、当前意图或尚未确认的执行情况提供报告。委派工作会在独立的 git worktree 中运行工作项，并限制在其计划允许的路径范围内；随后，第二个主机会审查生成的差异，之后你再进行合并。如果某个主机报告用量限制或速率限制，运行会改由另一个已配置的主机重试一次。

这些运行会使用你已安装的 Codex 或 Claude Code 账户，并消耗该账户的用量。审查者无法编辑计划、接受经验教训或合并任何内容。请参阅Agent 检查和委派工作。

防护与范围

带有触发条件的已采纳经验会成为防护规则。当防护规则与工作项的路径或措辞匹配时，决策必须在 lessons_considered 中列出该经验，明确给出是或否，并说明理由，否则该决策会被拒绝。当工作项设有允许的路径时，生命周期钩子会阻止在这些路径之外进行编辑、记录拦截，并在聊天中要求你扩展范围。记录字段 文档定义了规则模式。

诚实的边界

• 已记录的计划不等于授权。自主性和范围属于参考记录；允许执行哪些操作，由宿主自身的权限和你当前的指令决定。
• 范围防护会读取编辑工具的文件路径、补丁标记以及 MCP 写入工具的目标。它不会解析 shell 重定向，也不会检测 shell 命令中的其他间接写入。
• 钩子会以机械方式记录事件。只有助手能记录这些事件的含义，而已连接面板并不能证明记录完整。
• Agent 的判定是一种解读。检查通过并不能证明工作正确，发现列表为空也不能证明工作正确。
• 架构是根据导入、清单和导出的工作流文件进行静态读取的。无法检测动态加载。
• 有界检索会限制一次调用返回的字符数，但无法控制宿主完整的模型输入。
• 本项目不会衡量每日生产力、令牌用量、纠正率和人工任务耗时，也不会对此作出任何声明。测试与限制 说明了哪些内容经过验证，哪些没有。

文档

• 用户指南，涵盖从首次对话到交付的全过程
• 控制面板和Agent 检查与委派工作
• 设置与生命周期和记录字段
• 测试与限制、贡献指南、安全和发布

软件包已发布在 PyPI 和 GitHub Releases。