Piia Engram
让多个 AI 编程工具共享一套由用户掌控、可审阅和覆盖的本地工作身份与长期知识。
- Star 数
- ★ 166
- 最近更新
- 12 天前
- License
- AGPL-3.0
- 主语言
- Python
- FA 评分
- 77/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台Codex · Claude CodeChatGPT(部分支持)
- 费用
- 免费,无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 同时使用 Claude Code、Codex 和 Cursor 的开发者,希望各客户端读取同一套编码偏好、质量标准与经验。
- 不适合
- 需要加密所有本地记忆文件的团队
- 需要经过加密认证的调用方隔离的组织
- 只想保存单次任务历史、而非用户身份知识的人
- 维护状态
- 近 30 天有提交最近提交 2026-11-08最新版本 v4.27.0(2026-11-01)
- 源码审查
- 77/100 · 表现良好
这个 Agent 能做什么,适合哪些场景?
Piia Engram 是面向开发者的本地优先 AI 工作身份层,而不是通用的 Agent 会话记忆数据库。它把身份、偏好、质量标准、项目快照、经验教训、关键决策和操作 Playbook 保存到 ~/.engram/ 下的 JSON 与 Markdown 文件中。项目通过 Python CLI 和 MCP stdio 服务器向 Claude Code、Codex、Cursor 等客户端提供读取、检索、写回、审阅、导入导出和会话恢复能力;不支持 MCP 的 ChatGPT、Gemini 和 Kimi 可使用导出的 Markdown 身份卡。默认身份与知识操作不联网,混合检索、远程 SSE 服务、加密、治理及遥测均属于可选能力。它适合频繁切换 AI 编程工具、希望知识可见且可迁移的用户,但本地明文默认值和调用方身份边界需要在采用前认真评估。
安装后,engram setup 检测 Python 环境和已安装的 AI 工具,询问数据目录,并在用户确认后备份、写入 MCP 配置。MCP 客户端可用 get_user_context 加载身份和已批准知识,用 search_knowledge、get_relevant_knowledge 或 get_recall 检索经验、决策与 Playbook,并通过 add_lesson、add_decision、add_playbook 或统一入口 memory_store 写回本地存储。save_project_snapshot、get_recent_context 和 get_resume_brief 负责项目及跨会话衔接;wrap_up_session 可提取会话成果,并把检测到的多步骤流程生成为待确认的 Playbook 草稿。高风险内容进入审阅流程,低中风险写入可审计并可撤销,设置 ENGRAM_APPROVAL=strict 可拦截所有写入。engram preview --as automation 展示调用方实际能收到的内容,engram doctor 检查安装和配置,export_engram、import_engram 与 get_identity_card 分别处理完整备份、预览式导入和非 MCP 工具的 Markdown 输出。默认使用关键词搜索;安装 vector 扩展并设置 ENGRAM_SEARCH=hybrid 后,可启用 FTS5 与语义向量结合的跨语言检索。
- 同时使用 Claude Code、Codex 和 Cursor 的开发者,希望各客户端读取同一套编码偏好、质量标准与经验。
- 经常开启新对话的工程师,希望通过
get_user_context或get_resume_brief减少重复说明背景。 - 架构师需要长期保存决策、被否决方案及原因,并在后续项目中检索决策链。
- 维护重复发布或部署流程的团队,希望从会话中生成待审阅的 Playbook,并记录执行结果。
- 重视数据主权的个人用户,希望记忆保存在可直接检查、编辑、备份和迁移的本地文件中。
- 需要在不支持 MCP 的 ChatGPT、Gemini 或 Kimi 中复用工作身份的用户,可导出并粘贴 Markdown 身份卡。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 安装 / 启动命令
pip install piia-engrampip install "piia-engram[vector]"
- 配置文件
~/.codex/mcp.json- 运行环境
- Python 3.10+
如何安装或部署这个 Agent?
需要 Python 3.10+。基础安装和交互式配置为:
pip install piia-engram
engram setup向导会列出将要修改的客户端配置文件,并在确认后写入 MCP 连接;每次外部配置写入前都会备份。用于 CI 或非交互环境时可直接应用外部配置:
engram setup --apply-external-config配置完成后重启对应 AI 工具,并执行健康检查:
engram doctor若需要可选的语义向量检索:
pip install "piia-engram[vector]"随后在 MCP 环境中设置 ENGRAM_SEARCH=hybrid。身份与知识功能默认不要求网络或 API 密钥。
如何使用这个 Agent?
Codex 可在 ~/.codex/mcp.json 中添加:
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"]
}
}
}Claude Code 也可直接注册 stdio MCP 服务器:
claude mcp add piia-engram -- piia-engram-mcp重启客户端后,先调用 get_user_context 获取已批准的身份与知识;工作中用 search_knowledge 查找经验和决策,用 memory_store 或 add_lesson、add_decision、add_playbook 保存新内容,结束时调用 wrap_up_session。可在终端预览 AI 将看到的内容并检查连续性:
engram preview --as automation
engram continuity若要开放全部高级工具,可在 MCP 服务器配置中加入:
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"],
"env": {
"ENGRAM_TOOLS": "all"
}
}
}
}不支持 MCP 的工具可使用 get_identity_card 生成 Markdown,再粘贴到对话中;该路径不是自动同步。
这个 Agent 有哪些优点和局限?
- 同一份本地存储可供多个 MCP 编程客户端使用,减少被单一工具的原生记忆锁定。
- JSON 和 Markdown 数据可直接查看、修改、备份与迁移,并提供 Memory Lens 预览调用方实际可见内容。
- 具备经验、决策和 Playbook 的结构化生命周期,包括暂存审阅、版本历史、关系、合并及知识继承。
- 默认身份和知识操作不发起网络请求,远程遥测及反馈需要单独明确启用。
- 提供 CLI 健康检查、配置修复、备份式外部配置写入和可逆导入预览。
- 既支持 MCP stdio,也记录了自托管 SSE 服务以及非 MCP 工具的 Markdown 回退路径。
- 本地 JSON 和 Markdown 默认是明文;AES-256-GCM 只覆盖受支持的资料字段,并非整个存储。
- 任何能读取
~/.engram/的进程都能访问数据,restricted_fields也不是真正的 ACL。 - MCP 不提供可靠的工具身份,治理依赖环境变量而非加密认证,不能视为强化沙箱。
- 各客户端证据等级不一致:Claude Code 与 Codex 有部分跨工具连续性证明,Cursor 仅有读写路径证据,多款客户端只是预期可用。
- 混合搜索需要额外安装 vector 依赖,远程模式还要求 HTTPS 反向代理、令牌和 CORS 配置。
- 文档中的工具数量存在不一致:部分位置写 19 个核心工具或总计 59 个,明确枚举和 FAQ 则写 18 个核心加 40 个高级工具。
这个 Agent 与同类方案有什么区别?
与 Claude Memory 相比,Piia Engram 把资料存放在用户控制的本地文件中,并面向多个 MCP 工具,而不是限定在 Claude 生态。与 CLAUDE.md 或 .cursorrules 相比,它保存跨仓库的个人偏好、经验与决策;仓库规则文件仍更适合项目专属构建步骤和规范。与 Mem0、Zep、Letta 这类 Agent 记忆系统相比,它强调“用户是谁”及其长期工作标准,而不是单次 Agent 工作流发生了什么。与官方 @modelcontextprotocol/server-memory 的通用实体关系图相比,它提供开发者身份、质量标准、经验、决策和审阅治理等专用结构。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Piia Engram 当前 | 77 · 表现良好 | 命令行工具免费 | ★ 166 | 12 天前 | Python | Codex · Claude Code |
| Remnic 智能体记忆 | 73 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 235 | 今天 | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| Mnemo Cortex | 75 · 表现良好 | 自托管服务免费 | ★ 161 | 1 天前 | Python | Codex · Claude Code · Claude.ai |
| mex 项目记忆 | 84 · 表现良好 | 命令行工具免费 | ★ 1.8k | 2 天前 | TypeScript | Codex · Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
文档明确说明数据存于本地 JSON/Markdown、默认明文、每日匿名使用信号及关闭方式;安全策略和遥测说明交代载荷、目的地、可选网络读取与本地审计。setup 展示将改动的配置并确认、备份;但低/中风险知识会自动验证,默认遥测仍会发送,且敏感字段加密为可选,因此未满分。
CI 配置显示多版本 Python 测试、额外依赖测试和依赖审计步骤,CLI 也说明传输失败、迁移失败时如何处理;但 README 的技能说明称长期知识需用户审核,quickstart 则称低/中风险项目立即自动验证,形成产品行为描述不一致,因此自洽性扣分。静态材料不能确认实际测试结果。
面向多种 MCP 编码工具和跨会话记忆,提供核心/高级工具分层、非 MCP 身份卡及客户端证据等级;技能触发语句具体,也明确普通编码任务不应调用。部分工具仅为预期兼容或证据待补,且主要流程面向本地 Python/MCP 环境,故环境适配未满分。
文档按快速开始、集成、隐私、治理和运维分层,安装步骤、FAQ、限制及双语说明充分;许可证文件与包元数据一致。版本号可见且有发布检查,但所给材料未提供清晰的维护者个人/组织责任与变更日志,相关分数保守。
产品把可编辑的身份、经验和决策跨工具提供给 AI,提供检索、恢复和导出等明确用途,边际价值描述具体。收益依赖客户端主动调用和本地配置,且额外工具与向量搜索带来设置和依赖成本,因此成本收益评分为中等。
README 对能力等级、遥测、加密、网络调用和验证边界有较细的文档指引;CI 文件列出测试和声明同步门。多处说明仍属于仓库自述,且本次材料未包含相应运行产物或完整源码来交叉核验,故跨来源印证未满分。
- 默认每日发送包含随机安装 ID、版本、系统、Python 版本、客户端名称和日期的匿名遥测;禁用前应查看遥测状态与预览。
- 本地记忆默认是明文文件;支持字段级加密需额外安装并配置密钥,而且不覆盖整个存储。
- 低/中风险写入自动验证与“用户决定永久知识”的技能描述不完全一致;采用前应确认当前审批策略。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
发布说明摘录
English Features - Hook queue body protection. When store encryption is enabled, hook queue events are stored in an authenticated encrypted envelope. Plaintext publication and encryption enablement share a root-local policy gate, and recovery diagnostics stay read-only. Existing plaintext queues remain readable. Downstream archives, digests and other generated outputs are not covered. See [Hook queue protection](https://github.com/Patdolitse/piia-engram/blob/main/docs/hook-queue-protection.md). …在 GitHub 查看 ↗ -
发布说明摘录
English Features - Isolated store contract v1 lets callers check compatibility with CONTRACT_VERSION and require_contract("1"). - Both isolated modes support atomic admission that supersedes a matching item. Family, subject and decision point must match; an older version cannot be restored while its replacement is active. - Recall receipts include a deterministic result_sha256 for verifying the returned result. Existing receipts remain readable. Fixes …在 GitHub 查看 ↗ -
发布说明摘录
English More reliable isolated store retries, verifiable recall receipts, and logical lifecycle times for replay experience. - Both isolated store modes accept optional event keys for idempotent retries and refuse conflicting reuse. Independent events can retain identical templates; unkeyed admission keeps its existing behavior. - Recall receipts include a snapshot ID, ordered item IDs, content hashes, and a query digest and term count. verify_recall_receipt checks integrity and reports retirement, veto, changed content or missing items without returning their bodies. …在 GitHub 查看 ↗
常见问题
使用它是否需要付费模型或云账户?
数据是否默认加密?
piia-engram[secure] 并设置 ENGRAM_SECRET 后,可对受支持的资料字段启用 AES-256-GCM,但这不是全盘加密。它会自动修改 Codex 或 Cursor 配置吗?
engram setup 会先显示目标文件并等待确认,写入前创建备份;拒绝则不修改。engram setup --apply-external-config 会跳过确认,适合明确需要非交互写入的环境。升级后 MCP 断开怎么办?
piia-engram doctor --fix,然后重启受影响的 AI 工具;该命令会检查已知 MCP 配置并修复旧条目或错误路径。ChatGPT 能否直接连接同一份记忆?
get_identity_card 导出后粘贴到 ChatGPT。它不是与 MCP 客户端相同的实时本地连接。Piia Engram 开源吗?
Piia Engram 安全吗?
Piia Engram 还在维护吗?
Piia Engram 是谁开发的?
谢谢反馈,我们会据此改进页面。