适合谁
- 同时使用多个支持 MCP 的 AI 编码工具、厌倦反复自我介绍的开发者。
- 希望记忆与身份数据留在本机、可自行查看编辑备份的用户。
- 需要长期沉淀质量标准、架构决策与技术教训的个人开发者或小团队。
- 需要在会话/工具切换间保持续接性的"氛围编程"工作流。
- 愿意接受人工确认门控以换取本地数据主权的用户。
P
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 编码工具、重视本地数据主权并愿意人工确认的个人开发者；不适合需要团队共享、企业级支持或商业许可的场景。
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 官方出品。
工具能力
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
查找与当前项目相关的知识。
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
维护者反馈：生成匿名聚合反馈报告。
安装接入
方式一（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 反向代理之后。
claude_desktop_config.json
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"]
}
}
}
选型与风险
不适合谁
- 需要多人协作、团队共享记忆或服务端集中管理的场景（本项目面向个人身份层）。
- 需要官方厂商 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 与令牌，身份数据可能暴露。
常见排障
- 升级后客户端报"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`。
使用场景
在 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 (Markdown identity card)部分支持