Piia Engram

Piia Engram

本地优先的 AI 工作身份，你可以查看、编辑和覆盖，并可在 MCP 编码工具之间移植。

只需告诉 AI 一次你是谁、如何工作，以及你对“优秀”的定义。 Claude Code、Codex、Cursor、Windsurf 和其他兼容 MCP 的工具，都可以从同一个 AI 工作身份层开始工作——它由你拥有的本地文件构成，无需云账户，也没有无法检查的隐藏记忆。

安装 · 查看演示 · 支持的工具 · MCP 工具 · 常见问题

ENGLISH | 中文

收录于：

另收录于：awesome-agents · Awesome-MCP-ZH · mcpservers.org · Cursor Directory · ModelScope · PulseMCP

简而言之： piia-engram 是一个本地优先的个人 AI 身份层。它帮助多个编码 Agent 基于对你的同一套认知开始工作：包括你的偏好、质量标准、经验教训、决策和项目上下文。它不是 Agent 记忆数据库，而是位于工具之上的、由用户拥有的层。

为什么不直接使用原生记忆？ Claude Code、Codex、Cursor 和 Windsurf 都在添加各自的记忆和规则。这些功能很有用，但仅适用于单个工具或工作区。piia-engram 为你提供了位于它们之上的一个可移植身份层：由你拥有的本地文件、经你审核的 AI 提议知识，以及能随你在不同工具间迁移的上下文。

四行说明信任模型：

• 无需云账户： 使用 pip 安装，将核心存储保留在本机。
• 本地文件： 身份和知识以 JSON/Markdown 格式存储在 ~/.engram/ 下。
• 用户审批： AI 在本地写入；高风险条目（凭据、shell 命令、MCP 配置、权限规则）会等待你审核，低风险和中风险写入则会自动吸收，但全程可审计且可撤销。设置 ENGRAM_APPROVAL=strict 可要求审批每次写入。“已验证”表示经你或按该策略接受，并非根据你当前的代码重新检查。
• 会话连续性： 恢复输出也可能包含较早的会话记录（检查点和快照），这些记录未经审核，也不授权执行操作。关于审批和审核的声明适用于按已配置策略管理的身份和长期知识。
• 明确的边界： 请参阅信任模型、隐私和安全。

想看证据？请查看实时跨工具连续性证明——Claude Code 写入的记忆由 Codex 通过同一个本地存储读回；也可以查看只需一条命令的可复现代码演示。

实际效果

You  → "Help me refactor this auth module"

# WITHOUT piia-engram: AI starts from scratch
AI   → "What language? What framework? What's your testing preference?"

# WITH piia-engram: AI can load your approved identity and long-term knowledge
AI   → "Based on your preference for pytest + 90% coverage, and your
        lesson about always separating auth middleware from business
        logic (from the March incident), here's my approach..."

你无需盲目相信——Memory Lens（engram preview --html）会准确展示任何 AI 调用方将收到的内容，以及治理机制拦截的内容，让你在发送任何内容之前一目了然：

上图：来自演示存储的实际报告——公开了 4 个条目；一条未经审核的暂存说明和一条包含凭据的经验已被拦截，秘密内容显示为 [REDACTED]。

安装

pip install piia-engram && engram setup

向导会自动检测你的 AI 工具——Claude Code、Cursor、Codex、Claude Desktop，列出将要修改的确切配置文件，并在你按一次按键确认后写入 MCP 连接（每次写入前都会先备份；拒绝后不会有任何更改）。向导会预览你的身份卡，然后你重启已配置的工具；首次对话可通过启动或搜索工具加载你已批准的身份和长期知识。（完整操作指南 ↓）

让你的 AI Agent 安装

让你的编码 Agent 安装 Engram，并在应用计划前检查计划内容：

pip install piia-engram
engram setup --non-interactive --json
engram setup --non-interactive --apply
engram doctor --json

设置过程不会提问。使用 --clients cursor,codex 可限定客户端，使用 --lang zh|en 可设置输出语言（默认为 en）。不带 --apply 时，计划模式 不会向 Engram 存储、主目录或客户端配置写入任何内容。Python 本身可能会使用系统临时目录。应用计划时会备份配置并设置 MCP 连接， 保留现有工具模式，且绝不会导入记忆、写入身份或知识，也不会批准提案。重启已配置的客户端；退出代码 1 表示仍需手动操作。Agent 指引请参阅 llms.txt，详情请参阅 CLI 和 JSON 协议。

支持的工具

证据等级遵循 Agent 客户端验证手册：L0 = 发现，L1 = 协议访问，L2 = 读取/搜索行为，L3 = A/B 行为提升，L4 = 跨客户端连续性，L5 = 可复现的公开证据。

数据一览

以下是来自 docs/public-facts.json 的当前仓库事实。公共注册表和软件包徽章仅在发布时更新。

每次切换工具或开始新对话，你的 AI 都会忘记你。 piia-engram 解决了交接问题。

每次打开新的对话窗口、从 Claude Code 切换到 Codex、更新 AI 工具，或转到另一个项目时，你都会回到起点：

• 你的沟通偏好——消失了
• 你的代码标准和质量要求——被忘记了
• 你已经吸取教训的错误——丢失了
• 你上个月做出那个架构决策的原因——被抹去了

这是因为如今 AI 的记忆被锁在各个平台中。记忆属于工具，而不属于你。工具更新、重置或被替换时，你的上下文也会随之消失。

piia-engram 为你提供一层存在于你机器上的个人身份信息，不受任何 AI 工具影响。 你只需告诉它一次你是谁、如何工作，以及你学到了什么。兼容 MCP 的工具可以读取同一份经过批准的身份信息和长期知识。新对话、新工具、新版本——你的身份始终可以随身迁移。

piia-engram 不是 Agent 记忆数据库。 Mem0、Zep 和 Letta 等工具会存储 AI Agent 的任务上下文和会话历史。piia-engram 存储的是你作为一个人的样子——你的身份、偏好、来之不易的经验和关键决策。这是不同的一层：它记录的不是任务中发生了什么，而是每项任务背后的你是谁。

为什么选择 piia-engram？

谁在使用 piia-engram

piia-engram 面向使用多种 AI 编码工具、厌倦了反复介绍自己的开发者。

如果你在 Claude Code、Codex 和 Cursor 之间切换——每次切换，你的代码规范、架构决策和来之不易的经验都会重置。piia-engram 让每种工具都能基于对你的共同了解开始工作。

如果你每周会打开 10 个以上的 AI 聊天窗口——每个窗口都会从零开始。piia-engram 让每次对话都能基于相同的、经过确认的身份信息和知识上下文开始。

如果你在工具更新后丢失过偏好设置——你的身份信息保存在自己的设备上，而非任何平台中。更新、重置和迁移都不会影响你的记忆。

piia-engram 存储的内容

所有数据都以纯 JSON 和 Markdown 文件的形式保存在 ~/.engram/ 下，你可以自行打开、编辑、备份或迁移。

• 身份信息：你是谁、如何沟通、偏好使用哪些语言
• 质量标准：你的代码审查标准、测试覆盖率要求，以及你拒绝发布的内容
• 偏好设置：编码风格、AI 行为，以及你喜欢的解释方式
• 信任边界：哪些字段应保密、哪些工具可以访问
• 项目快照：正在进行的工作的上下文，可捕获并重新加载
• 经验教训：错误、意外发现，以及行之有效或无效的做法
• 关键决策：你选择了什么、排除了什么，以及为什么
• 领域知识：可在不同项目和工具间复用的见解

piia-engram 的功能（不止于存储）

大多数记忆工具都是被动的——你把内容放进去，它们再把内容还给你。piia-engram 也能主动工作。

跨项目知识继承
用纯文本描述一个新项目。get_knowledge_inheritance 会从你以往参与的所有项目中，精选并返回最相关的经验教训和决策，作为入门资料包。只需调用一次工具，你的第十个项目就能受益于前九个项目的积累。

被动知识捕获
将会话摘要粘贴到 extract_session_insights，piia-engram 就会提取并存储其中的经验教训和决策。无需手动记笔记。知识会在正常的 AI 对话中不断积累。

适用于不支持 MCP 的工具
ChatGPT、Gemini、Kimi——get_identity_card 会导出一份可直接粘贴的 Markdown 身份卡片。即使工具无法直接连接，你的上下文也能随之传递。

自动提取操作手册
完成多步骤工作流——发布到 PyPI、部署到 Cloudflare、发布到 MCP Registry——piia-engram 会在会话结束时检测到它。它会生成一份结构化的操作手册草稿（步骤、注意事项、触发关键词），并保存到暂存区。下次执行相同任务时，AI 可以检索已确认的操作手册作为被动参考，陪你逐步完成，并记录结果。无需手动记录——Engram 会创建草稿，由你确认，宿主 AI 则负责跟进。参见下文的操作手册自动提取。

本地工具注册表
AI 工具经常需要查找本地程序、运行时和 CLI。register_tool 会记录已安装的内容及其位置；find_tool 可立即检索。无需每次会话都运行 which python——环境映射会在不同工具和对话间持续保留。

知识健康状况与探索
get_knowledge_overview 会显示过时的经验教训（超过 30 天未复核），从四个维度（时效性、质量、覆盖度、整洁度）计算 0–100 分的健康评分，并标出值得重新审视的空白。explore_knowledge 会扫描你的知识库，查找近似重复项（并遍历相关或相似条目），同时提供可执行的合并命令。manage_relation 可将相关的经验教训和决策关联起来，构建可导航的知识图谱。

混合搜索（可选，默认关闭）
默认的关键词搜索保持不变。你可以选择启用混合检索——FTS5 全文搜索加语义向量层——以支持跨语言召回，例如通过英文查询找到中文笔记：运行 pip install "piia-engram[vector]" 并设置 ENGRAM_SEARCH=hybrid，或者让 engram setup 通过一次按键启用。索引是可重建的 SQLite 文件；你的 JSON 存储仍是唯一事实来源。参见 docs/hybrid-search.md。

快速开始

pip install piia-engram
engram setup

刚开始使用 piia-engram？请参阅更完整的首次价值快速入门指南，了解如何仅使用默认的 19 个核心工具，完成安装 -> 创建第一条记忆 -> 在新会话中回忆；也可以参阅完整的用户指南，了解安装 -> 实现首次价值 -> 跨工具连续性 -> 治理 -> 隐私 -> 常见问题。针对特定宿主的设置说明卡见 Claude Code、Codex 和 Cursor。如需仅生成提案的安全上下文、回放、时效性/冲突和证据草稿，请参阅上下文治理。

设置向导将：

1. 检测你的 Python 环境
2. 让你选择 Engram 数据文件夹（~/.engram、其他驱动器或自定义路径）
3. 检测你的 AI 工具，列出将修改的确切配置文件，并在你按一次按键确认后写入 MCP 连接（事先备份；拒绝则不会修改）
4. 引导你填写种子知识（角色、技术栈、语言）
5. 提议从其他 AI 工具导入规则和记忆——CLAUDE.md、.cursorrules、记忆文件（默认为否；会先列出文件，再显示审核队列，通过 engram review 批准）
6. 显示简短的每日使用提示；两种设置模式都不会询问遥测，也不会更改你的选择
7. 预览你的 AI 身份卡——立即展现价值

设置向导写入 MCP 连接后（会先提示你确认），请重启 AI 工具。许多客户端可以在启动时调用 get_user_context；如果宿主不会主动调用，仍应通过显式调用 search_knowledge 或 get_resume_brief 来使用 L2 路径。

对于非交互式或 CI 运行，可跳过确认提示并直接写入：

engram setup --apply-external-config

无论采用哪种方式，每次写入外部配置前都会将其备份到所选的 Engram 数据文件夹中；拒绝提示则不会修改任何外部配置。

如需通过本地点选进行审核，请打开 piia-engram-review（双击已安装的 Windows 启动器）。审核完整提案并选择批准、拒绝或稍后处理；窗口运行期间还可选择使用不含正文的提示。需要支持 Tk 的 Python；MCP 审批权限保持不变。请参阅本地审核窗口指南。

随时检查运行状况：

engram status        # redacted install + memory health summary
engram status --html # write a local redacted status page
engram preview --as automation  # see exactly what a given AI caller would receive (read-only)
engram continuity    # metadata-only proof that cross-tool handoff is ready
engram management    # metadata-only review/playbook management view
engram doctor        # diagnose all tools
engram doctor --fix  # auto-repair issues + inject missing instructions
engram doctor --days 7 --json  # which AI clients are configured and called Engram lately (read-only)
engram repair-encoding        # dry-run scan for garbled / mojibake text
engram repair-encoding --apply  # repair reversible cases with a backup

engram continuity 仅报告元数据：已保存的会话数量、参与的工具、恢复摘要的就绪状态，以及上下文加载/收尾信号的汇总信息；不会输出记忆正文、原始遥测事件、会话 ID 或本地路径。

如需生成可供机器读取的合成循环证明，请运行：

python demos/cross_tool_continuity_demo.py --json

engram continuity 会报告就绪状态元数据。演示 JSON 仅使用合成数据，证明了一个隔离的写入 -> 恢复 -> 搜索 -> 溯源循环。

回放体验模式

自动化离线和在线评估调用方可以在任一隔离模式下使用 IsolatedStore.admit(..., event_key="source:event:record:v1")，以区分文本相同的事件，并安全地重试同一事件。召回会返回由账本支持的 receipt，其中包含快照标识符、有序 ID、内容哈希和有效筛选条件；verify_recall_receipt 会报告后续变更，但不包含正文。回放调用方还可以提供 effective_at 和 now，以在历史时间点退役或恢复。Owner 否决会使卡片在任何时间都不可见。

在打开存储之前，使用 from piia_engram.isolated_store import require_contract; require_contract("1") 固定隔离存储 API。Contract v1 支持使用 admit(..., supersedes=item_id) 接纳替代项，并在一张完成回执中停用其前任，在两种模式下均支持崩溃安全重试。Family、subject 和完全不透明的 source_decision_point 必须匹配。活动版本会阻止恢复其他版本；回滚会追加一个新版本。召回还会返回并封存一个确定性的 result_sha256，其内容基于有效截断点、排除计数和有序内容引用。不兼容的变更需要使用新的 contract 版本，并继续提供支持，否则返回 contract_version_unsupported；现有账本仍可读取。

按时间顺序重新馈入历史材料的离线回放和评估，可以在启动器配置中使用 "mode": "replay_experience" 初始化隔离存储。根模式不可变。接纳需要带时区的 admitted_before 和 now 参数；召回也需要 now。历史接纳使用提供的时间，但回执保留实际时间戳，并且停用自动同 Family 排除。证据仍止于决策点的 as_of。即使模板相似度很高，回放接纳仍会保留经验证的非相同规范化摘要；精确重复项以及现有的 tombstone、retired 和 archived 双胞胎规则仍然适用。未使用事件键时，生产环境的重复项处理方式不变；所有容量限制仍然适用。回放根可以将 hard_cap 固定为最高 10,000（例如 1,400）；生产根仍保留默认值 1,000。原生备份和返回的条目都带有 store_mode: replay_experience，普通根会拒绝回放根和带标记的导入内容。

这种隔离可防止意外混用，例如使用错误的配置、挂接其他根，或导入未标记的导出内容。新的初始化回执会绑定到目录标识，且上下文文本会保留其回放标记。这并不是针对能够同时编辑两个根及其账本的人员的防篡改边界。在回放模式之前创建的现有生产根，无需启动器配置即可直接挂接。

若要获取更全面的发布证据，请运行合成 MCIC 基准测试：

python demos/mcic_benchmark.py --json

MCIC v1 包含 10 个带有明确用途标签的连续性场景，涵盖显式召回、隐式个性化信号、错误前提防护信号、公开行动边界、版本链 HEAD 选择、阴性对照和溯源。其主张范围有限：Engram 会让下一个客户端获得正确的信号；实时模型是否遵从仍需单独进行 A/B 测试。

信任与证据

piia-engram 将信任声明视为发布产物，而非营销文案：

亲自验证（5 分钟）

不要只相信上表——在自己的机器上运行这些检查：

1. 检查设置——engram doctor 会报告检测到的工具、存储 健康状况和当前能力模式。
2. 查看 AI 所见——engram preview --as automation 会呈现调用方 将收到的确切上下文（只读，不会发送任何内容）。
3. 控制可用范围——设置 ENGRAM_TOOLS=core（或组合多个组），然后 重新运行 engram doctor，确认它报告了预期的核心范围。 请参阅能力模式。
4. 审计数据——按照 数据主权审计操作手册 确认身份和知识数据保留在你的 Engram 根目录下，且外部写入均已明确授权并经过审计。
5. 检查声明——信任证据中的每项信任声明 都对应一项可在本地运行的确定性检查或检查流程。

为你的 AI 工具进行配置

这些代码片段使用服务器名称 engram，这是 engram setup 写入的名称。名为 piia-engram 的条目（来自早期说明）仍可识别；setup 会先备份文件，再将其改为 engram，而不是添加第二个服务器。

# Guided setup; confirms before writing external client configs (backed up first)
engram setup
# Skip the confirmation prompt for non-interactive/CI runs
engram setup --apply-external-config
# Or manual (user scope, available in all your projects):
claude mcp add --scope user engram -- piia-engram-mcp

{
  "mcpServers": {
    "engram": {
      "command": "piia-engram-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

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

[mcp_servers.engram]
command = "python"
args = ["-m", "piia_engram.mcp_server"]

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

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

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

验证配置

完成配置后，运行 engram doctor，验证所有连接是否正常：

$ engram doctor

  Detected 3 AI tool(s):
    [ok] Claude Code — Engram configured
    [ok] Cursor — Engram configured
    [ok] Codex — Engram configured

  [ok] All configured tools look healthy.

  ── Functional Checks ──
    [ok] piia_engram.core importable
    [ok] Engram initialized (~/.engram)
    [ok] Identity loaded (role: Senior Backend Developer)
    [ok] quick_context.md ready (4096 bytes)
    [ok] MCP server: 19 tools registered

  -- Terminal encoding --

    [ok] stdout/stderr: utf-8 / utf-8
    [ok] PYTHONIOENCODING not set (stdout/stderr already UTF-8)
    [ok] Runtime encodings: preferred=UTF-8, filesystem=utf-8

  -- Config Integrity --

    [ok] MCP configs: 3/13 files found, 3 configured
    [ok] Instruction files: 3/4 found, 3 fresh
    [ok] Project rule files: 1 found
    [ok] Shared instructions: 1 found
    [ok] Claude hooks: 4/4 registered
    [ok] Report is metadata-only (hashes + counts; no rule bodies)

  -- Continuity --

    [--] No saved agent sessions yet
         Run an AI session, then wrap up or stop the tool to create one.
    [ok] Resume brief builds (2 section(s))

如需机器可读的兼容性检查，请运行 engram capabilities --json。 该命令会报告稳定的能力代码和契约版本，不会读取用户记忆或项目内容；MCP doctor(output_format="json") 会包含相同的指纹。

升级

pip install --upgrade piia-engram

升级后，piia-engram 会在下次启动服务时（stdio 模式）自动迁移过时的 MCP 配置。如果重启后 AI 工具仍显示“MCP 已断开”错误，请运行：

piia-engram doctor        # show what's wrong
piia-engram doctor --fix  # auto-repair and fix in one step

然后重启受影响的 AI 工具。doctor 命令会检查 Claude Code、Cursor、Codex、Windsurf、Claude Desktop 以及社区支持的 MCP 配置位置，移除过时的服务条目，并输出仅包含元数据的配置完整性摘要。

远程部署

在自己的服务器上运行 piia-engram，并从任何地方连接。

服务端设置

# Install with remote support
pip install piia-engram[remote]

# Generate an auth token
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Save the output, e.g. "abc123..."

# Start in SSE mode
ENGRAM_AUTH_TOKEN=abc123... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767

客户端配置（Claude Code）

{
  "mcpServers": {
    "engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

客户端配置（Cursor）

{
  "mcpServers": {
    "engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

安全说明：

• 在生产环境中始终使用 HTTPS，并通过启用了 TLS 的 nginx 或 caddy 代理。
• 身份数据由身份验证令牌保护。请妥善保密。
• 默认绑定地址为 127.0.0.1，仅供本机使用。只有在反向代理后面才使用 0.0.0.0。
• 设置 ENGRAM_CORS_ORIGINS 以限制跨源访问（例如，https://your-domain.com）。
• 数据保留在你的服务器上，不会接触第三方云服务。

MCP 工具

piia-engram 提供 59 个 MCP 工具。默认情况下，只加载 19 个 Tier-1 Core 工具，以保持 AI 的上下文简洁。Core 指“在大多数会话中使用”，而非“只读”：部分核心工具会写入本地记忆或受所有者权限控制的导出文件，治理层仍会管控这些副作用。每个工具还带有标准 MCP 提示（只读、破坏性、幂等、开放世界），供客户端参考；这些提示仅供建议，并非访问控制，访问控制仍由严格模式和治理层负责。如需查看简明的操作人员指南，请参阅 MCP 速查表。若要启用全部 59 个工具，请在 MCP 配置中添加 ENGRAM_TOOLS=all：

你也可以启用可组合的能力模式，例如知识管理、治理、管理或集成；请参阅能力模式指南。

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

从其他 AI 工具导入： Engram 不会自行读取其他 AI 工具的记忆或规则文件：无论是在服务启动时、冷启动时，还是会话结束时都不会。运行 engram import-memories 即可导入；它会先列出找到的内容（--dry-run 会在此处停止），然后在你确认后将其加入审核队列，并在存储目录中的 import_receipts/ 写入回执。ENGRAM_MCP_STARTUP_SYNC 仍受支持，但已不再执行任何操作；设置 ENGRAM_RECONCILE=0 则会完全关闭对其他 AI 工具文件的读取。ENGRAM_EPHEMERAL=1 会跳过容器或临时客户端的启动配置检查。

MCP 启动时绝不会导入其他工具的记忆，也不会更改知识或身份内容。启动和读取工具仍可能写入会话检查点、使用记录、审计记录和访问元数据；它们并非零写入操作。

Tier-1 核心（19 个工具 — 日常工作流）

Tier-2 高级（40 个工具 — 知识管理、审核、治理、导入／导出）

高级工具包括可选的本地集成、所有者／管理员功能以及维护辅助工具。可导出文件、导入整个存储库、生成审核页面或更改调用方信任度的工具，均属于所有者／管理员／导出功能，即使它们是广泛适用的产品能力。相关操作已整合到单个工具中，并通过 mode／action 选择器进行区分（v4.0）。

传统的 Playbook 范围迁移（分类 / 应用 / 回滚 / 审核队列）已从 MCP 层移至仅限所有者使用的本地 CLI：engram playbook scope classify|apply|rollback|queue|resolve（默认预览；写入需要 --apply --yes）。

Playbook 自动提取

piia-engram 可以检测你在会话中完成的多步骤工作流，并自动起草结构化 Playbook — 无需手动记录。

工作原理

1. 检测 — 调用 wrap_up_session 或 save_agent_context 时，piia-engram 会扫描流程性工作流信号：检查点步骤、动作动词和触发关键词。
2. 生成草稿 — 如果检测到工作流，就会创建 Playbook 草稿，其中包含步骤、陷阱、触发关键词和前置条件。敏感信息（API 密钥、令牌、绝对路径）会在存储前自动脱敏。
3. 暂存 — 草稿会保存到暂存区，不会自动升级为已验证状态。你需要审核并确认，之后它才会成为可信的 Playbook。
4. 架构契约 — 存储的 Playbook 会规范化为带版本的契约：触发关键词、前置条件、陷阱、结构化步骤以及可选的 required_tools 声明。内容较少的草稿仍可审核，但会附带机器可读的质量警告。
5. 工具解析 — Playbook 按名称或用途声明工具需求，而本地路径保留在工具注册表中。playbook_execution（操作 prepare）会在运行时返回 resolved_tools、tools_ready 和 missing_tools，让宿主 AI 可以查看哪些本地工具可用，而无需在 Playbook 中存储解析后的路径。
6. 复用与结果 — AI 工具下次遇到类似任务时，search_knowledge 会匹配触发关键词，并将 Playbook 作为被动参考返回。宿主 AI 会与你一起逐步执行，而 playbook_execution（操作 status）会汇总执行结果（pending、partial、succeeded 或 failed），而不会将跳过的步骤视为默认成功。

设计理念：由 Engram 发起，由你确认，由 AI 应用

Playbook 自动提取并非完全自动化。piia-engram 会检测工作流并生成粗略草稿 — 但草稿会一直留在暂存区，直到你明确确认。确认后，AI 工具可以将 Playbook 用作受治理的被动参考，并记录步骤结果；Engram 不会悄悄替它们执行工作流。这样既能让人类参与质量控制，也免去了手动编写操作流程的工作。

置信度级别

敏感信息脱敏

存储任何草稿前，piia-engram 会自动对以下内容进行脱敏：

• API 密钥和令牌（Bearer、sk-、ghp_ 等）
• 绝对文件路径（Windows 和 Unix）
• 电子邮件地址
• 环境变量中的机密信息

紧急开关

用户可以随时禁用或重新启用 Playbook 自动提取：

• 禁用： 告诉 AI“关闭 playbook” / “stop playbook” / “disable playbook auto-extraction”
• 启用： 告诉 AI“开启 playbook” / “start playbook” / “enable playbook auto-extraction”

AI 可以通过 update_identity(field="preferences", ...) 提议更改 playbook_auto_extract；只有你在本地使用 engram review 批准后，更改才会生效。默认情况下为启用。

手动创建 Playbook

无论自动提取设置如何，你始终可以使用 add_playbook 手动创建 Playbook。紧急开关只会影响 wrap_up_session 期间的自动检测。

数据布局

~/.engram/
|-- schema_version.json
|-- identity/
|   |-- profile.json
|   |-- preferences.json
|   |-- quality_standards.json
|   `-- trust_boundaries.json
|-- knowledge/
|   |-- lessons.json
|   |-- decisions.json
|   `-- domains.json
|-- playbooks/
|   |-- _index.json
|   `-- {playbook_id}.json
|-- tools/
|   `-- registry.json
|-- projects/
|   `-- {project_id}.json
|-- contexts/
|   `-- {tool_name}/
|       `-- {session_id}.md
|-- exports/
`-- compat/
    `-- openclaw/

拥有并导出你的数据

所有内容都保存在由你掌控的本地 JSON 文件中，可直接检查、编辑、备份或删除。 提供三种明确的导出方式，各自的范围不同：

当 ENGRAM_GOVERNANCE=1 时，导出操作需要所有者授权（参见 docs/governance.md）。没有云端副本，也没有隐藏记忆： 导出的内容与你磁盘上的内容完全一致。

存储限制。 已审核的记忆绝不会因存储空间已满而被移出；未审核的记忆会在审核队列中至少等待 7 天，移出的内容会进入只能追加的溢出归档，你可以从中恢复（engram retention plan 显示数量，engram retention restore <id> 可恢复条目）。

本地数据自主权。 备份和恢复仅涵盖 Engram 目录 ——engram backup-plan 会输出升级前需要复制内容的元数据清单（不会读取已存储知识的正文，也不会访问 Engram 根目录之外的内容）。对于 JSON 备份，import_engram(..., dry_run=True) 或 engram import <backup.json> 会在任何写入发生前，返回仅包含元数据的合并计划，其中列出新增/跳过/冲突的数量；应用此计划仅在本地执行： engram import <backup.json> --apply --yes（通过 MCP 时，import_engram 仅预览）。摘要相同的经验教训，以及问题相同但语义字段不同的决策，会作为版本链候选项显示在预览中；只有所有者明确运行 engram import <backup.json> --apply --yes --materialize-version-chain 时，才会将其实际创建为版本链。Engram 绝不会备份、修改或删除你项目文件夹中的文件。 参见 docs/runbooks/setup-upgrade-safety.md。

对比

📊 完整的并列对比，包括何时选择竞品而非 piia-engram，请参见 docs/comparison.md。

Built With

piia-engram 是一个由人主导、AI 辅助的开源项目。

FAQ

哪些 MCP 服务可以让我在 Claude Code 和 Cursor 之间共享记忆？ piia-engram。使用 pip install piia-engram && engram setup 安装后，这两个工具都会从 ~/.engram/ 读取相同的身份、偏好和经验。无需云端，也无需同步服务——它们都通过 MCP 读取本地 JSON 文件。

什么是 piia-engram？ piia-engram 是面向兼容 MCP 的编码工具的本地优先 AI 工作身份层。它会将你的身份、偏好、代码标准、经验和关键决策保存为你机器上的本地 JSON 文件。配置好的工具（Claude Code、Codex、Cursor、Windsurf、Claude Desktop）可以读取同一份由用户掌控的上下文，因此新对话和工具切换都能基于同一套受治理的记忆与身份体系开始。

piia-engram 与官方 MCP memory server 有何不同？ 官方的 @modelcontextprotocol/server-memory 存储由实体和关系组成的通用知识图谱。piia-engram 专注于开发者身份：它提供结构化字段来记录你的个人资料、代码标准、质量要求、经验和关键决策，还提供 59 个用于知识生命周期管理的工具（搜索、审查、合并、跨项目继承）。如果你需要通用的实体记忆，请使用官方服务。如果你希望兼容 MCP 的编码工具基于对你的偏好和过往错误相同且经过认可的理解来开始工作，请使用 piia-engram。

piia-engram 与 Mem0、Zep 或 Letta 等 Agent 记忆工具有何不同？ 这些工具为 AI Agent 保存任务上下文和会话历史，记录工作流期间发生的事情。piia-engram 保存的是你作为一个人的特质：你的身份、偏好、来之不易的经验和关键决策。它属于不同的层面：身份会在不同工具、会话和项目之间持续存在，而任务记忆仅适用于单次 Agent 运行。你的数据是由你掌控、可以直接编辑的本地 JSON 文件。

为什么不直接使用 AGENTS.md / CLAUDE.md / .cursorrules？ 这些配置文件非常适合定义特定代码库的规则（构建步骤、编码约定）。piia-engram 面向的是你——能伴随你在不同代码库和已配置的兼容 MCP 工具之间使用的偏好、经验和决策。两者相辅相成：用 AGENTS.md 管理项目，用 piia-engram 记录个人信息。请参阅 docs/comparison.md 中的完整比较。

我可以同时将 piia-engram 与多个 AI 工具搭配使用吗？ 可以。这正是它的主要用途。piia-engram 使用本地文件存储（~/.engram/），并支持原子写入和文件锁定。Claude Code、Cursor、Codex 以及任何其他 MCP 客户端都可以同时连接。在 Claude Code 中记录的经验会立即在 Cursor 中可用。

piia-engram 支持哪些 AI 工具？ 任何兼容 MCP 的工具：Claude Code、OpenAI Codex、Cursor、Claude Desktop、Windsurf、GitHub Copilot、Cline、Roo Code、Amazon Q、Augment、Zed 等。对于不支持 MCP 的工具（ChatGPT、Gemini、Kimi），可以使用 get_identity_card 导出 Markdown 身份卡片并粘贴到其中。

我的数据存储在哪里？ 所有数据都以纯 JSON 和 Markdown 文件的形式保存在本地机器的 ~/.engram/ 中。无需云端、账户或订阅。你可以自行打开、编辑、备份或迁移这些文件。也可以通过 pip install piia-engram[secure] 使用可选的 AES-256-GCM 加密。

如何安装 piia-engram？

pip install piia-engram
engram setup

默认情况下，设置向导会检测你的 AI 工具，但不会更改其配置文件。若要自动配置 MCP 条目并创建备份，请运行 engram setup --apply-external-config，然后重启 AI 工具。AI 会在每次会话开始时调用 get_user_context。 升级后，我的 AI 工具显示“MCP 服务已断开连接”。该如何修复？ 在终端中运行 engram doctor --fix，然后重启 AI 工具。此命令会扫描所有已知的 MCP 配置文件，删除过时的服务条目，并一次性修复损坏的路径。

piia-engram 会向云端发送数据吗？ 你的记忆不会离开你的设备。默认情况下，Engram 每天发送一次匿名使用情况信号（随机安装 ID、版本、操作系统、Python 版本、AI 客户端名称、日期）。不会发送任何内容、提示词或文件路径；也不会存储 IP 地址。你可以使用 engram telemetry off、ENGRAM_TELEMETRY=0 或 DO_NOT_TRACK=1 关闭此功能（在 CI 和容器中默认关闭）；engram telemetry preview 会显示确切的负载内容。设置期间会显示一则信息提示，但不会询问你是否启用遥测。除非明确通过 engram telemetry on 启用，否则详细统计信息会保持关闭；远程发送（engram telemetry remote on）和每周反馈（engram telemetry feedback on）需要分别选择启用。设置会保留现有选项。请参阅 PRIVACY.md。

piia-engram 提供多少个 MCP 工具？ 共有两个层级，旨在让大多数用户只看到 19 个工具：

大多数用户无需启用高级工具——核心工具足以满足日常使用。

piia-engram 是免费的吗？ 是。开源核心是依据 AGPL-3.0 发布的免费软件。个人/本地使用无需订阅、云端套餐或担心受供应商锁定。如果你计划将其嵌入闭源产品、托管后再分发或打包用于企业，请先了解 AGPL 的义务；piia-engram 目前没有单独的商业许可证。

局限性

piia-engram 功能完善且已在积极使用中，但目前仍有一些它有意尚未实现的功能：

实际影响：

• 不要在 piia-engram 中存储密码、API 密钥或客户端个人身份信息
• 任何拥有 ~/.engram/ 读取权限的进程都能读取你的数据
• restricted_fields 会减少 piia-engram 在冷启动上下文中输出的内容，但它不是加密，也不是真正的 ACL

这并不是在警告你不要使用 piia-engram——而是如实说明它的定位：为个人 AI 上下文提供本地记忆层。对于个人使用，它目前表现良好。

安全配置

字段级加密（可选）

静态加密敏感的个人资料字段（电子邮件、电话、位置等）：

pip install piia-engram[secure]
export ENGRAM_SECRET="your-strong-passphrase"

加密字段在 JSON 文件中存储为 enc:v2:...；旧版 enc:v1:... 值仍可解密。未加密的存储会像往常一样使用明文（向后兼容）。

在预期根目录启用存储加密后，钩子队列正文及其队列发布中间数据也会受到保护。这是根目录本地的选择性启用：如果仅缺少密钥，盐值或必需的队列策略会阻止回退到明文。所有写入方都必须使用预期根目录；副本必须保留策略和原始盐值，并将密钥传递到每台主机。如果不完整的恢复同时遗漏这两项本地信号，则可能选择明文。启用期间请暂停写入方，或使用钩子队列范围与恢复指南中所述的共享策略门控。下游归档、摘要、快速上下文、项目快照和部分知识元数据仍为明文；这并非全存储或端到端加密。

审计日志（默认开启）

本地审计日志会以 JSON 行格式将所有读写操作记录到 ~/.engram/audit.log。它是仅存储在本地的文件，不会发送到任何地方。可使用 get_audit_log 工具或 grep 查询。

选择退出：

export ENGRAM_AUDIT=0

Agent 治理（高级，可选）

启用按调用方划分的信任级别和披露回执：

export ENGRAM_GOVERNANCE=1
export ENGRAM_CLIENT_TYPE=claude_code

治理默认关闭。启用后，已知的本地编码 Agent 会被限制为公开/工作知识，未知调用方会默认拒绝并仅限访问公开内容，而仅限所有者的导出/导入/授权变更则要求 private-self。有关确切的信任级别、门控、适用边界和账本命令，请参阅docs/governance.md。

建议的部署方式：保持全局默认设置兼容，但在通过多个 AI 工具、自动化或任何面向远程的桥接使用 Engram 时，在每个 MCP 客户端环境中启用治理。engram status 和 engram doctor 会报告这一层是否已开启。调用方身份仍由 MCP 环境变量提供，而非通过加密身份验证，因此治理属于实用的本地策略边界，而不是强化的沙箱。

CLI 命令

engram setup            # Interactive install wizard (confirms before writing client configs)
engram setup --apply-external-config  # Skip the confirm prompt (non-interactive/CI); writes with backups
piia-engram doctor           # Check config health + governance state
piia-engram status           # Redacted install + memory/governance summary
piia-engram status --html    # Write a local redacted status page
piia-engram preview          # Show what a simulated AI caller would receive (--as ROLE, --level, --html)
piia-engram continuity       # Prove cross-tool handoff readiness (metadata only)
piia-engram management       # Show a metadata-only review/playbook management view
piia-engram doctor --fix     # Auto-repair any issues found
piia-engram sessions         # List saved cross-tool agent sessions
piia-engram sessions show <id>  # Print one saved session
piia-engram review           # List staging knowledge awaiting review
piia-engram review interactive  # Decide pending proposals one at a time (a/r/s/k/v/q, confirm with y)
piia-engram review show <id> # Inspect one review item
piia-engram review approve <id> --yes  # Promote a staging item
piia-engram review archive <id> --yes  # Archive a review item
piia-engram management action review approve <id> --yes --json  # Structured metadata-only action receipt
piia-engram management action playbook delete <id> --yes --json # Soft-delete a Playbook without body echo
piia-engram management action playbook_scope accept_project <id> --project . --yes --json # Resolve ambiguous Playbook scope
piia-engram management action playbook_scope accept_shared <id> --project ./app-a --project ./app-b --yes --json # Share one Playbook with selected projects
piia-engram dock-status      # Zero-write Dock owner-console status (--json)
piia-engram repair-encoding  # Dry-run scan for garbled / mojibake text
piia-engram repair-encoding --apply  # Repair reversible cases with a backup
piia-engram backup-plan      # Metadata-only plan of what to copy before upgrading (local-only)
piia-engram retention plan   # Read-only: memory counts per pool and what the next write would archive
piia-engram export-agents-md # Export verified, non-sensitive knowledge as an AGENTS.md/CLAUDE.md block
piia-engram stats            # Show project growth metrics (GitHub + PyPI)
piia-engram stats --log      # Append stats snapshot to local log
engram telemetry        # Manage the daily usage ping and opt-in detailed statistics
engram privacy          # Show what data piia-engram stores and where

参与贡献

欢迎贡献、反馈问题和提出意见。

请参阅 CONTRIBUTING.md。

许可证

AGPL-3.0。piia-engram 是自由软件。你的 AI 工作身份和记忆属于你。