Perenna

这是什么？适合谁？

Perenna（scarletkc/Perenna，16 Stars，MIT，PyPI: perenna）是一个 Git 背书的 AI Agent 永久记忆层，以 MCP server 形态提供。它要解决的问题是记忆孤岛：Claude Code、Codex、Cursor、ChatGPT 各自把记忆存在自己的角落里——换 Agent 记忆就丢、换机器记忆就留在原地。

Perenna 的回答很工程派：记忆就是你自己 Git 仓库里的普通 Markdown。每条 durable memory 都是可 inspect、可编辑、可版本化、可备份的人类可读文件；所有 Agent（本地 stdio 或自托管 HTTP 接入的 ChatGPT）连同一个 Perenna 服务，共享这一份记忆。没有账号、没有专有记忆云、没有锁定。

设计要点：

• 读写分离的 MCP 工具：read/write/delete 各自独立工具，权限边界清晰
• 两种传输：本地 stdio 与单用户 OAuth 保护的 Streamable HTTP
• 本地检索索引（Vexor）：语义检索可用，但永远可以从 Git 重建——索引是缓存不是源
• 跨进程锁：多个本地 Agent 进程并发读写不冲突
• 记忆行为 Skill：perenna skill install --agent claude-code/codex 可选装「如何使用记忆」的行为指引

作者对竞品的批评也值得引用：Mem0 自托管栈重得多，而其托管免费计划条款允许客户内容用于模型训练与产品改进——Perenna 用「你的 Git 仓库、你控制的基础设施」从设计上排除这类问题。

适合人群：

• 同时用多个编码 Agent（Claude Code + Codex + Cursor）的开发者，想要一份跨 Agent 的项目记忆
• 数据主权敏感的用户/团队：记忆必须可审计、可导出、可自托管
• 想给 Agent 做「长期记忆」但不想引入向量数据库全家桶的工程师

不适合：想要开箱即用云端 SaaS 记忆服务的用户；需要多团队共享/复杂权限管理的场景（当前单用户定位）。

使用前提：Python 3.12+、Git、uv；或任一 MCP 客户端。

准备工作

1. 运行时：Python 3.12+、Git、uv。
2. 安装：uv tool install perenna。
3. （可选）记忆行为 Skill：perenna skill install --agent claude-code（或 codex，两者都要就重复 --agent）。
4. Git 仓库：为记忆单独建一个私有仓库（强烈建议 private）。
5. 成本：MIT 免费开源；成本仅本地运行与你自己 LLM 的 tokens。
6. 时间预算：安装配置 10 分钟。

快速上手（3 步）

第一步：安装

uv tool install perenna
# 可选：给本地客户端装记忆行为 skill
perenna skill install --agent claude-code

第二步：接入 Agent

最省事的方式是把官方引导 prompt 贴给你的 Agent：

Open the following URL, read the complete instructions, and follow them to
install and connect Perenna:
https://raw.githubusercontent.com/scarletkc/Perenna/main/docs/guides/agent-installation.md

Claude Code/Codex/ChatGPT Desktop/Cursor 都能照着自主完成配置。

第三步：跨 Agent 验证记忆共享

（在 Claude Code 里）记住：这个项目用 pnpm，禁止 npm install。
（换到 Codex 里）这个项目用什么包管理器？

预期结果：Codex 从 Perenna 读出「pnpm，禁止 npm install」——记忆跨 Agent 存活。

常见踩坑

踩坑 1：索引与 Git 内容不一致

• 现象：检索结果缺最新记忆。
• 原因：索引未同步（索引只是缓存）。
• 解决：任何时候可删索引从 Git 重建；这也是设计兜底而非 bug。

踩坑 2：并发写冲突

• 现象：多 Agent 同时写记忆时偶发报错。
• 原因：跨进程锁保证不损坏，但业务层去重仍需注意。
• 解决：让不同 Agent 写不同主题前缀；冲突时靠 Git 历史回滚。

踩坑 3：把记忆仓库设成 public

• 现象：记忆内容（可能含代码上下文、个人偏好）公开泄露。
• 原因：新建仓库默认 public（GitHub）。
• 解决：务必 private；这是你唯一的安全边界之一。

踩坑 4：stdio 与 HTTP 模式混淆

• 现象：ChatGPT 连不上本地 stdio 的实例。
• 原因：ChatGPT 需要走自托管 Streamable HTTP（OAuth 保护）。
• 解决：按文档起 HTTP 模式并配置 OAuth，本地 CLI 类 Agent 用 stdio。

踩坑 5：Python 版本不达标

• 现象：安装失败。
• 原因：要求 Python 3.12+。
• 解决：uv 会自动管理 Python 版本；确认 uv tool install perenna 用的解释器 ≥3.12。

踩坑 6：skill 装了没生效

• 现象：Agent 不主动用记忆。
• 原因：行为 skill 只装在了一个 Agent 的目录。
• 解决：perenna skill install --agent codex --agent claude-code 一条命令装双端。

初级用法

1. 项目约定记忆：包管理器、代码风格、禁区——一次写入，所有 Agent 遵守。
2. 踩坑日志：让每个 Agent 干完活自动把「本次踩坑+解法」写进 Perenna，形成团队知识库。
3. 直接读 Markdown：记忆就是 Git 里的 .md，用编辑器/Git 历史直接查看与修改，不依赖任何工具。
4. 定期备份：记忆仓库 push 到远端，备份策略与代码仓库一致。

高级玩法

1. 记忆的 code review：记忆仓库开 PR 流程——Agent 写的记忆先出 PR、人审后合并，记忆质量有门禁。
2. 跨机器同步：办公机/家用机克隆同一记忆仓库，配合锁机制避免写冲突。
3. ChatGPT + 本地 CLI 混编：自托管 HTTP 模式让 ChatGPT 与 Claude Code 共享同一份记忆，云端/本地 Agent 认知对齐。
4. 记忆迁移与审计：从 Mem0 等导出记忆转成 Markdown 入库；Git blame 就是记忆审计日志。

小技巧

1. 记忆按主题分文件：conventions.md、pitfalls.md、people.md，比一锅粥好检索好审阅。
2. 删记忆也走 Git：delete 工具之外，直接改文件提交同样合法，历史可追溯。
3. 重建索引当体检：定期删索引重建，顺便验证 Git 源完整性。
4. OAuth 别关：HTTP 模式的 OAuth 保护是单用户场景的最低安全线。
5. 给记忆写测试：把「Agent 是否正确读到了约定」做成冒烟测试，防配置漂移。

常见问题 FAQ

Q1：和 Mem0 有什么本质区别？

A：Mem0 是向量库/云服务取向（自托管栈重、托管版有数据训练条款）；Perenna 是 Git + Markdown + 可重建索引，数据主权完全在你。来源：README Why Perenna

Q2：语义检索怎么做？索引丢了怎么办？

A：本地 Vexor 检索索引，索引永远可从 Git 重建——Git 是唯一事实源。来源：README

Q3：ChatGPT（非 MCP 客户端）怎么接？

A：通过自托管、OAuth 保护的 Streamable HTTP 端点接入。来源：README

Q4：能多人共用吗？

A：当前设计为单用户；多 Agent 共享是核心场景，多人类协作者不是。

Q5：记忆会很大吗？性能如何？

A：Markdown 文本体积通常远小于向量库；检索走本地索引，规模敏感场景建议分仓。

进阶学习建议

• 读 agent-installation.md 的自安装设计：让 Agent 自己读文档完成安装配置——这种「Agent 自服务 onboarding」模式正在成为 MCP 工具的标配交互，值得在自己产品里复用。
• 对比三种记忆架构：Perenna（Git 源）vs 向量库方案 vs 厂商托管记忆，从「可审计性/可迁移性/运维成本」三列表格做一次自己的选型分析，你会更清楚什么时候 Git 背书是优势、什么时候是负担。
• 记忆治理实践：结合上面的「记忆 PR 门禁」玩法，给你的记忆仓库写一份 CONTRIBUTING——记忆质量决定 Agent 长期表现。

参考链接

• Perenna GitHub 仓库
• PyPI: perenna
• DeepWiki: Perenna
• MCP 协议官网

免责声明：本文基于官方仓库 README 与 GitHub 公开数据整理，AI 辅助生成，MagicNetWorld 尚未完成独立实测。项目较新（16 Stars），生产采用前请自行评估。