Piia Engram

社区

本地优先、可查看可编辑可覆盖的 AI 工作身份层，跨 MCP 编码工具通用。

分类: 开发工具第 133 / 438
Stars: ★ 162 非常热门
传输方式: stdio（本地进程） · SSE
运行环境: Python 3.10+
凭据: 无需凭据
许可证: AGPL-3.0
最近提交: 14 天前
工具数: 58

59FMRS · C

Piia Engram 是一个本地优先的 AI 工作身份与记忆层，由个人开发者主导的开源项目（AGPL-3.0），并非 Anthropic 或 MCP 官方出品。它的定位清晰且刻意与代理任务记忆库（Mem0、Zep、Letta）区分：存的是"你是谁"——身份、偏好、质量标准、经验教训与关键决策，而不是某次任务的会话历史。数据以明文 JSON/Markdown 存放在本机 ~/.engram/，默认无网络调用，可自行查看、编辑、备份与迁移。默认加载 19 个核心工具，ENGRAM_TOOLS=all 可解锁共 59 个；写入有分级治理与暂存确认机制，高风险内容必须人工批准，也可用严格模式门控全部写入。跨工具连续性有可验证的证据路径（Claude Code 写入、Codex 读取的实测证明与合成 MCIC 基准），且提供只读的 Memory Lens / preview 让你先看清 AI 实际会收到什么。值得注意的边界也很诚实：默认明文存储、调用者身份依赖环境变量而非强认证、治理层是本地策略而非硬化沙箱，官方也明确建议不要存放密钥或客户 PII。适合同时使用多个 MCP 编码工具、重视本地数据主权并愿意人工确认的个人开发者；不适合需要团队共享、企业级支持或商业许可的场景。

最强项 · 安装易用性 14/20 最弱项 · 可靠性 10/20

可靠性

10/20

安全与权限

12/20

维护活跃度

12/20

文档质量

11/20

安装易用性

14/20

查看各项评分依据

可靠性 10/20: 静态材料显示服务器通过 PyPI 包 piia-engram 提供 stdio 传输的控制台脚本 piia-engram-mcp，manifest 明确指定了 --transport stdio 与固定版本 4.20.0，安装路径清晰，冷启动声称 <100ms 且无网络调用，理论上握手可行。但本次未执行任何代码，README 自身承认存在内部矛盾：工具数量在 59 / 19+40 / 18 / 18+40 之间反复切换（Core 表头写“18 tools”而清单中列出 19 项，正文又写“19 Tier-1 Core”），manifest 声明 prompts/resources 均为 0，功能面描述与实际可能不一致；同时缺少可核验的 CI 工作流文件与已提交测试内容作为证据，因此无法判断异常路径与错误处理是否受控。按静态校准上限，可靠性不得超过 12，考虑到工具面自相矛盾、无执行证据，给予 10。
安全与权限 12/20: 安全方面证据较完整：数据默认仅存于本地 ~/.engram/ 的 JSON/Markdown，身份与知识工具默认零网络调用，遥测默认关闭且需显式 opt-in 且仅发送计数；远程 SSE 部署示例使用 ENGRAM_AUTH_TOKEN 占位符而非真实令牌，示例中未出现真实凭据，默认绑定 127.0.0.1 并建议 HTTPS 与 CORS 限制。风险侧可见部分也已披露：高风险的凭据、shell 命令、MCP 配置、权限规则写入默认进入 staging 需人工确认；导出/导入在开启 ENGRAM_GOVERNANCE 时为 owner-gated；可选 AES-256-GCM 字段级加密为 opt-in。扣分点在于：低/中风险写入默认自动吸收（非严格模式），治理依赖 MCP 环境变量提供调用方身份而非密码学认证，README 自认任何能读取 ~/.engram/ 的进程均可读取数据，且 playbook 自动抽取与 wrap_up 默认启用属隐式副作用；这些属于本地策略边界而非硬化沙箱。未触及红线，故不落入 0-4。
维护活跃度 12/20: 维护活跃度信号积极：版本号 4.20.0 明确并注明验证日期，LICENSE 为 AGPL-3.0（manifest 中为 AGPL-3.0-or-later，略有出入但非缺失），README 列出 CI 与 guard-strategic-files 两个 GitHub Actions 徽章、CHANGELOG、CONTRIBUTING.md 与明确的创建者归属，另有版本化工具契约、迁移逻辑与发布证据门禁脚本的描述，作者身份单一且非虚构。扣分点在于：静态材料无法核实 CI 徽章对应的实际工作流内容，仓库无提交历史、发布节奏、依赖更新或安全响应渠道（SECURITY.md 被引用但内容不可见）的一手证据，160 stars 仅作发现信号不予加分，issues 为 0 无法判断响应能力，治理与维护存在依赖单一维护者的集中风险。
文档质量 11/20: 文档体量庞大且分层：包含安装向导、快速上手、按客户端（Claude Code/Cursor/Codex/Claude Desktop）的配置片段、59 个工具的职责表、数据目录结构、CLI 命令清单、信任模型、隐私与对比说明、限制章节与若干 docs/ 引用，安装与客户端配置示例具体可照做，且主动披露了限制（并发写、调用方身份受 MCP 规范阻塞、加密仅字段级、restricted_fields 不等于 ACL）。扣分点在于存在明显自相矛盾：核心工具数在 18/19 与总数 59 之间多处不一致，工具总数列举与 manifest 的 mcp_tools_core 声明不一致；若干 README 中引用的文档（trust.md、comparison.md、context-governance.md、测试与脚本）本身不在提供材料内无法核验；“Expected to work”“Usable”一类未经验证的兼容性表述与证据等级表并存，易造成过度期待；privacy/security/依赖与成本章节缺少可复核的一手证据。
安装易用性 14/20: 安装路径清晰且对主流客户端友好：pip install piia-engram && engram setup 一条命令即可，另提供 uvx --from piia-engram==4.20.0 piia-engram-mcp 的免安装方案，manifest 固定了包版本与运行时参数，显著降低环境漂移；文档给出 Claude Code、Cursor、Codex、Claude Desktop、Windsurf 等客户端的完整 mcpServers JSON 片段，含 python -m piia_engram.mcp_server 的回退写法，并提供 engram doctor / doctor --fix 进行连接排障，安装向导写入外部配置前会备份并需确认。扣分点在于：无可提交/可核验的实际安装执行证据，Python 3.10+ 与可选 extras（remote、secure、vector、reader）会增加复杂度，Windows 编码需依赖 PYTHONIOENCODING 提示，部分国产 IDE 需手动粘贴配置，且未说明多平台的具体差异。按静态校准上限，安装易用性不超过 15。

静态评测 · 未实际运行收录于 2026-09-10

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件访问网络

适合谁

同时使用多个支持 MCP 的 AI 编码工具、厌倦反复自我介绍的开发者。
希望记忆与身份数据留在本机、可自行查看编辑备份的用户。
需要长期沉淀质量标准、架构决策与技术教训的个人开发者或小团队。
需要在会话/工具切换间保持续接性的"氛围编程"工作流。
愿意接受人工确认门控以换取本地数据主权的用户。

不适合谁

需要多人协作、团队共享记忆或服务端集中管理的场景（本项目面向个人身份层）。
需要官方厂商 SLA、企业级支持或商业许可的用户（AGPL-3.0，无独立商业许可）。
希望存放密码、API 密钥或客户 PII 的用户——官方明确建议不要这样做。
把"代理任务记忆/会话历史"作为主要需求、并已选择 Mem0/Zep/Letta 等专用方案的用户。
不完全信任本地明文 JSON、又需要强访问控制的场景：restricted_fields 与治理层并非加密或真正 ACL。

所需权限

读写本地 Engram 数据目录（默认 ~/.engram/）下的 JSON/Markdown 文件。
在 engram setup 中经你确认后，写入 AI 客户端的 MCP 配置与指令文件（写入前会备份，拒绝则不写入）。
默认启用本地审计日志 ~/.engram/audit.log（仅本地，可用 ENGRAM_AUDIT=0 关闭）。
可选：read_web_content 会抓取你提供的 URL（内置读取器或本地 sidecar）。
可选：ENGRAM_TOOLS=all 会向模型暴露全部 59 个工具，包括所有者/管理级导出、导入与信任管理接口。
可选：远程 SSE 模式需要 ENGRAM_AUTH_TOKEN，并建议由 TLS 反向代理保护。
可选：遥测默认关闭；开启远程遥测/反馈需显式选择加入，且只发送计数。

风险与副作用

数据默认以明文 JSON/Markdown 存放，任何能读取 ~/.engram/ 的进程都可读取你的数据；字段级加密为可选项而非默认。
官方明确提示不要在 Engram 中存放密码、API 密钥或客户 PII。
restricted_fields 只减少冷启动上下文中输出的字段，并不等于加密或真正的访问控制。
调用者身份由 MCP 环境变量提供，而非密码学认证，因此治理层是本地策略边界，不是强化的沙箱；MCP 协议本身不传递工具身份。
导出文件（export_engram、get_identity_card、export_knowledge_report）包含完整或大范围内容，应按敏感文件对待。
import_engram 会写入本地存储，务必先用 dry_run=True 预览；正式应用需要显式 --apply --yes。
并发写依赖文件锁与原子替换，网络文件系统的边界情况不受保证。
自动 Playbook 抽取在存入前会做敏感信息脱敏（密钥、令牌、绝对路径、邮箱），但草稿仍需人工确认后才可信。
远程部署若未正确配置 HTTPS 与令牌，身份数据可能暴露。

安装接入

准备工作

运行环境：Python 3.10+

ENGRAM_SECRET 可选密钥可选字段级加密（AES-256-GCM）的本地口令，由用户自行设定，需先安装 piia-engram[secure]。

ENGRAM_AUTH_TOKEN 可选密钥远程 SSE 模式的 bearer 令牌，用 secrets.token_urlsafe(32) 自行生成。

其他可选配置项（10 个）

ENGRAM_MCP_STARTUP_SYNC 可选控制 MCP 启动时的本地同步行为；设为 off 可跳过启动同步，background 为默认。

ENGRAM_TOOLS 可选控制暴露的工具面；默认 core（19 个），设为 all 启用全部 59 个高级工具。

PYTHONIOENCODING 可选在 Windows 风格控制台上强制 UTF-8 stdio 帧，设为 utf-8。

ENGRAM_APPROVAL 可选写入审批策略；设为 strict 时所有写入都需人工确认。

ENGRAM_SEARCH 可选搜索模式；设为 hybrid 启用 FTS5+向量混合检索（需 pip install "piia-engram[vector]"）。

ENGRAM_GOVERNANCE 可选启用按调用者信任等级的治理层，设为 1 开启。

ENGRAM_CLIENT_TYPE 可选治理开启时声明调用者身份，例如 claude_code。

ENGRAM_AUDIT 可选本地审计日志开关，设为 0 关闭 ~/.engram/audit.log 记录。

ENGRAM_EPHEMERAL 可选容器/临时客户端设为 1 时跳过启动同步和迁移。

ENGRAM_CORS_ORIGINS 可选远程部署时限制跨域来源，例如 https://your-domain.com。

方式一（pip）：运行 pip install piia-engram && engram setup。安装向导会检测你的 Python 环境，让你选择 Engram 数据目录，检测已安装的 AI 工具并列出将要改动的具体配置文件，在你按一次键确认后才写入 MCP 连接（每次写入前都会先备份；拒绝则不改动任何文件），随后引导你填写角色、技术栈、语言等种子知识，并可导入已有的 CLAUDE.md / .cursorrules 规则，最后预览你的 AI 身份卡。

方式二（uvx，免安装）：在客户端配置中使用 uvx --from piia-engram piia-engram-mcp。

客户端配置示例（Claude Desktop / 通用 MCP over stdio）：

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

Cursor 配置文件为 ~/.cursor/mcp.json，Codex 为 ~/.codex/mcp.json，Claude Desktop 为 claude_desktop_config.json。Claude Code 也可用 claude mcp add piia-engram -- piia-engram-mcp。

非交互/CI 场景可用 engram setup --apply-external-config 跳过确认提示（仍会备份）。安装后重启 AI 工具，然后运行 engram doctor 验证连接。

可选环境变量：ENGRAM_TOOLS=core|all（默认 core，暴露 19 个核心工具；all 解锁全部 59 个）、ENGRAM_MCP_STARTUP_SYNC=off|background|eager（默认 off，背景模式用于本地跨工具同步）、PYTHONIOENCODING=utf-8（Windows 控制台 UTF-8）。

远程部署：pip install piia-engram[remote]，生成令牌后以 ENGRAM_AUTH_TOKEN=... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767 启动 SSE 模式，客户端用 url + Authorization: Bearer 头连接，生产环境务必置于 TLS 反向代理之后。

.mcp.json

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "piia-engram": {
      "command": "python",
      "args": [
        "-m",
        "piia_engram.mcp_server"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add piia-engram -- python -m piia_engram.mcp_server

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

运行 engram doctor 确认配置的工具显示为已配置且健康；在客户端工具列表中应出现 piia-engram 的工具（如 get_user_context），调用它应返回你的身份与知识上下文。

常见排障

升级后客户端报"MCP server disconnected"：运行 `engram doctor --fix` 后重启 AI 工具（会扫描已知 MCP 配置、清理过时条目并修复路径）。
安装后不确定是否连上：运行 `engram doctor` 查看已检测工具、存储健康度与当前能力模式；`engram capabilities --json` 可输出机器可读能力码与契约版本。
想确认 AI 实际会拿到什么：运行 `engram preview --as automation`（--html 生成页面），只读、不发送任何数据。
想收窄工具面：设置 ENGRAM_TOOLS=core 或组合能力组，再运行 engram doctor 确认报告的核心工具面符合预期。
启动过慢或用于测试环境：设置 ENGRAM_MCP_STARTUP_SYNC=off 跳过启动同步；ENGRAM_EPHEMERAL=1 也可在容器/临时客户端中跳过启动同步与迁移。
Windows 控制台出现编码错误：设置 PYTHONIOENCODING=utf-8；出现乱码文本可用 `engram repair-encoding` 先干跑扫描，再 `--apply` 带备份修复。
升级前想确认该备份什么：运行 `engram backup-plan` 获得仅元数据的复制清单（只覆盖 Engram 目录，绝不触碰项目文件夹）。
想看跨工具续接是否就绪：运行 `engram continuity`（仅元数据，不打印记忆正文或本地路径）。
想排查隐私与遥测：`engram privacy`、`engram telemetry preview`、`engram telemetry off`、`engram telemetry remote off`。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

帮我记住这条经验：重构时要把认证中间件和业务逻辑分开
搜索一下我以前关于 pytest 覆盖率标准的记录
在会话结束前总结这次改动的要点并保存
给我看看这份知识库的健康报告和过期条目

工具能力 58

get_user_context 只读

启动工具：在会话开始时加载身份与知识（支持 token_budget 控制上下文大小）。

wrap_up_session 写入

会话结束工具：保存洞察并在会话结束时同步。

memory_store 写入

统一写入端点：按 kind 路由到 add_lesson / add_decision / add_playbook。

add_lesson 写入

存储一条可复用的经验教训。

add_decision 写入

记录一项关键决策及其理由。

add_playbook 写入

记录一个操作型 Playbook（带触发关键词的多步骤流程）。

search_knowledge 只读

检索工具：搜索经验教训、决策与 Playbook（支持 filters_json 按领域/层级/日期过滤）。

get_relevant_knowledge 只读

查找与当前项目相关的知识。

展开其余 50 个工具

get_recall 只读

返回一个结构化召回载荷：身份 + 近期活动 + 相关知识。

get_knowledge_history 只读

读取某条目的修订历史（被取代的快照；支持按版本精确查询）。

get_identity_card 写入

所有者门控导出：写出并返回一份供非 MCP 工具使用的 Markdown 身份卡。

update_identity 写入

更新个人资料、偏好或质量标准。

get_project_context 只读

读取已保存的项目快照。

save_project_snapshot 写入

持久化项目状态，供后续会话使用。

get_recent_context 只读

在重启后恢复丢失的会话上下文。

get_daily_log 只读

读取某一天的人类友好型项目时间线。

get_resume_brief 只读

构建跨会话、跨工具的续接简报。

doctor 只读

运行记忆系统自检诊断。

register_tool 写入

可选本地集成（受治理写入）：把本地工具、运行时或 CLI 注册进环境地图。

find_tool 只读

可选本地集成：按名称查找已注册的本地工具。

list_tools 只读

可选本地集成：列出已注册的本地工具（可按类别过滤）。

save_agent_context 写入

保存 AI 会话检查点（也会自动运行）。

list_agent_sessions 只读

浏览跨工具保存的会话记录。

refresh_quick_context 写入

刷新本地 quick_context.md 快照，供离线/跨工具使用。

get_identity_facets 只读

按 facet 读取身份切片：profile、preferences、trust_boundaries、work_style、quality_standards、domains 或 all。

user_portrait 只读

action：获取 / 保存 / 对比 AI 维护的用户画像。

preview_context_governance 只读

高级所有者门控预览：生成安全上下文、新鲜度/冲突、回放或证据提案，但不实际应用变更。

get_playbooks 只读

按 mode 读取 Playbook：list、get（完整内容）、recent、management（含归档/删除元数据）。

manage_playbook 写入

按 action 管理 Playbook 生命周期：update、archive、delete、restore（变更需确认门控）。

playbook_execution 只读

按 action 引导执行：生成步骤计划、update_step、状态汇总（仅被动参考，不自动执行）。

get_lessons 只读

列出可复用的经验教训。

get_decisions 只读

列出关键决策；thread_seed_id / history_question 可重建决策线程与修订历史。

get_knowledge_inheritance 只读

构建跨项目知识起步包。

list_projects 只读

列出已保存的项目快照。

extract_session_insights 写入

从会话文本中提取并存储经验教训与决策。

ingest_notes 写入

把自由格式笔记解析为结构化知识。

update_knowledge 写入

按 ID 更新某条经验教训或决策。

archive_knowledge 写入

按 ID 归档某条经验教训或决策。

confirm_knowledge 写入

仅所有者可用的确认标记，来源可为人工、测试或锚点。

onboard_repo 写入

仅所有者可用：扫描代码仓库，依据锚点创建暂存的仓库事实候选。

onboard_accept 写入

仅所有者可用：校验候选锚点并提升为已验证。

check_anchors 只读

仅所有者可用：对已有锚点支撑的事实做重新校验。

merge_knowledge 写入

把重复条目合并到主条目。

manage_relation 写入

action：link / unlink —— 管理知识条目之间的类型化关系（决策线程）。

explore_knowledge 只读

按 mode 做知识图谱探索：related、similar、merge_candidates。

get_knowledge_overview 只读

知识摘要、健康报告与过期检查。

get_stale_knowledge 只读

列出需要复查的条目。

review_staging 写入

暂存复查中心，按 action：列出待处理项、批量决策、review_item、应用文本复查结果。

export_knowledge_report 写入

所有者门控导出：写出可读的 Markdown 知识报告。

request_outline_review 写入

所有者门控导出：生成交互式本地 HTML 复查页面。

export_engram 写入

所有者门控导出：写出完整备份（format="openclaw" 时输出 OpenClaw 兼容文件）。

import_engram 写入

所有者/管理员导入：先用 dry_run=True 做仅元数据的合并/冲突预览（支持 format="openclaw"）。

read_web_content 只读

抓取用户提供的 URL：优先使用本地 sidecar，否则使用内置独立读取器（需 pip install "piia-engram[reader]"）。

get_audit_log 只读

获取最近的审计日志条目。

start_project 写入

在继承已有知识的情况下启动一个项目。

get_permission_profile 只读

查看所有调用者的信任等级与访问边界。

manage_caller_trust 写入

所有者/管理员 action：授予或撤销某调用者的信任等级。

export_feedback_report 写入

维护者反馈：生成匿名聚合反馈报告。

使用场景

在 Claude Code、Codex、Cursor 等多个 MCP 编码工具之间共享同一份身份、偏好与经验教训。

让每次新开的 AI 会话从同一份已确认的上下文出发，而不是从零开始。

把架构决策连同"选了什么、排除了什么、为什么"记录成可查询的决策档案。

描述新项目后用 get_knowledge_inheritance 获得来自历史项目的相关知识起步包。

把会话总结粘贴进 extract_session_insights，被动积累经验教训，无需手工记笔记。

用 get_identity_card 导出 Markdown 身份卡，粘贴到 ChatGPT/Gemini/Kimi 等不支持 MCP 的工具中。

把重复的多步骤流程（发版、部署、发布注册表）自动草拟为 Playbook 并在下次复用。

记录本机已安装的运行时与 CLI（register_tool / find_tool），避免每次会话重复搜索环境。

通过 get_knowledge_overview、explore_knowledge、manage_relation 做知识健康度检查、去重与图谱关联。

在自建服务器上以 SSE 模式运行，实现远程接入（带 Bearer 令牌）。

支持客户端

Claude Code

Codex

Cursor

Claude Desktop部分支持

Hermes

OpenClaw部分支持

Windsurf部分支持

GitHub Copilot部分支持

Cline部分支持

Roo Code部分支持

Amazon Q部分支持

Augment部分支持

Zed部分支持

Trae部分支持

Tencent CodeBuddy部分支持

ChatGPT / Gemini / Kimi部分支持

依据项目文档列出，未经本站实测。

详细介绍

Piia Engram 是一个本地优先的 AI 工作身份与记忆层，面向支持 MCP 的编码工具（Claude Code、Codex、Cursor、Windsurf、Claude Desktop 等）。它把"你是谁、你如何工作、什么算好"一次性写清楚，让多个 AI 工具从同一份你拥有的上下文出发：身份、偏好、质量标准、代码评审门槛、经验教训、关键决策与项目快照，全部以 JSON/Markdown 明文存放在本机 ~/.engram/ 目录下，无需云端账号，也没有你无法检查的隐藏记忆。

它刻意区别于 Mem0、Zep、Letta 这类代理任务记忆库：那些工具保存"任务过程中发生了什么"，Piia Engram 保存"做事的人是谁"——属于使用者本人的身份与经验层。默认加载 19 个核心工具（Tier-1），设置 ENGRAM_TOOLS=all 可解锁全部 59 个工具（含知识管理、治理、导入导出等）。

写入采用治理模型：AI 只能本地写入，高风险内容（凭据、shell 命令、MCP 配置、权限规则）进入暂存区等待人工确认，低/中风险写入自动吸收但完全可审计、可回滚；设置 ENGRAM_APPROVAL=strict 可让所有写入都需确认。其他特性包括：跨项目知识继承、会话洞察自动提取、Playbook 自动草稿（检测多步骤流程后生成草稿，必须由你确认才会成为可信 Playbook）、本地工具注册表、知识健康度与去重、可选混合检索（FTS5 + 语义向量，默认关闭）、可选字段级 AES-256-GCM 加密与本地审计日志。

默认情况下身份与知识工具不产生任何网络调用（可选的 read_web_content 除外）；遥测默认关闭，远程遥测与反馈需另行显式选择加入且只发送计数。项目采用 AGPL-3.0 许可，由 @Patdolitse 主导、Claude Code 与 Codex 协助开发，属于社区开源项目而非 Anthropic 或 MCP 官方出品。