Piia Engram

让多个 AI 编程工具共享一套由用户掌控、可审阅和覆盖的本地工作身份与长期知识。

Star 数
★ 166
最近更新
12 天前
License
AGPL-3.0
主语言
Python

30 秒速览

运行形态
命令行工具MCP 服务器自托管服务
可在哪里用
通用 · 跨平台Codex · Claude CodeChatGPT(部分支持)
费用
免费,无需付费服务
上手难度
低 · 几分钟可跑通
开始前需要
Python 3.10+用于直接集成的 MCP 兼容客户端Shell / 命令行本地文件系统MCP Server
典型场景
同时使用 Claude Code、Codex 和 Cursor 的开发者,希望各客户端读取同一套编码偏好、质量标准与经验。
不适合
  • 需要加密所有本地记忆文件的团队
  • 需要经过加密认证的调用方隔离的组织
  • 只想保存单次任务历史、而非用户身份知识的人
维护状态
近 30 天有提交最近提交 2026-11-08最新版本 v4.27.0(2026-11-01)

这个 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 与语义向量结合的跨语言检索。

  1. 同时使用 Claude Code、Codex 和 Cursor 的开发者,希望各客户端读取同一套编码偏好、质量标准与经验。
  2. 经常开启新对话的工程师,希望通过 get_user_context 或 get_resume_brief 减少重复说明背景。
  3. 架构师需要长期保存决策、被否决方案及原因,并在后续项目中检索决策链。
  4. 维护重复发布或部署流程的团队,希望从会话中生成待审阅的 Playbook,并记录执行结果。
  5. 重视数据主权的个人用户,希望记忆保存在可直接检查、编辑、备份和迁移的本地文件中。
  6. 需要在不支持 MCP 的 ChatGPT、Gemini 或 Kimi 中复用工作身份的用户,可导出并粘贴 Markdown 身份卡。

安装与配置要点

摘自下方的安装和使用说明,以项目 README 的最新说明为准。

安装 / 启动命令
  • pip install piia-engram
  • pip 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?

FollowAgents 源码审查 · FARS-2.1
表现良好
77/ 100 五分制 3.9 / 5
信任安全 21/29
可靠稳定 8/14
适用触发 15/18
规范维护 16/18
有效结果 10/13
证据核验 7/8
查看各维度的扣分理由
信任安全21 / 29 · 3.6/5

文档明确说明数据存于本地 JSON/Markdown、默认明文、每日匿名使用信号及关闭方式;安全策略和遥测说明交代载荷、目的地、可选网络读取与本地审计。setup 展示将改动的配置并确认、备份;但低/中风险知识会自动验证,默认遥测仍会发送,且敏感字段加密为可选,因此未满分。

可靠稳定8 / 14 · 2.9/5

CI 配置显示多版本 Python 测试、额外依赖测试和依赖审计步骤,CLI 也说明传输失败、迁移失败时如何处理;但 README 的技能说明称长期知识需用户审核,quickstart 则称低/中风险项目立即自动验证,形成产品行为描述不一致,因此自洽性扣分。静态材料不能确认实际测试结果。

适用触发15 / 18 · 4.2/5

面向多种 MCP 编码工具和跨会话记忆,提供核心/高级工具分层、非 MCP 身份卡及客户端证据等级;技能触发语句具体,也明确普通编码任务不应调用。部分工具仅为预期兼容或证据待补,且主要流程面向本地 Python/MCP 环境,故环境适配未满分。

规范维护16 / 18 · 4.4/5

文档按快速开始、集成、隐私、治理和运维分层,安装步骤、FAQ、限制及双语说明充分;许可证文件与包元数据一致。版本号可见且有发布检查,但所给材料未提供清晰的维护者个人/组织责任与变更日志,相关分数保守。

有效结果10 / 13 · 3.8/5

产品把可编辑的身份、经验和决策跨工具提供给 AI,提供检索、恢复和导出等明确用途,边际价值描述具体。收益依赖客户端主动调用和本地配置,且额外工具与向量搜索带来设置和依赖成本,因此成本收益评分为中等。

证据核验7 / 8 · 4.4/5

README 对能力等级、遥测、加密、网络调用和验证边界有较细的文档指引;CI 文件列出测试和声明同步门。多处说明仍属于仓库自述,且本次材料未包含相应运行产物或完整源码来交叉核验,故跨来源印证未满分。

风险与缓解建议
  • 默认每日发送包含随机安装 ID、版本、系统、Python 版本、客户端名称和日期的匿名遥测;禁用前应查看遥测状态与预览。
  • 本地记忆默认是明文文件;支持字段级加密需额外安装并配置密钥,而且不覆盖整个存储。
  • 低/中风险写入自动验证与“用户决定永久知识”的技能描述不完全一致;采用前应确认当前审批策略。
证据充分度:低 评估于 2026年11月8日 审查版本 2ab0cb645635 评估后仓库已有新提交,评分可能未覆盖最新改动
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/piia-engram.svg?lang=zh)](https://followagents.com/zh/agents/piia-engram)
<a href="https://followagents.com/zh/agents/piia-engram"><img src="https://followagents.com/badge/piia-engram.svg?lang=zh" alt="FARS 评测"></a>

最近版本

来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。

  1. v4.27.0
    发布说明摘录
    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 查看 ↗
  2. v4.26.0
    发布说明摘录
    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 查看 ↗
  3. v4.25.0
    发布说明摘录
    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 查看 ↗

常见问题

使用它是否需要付费模型或云账户?
不需要。项目以 AGPL-3.0 发布,个人本地使用没有订阅要求;身份和知识工具默认使用本地文件,也不要求模型 API 密钥。
数据是否默认加密?
不是。默认存储是明文 JSON 和 Markdown。安装 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 能否直接连接同一份记忆?
来源只记录了 Markdown 身份卡回退方式:用 get_identity_card 导出后粘贴到 ChatGPT。它不是与 MCP 客户端相同的实时本地连接。
Piia Engram 开源吗?
开源。源码在 GitHub(Patdolitse/piia-engram),许可证是 AGPL-3.0。AGPL-3.0 是传染性(copyleft)许可证,而且覆盖网络使用:把修改后的版本作为服务提供给别人用,也要向用户提供源码。
Piia Engram 安全吗?
FollowAgents 的 FARS 评审(2026年11月8日)给 Piia Engram 的“信任与安全”打了 21/29 分。评审检查的 8 项安全措施没有完全缺失的。评审之后仓库已有更新。
Piia Engram 还在维护吗?
在维护。GitHub 上最近一次提交是 2026-11-08,在最近 30 天内。最新版本是 v4.27.0(2026-11-01)。
Piia Engram 是谁开发的?
Piia Engram 由 GitHub 账号 Patdolitse 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念