piia-engram

一个记忆。所有AI工具。由你保管。

AI可以建议记忆。你决定哪些成为真实。

只需告诉AI一次——你的偏好、标准和经验教训将跟随你在Claude Code、Cursor、Codex以及任何兼容MCP的工具中。AI提出知识；你批准哪些被保留。本地优先，无需云，无需账户。

跨工具记忆 | 本地优先 | Claude Code | Codex | Cursor | Windsurf | MCP

ENGLISH | 中文

---

TL;DR: piia-engram 将你的身份、偏好、学到的经验和关键决策存储为本地JSON文件，并通过MCP与每个AI工具共享。设置一次，每个AI工具都会记住你。无需云，无锁定，Apache 2.0许可。

---

每次切换工具或开始新的聊天时，你的AI都会忘记你。 piia-engram 解决了这个问题。

每次打开新的聊天窗口、从Claude Code切换到Codex、更新你的AI工具或进入不同的项目时，你都得从零开始：

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

这是因为今天的AI记忆被锁定在每个平台内部。它属于工具，而不是你。当工具更新、重置或被替换时，你的上下文也随之消失。

piia-engram 提供了一种持久的记忆，它存在于你的机器上，独立于任何AI工具。 你只需要告诉它一次你是谁、如何工作以及学到了什么。每个兼容MCP的工具读取相同的上下文。新聊天、新工具、新版本——你的身份始终存在。

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

为什么选择piia-engram？

无piia-engram	有piia-engram
新聊天窗口 = 从零开始	每次对话都已经了解你
AI工具更新后，你的偏好消失	你的身份存在于你的机器上，不受任何更新影响
切换工具时失去累积的上下文	Claude Code、Codex和Cursor读取相同的记忆
过去的错误不断重复	经验教训跟随你在不同工具和会话中
记忆被锁定在一个产品内	数据保持本地化、可编辑和可移植

谁使用piia-engram

piia-engram 是为那些使用多种AI编码工具并厌倦了反复解释自己的开发者而构建的。

如果你在Claude Code、Codex和Cursor之间切换——你的代码标准、架构决策和来之不易的经验每次都会重置。piia-engram 使每个工具都能从对你身份的相同理解开始。

如果你每周打开10多个AI聊天窗口——每个窗口都从零开始。piia-engram 从第一条消息开始就给每段对话提供完整的上下文。

如果你在工具更新后失去了偏好——你的身份存在于你的机器上，而不是任何平台上。更新、重置和迁移不会影响你的记忆。

系统架构师
架构决策需要上下文：你选择了什么，排除了什么，以及原因。piia-engram 保存了可查询的、持续更新的架构决策记录，这些记录可以随你跨越公司和项目，并且可以通过任何 AI 工具进行查询。

后端开发者
API 的怪癖、集成陷阱、性能权衡 —— 这些通常是只存在于你脑海中的隐性知识，并且在你换工作时会被重置。piia-engram 将其转化为一个可搜索的库，可以在所有内容中持久化。

前端和设计
设计哲学很少以 AI 工具可以使用的方式被记录下来。piia-engram 存储你的真实标准、来自真实用户的 UX 经验教训以及组件决策背后的推理 —— 因此每个项目都可以从上一个项目的终点开始。

氛围编码者
你用 AI 构建并快速前进。问题在于：每次新会话 AI 都是从头开始 —— 不同的风格选择、不一致的模式、重复解释相同的偏好。piia-engram 使每个工具从第一次会话起就保持一致：你的技术栈、你的模式、你的声音，都已经在那里了。

piia-engram 存储的内容

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

• 身份：你是谁，如何沟通，偏好的语言
• 质量标准：你的代码审查标准、测试覆盖率期望、你不愿意发布的内容
• 偏好：编码风格、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健康评分，并标记出值得重新审视的缺口。suggest_merges 会扫描您的整个知识库以查找近似重复项，并返回可操作的合并命令。link_knowledge 将相关的课程和决策连接成一个可导航的知识图谱。

快速开始 (30秒)

pip install piia-engram

engram setup

设置向导将：

1. 检测您的Python环境
2. 查找并配置您的AI工具（Claude Code, Cursor, Claude Desktop, Codex）
3. 注入AI指令到每个工具的原生配置文件中（如 CLAUDE.md, .cursorrules, AGENTS.md），以便AI主动调用Engram
4. 引导您通过种子知识（角色、技术栈、语言）
5. 从现有的 CLAUDE.md / .cursorrules 文件智能导入规则
6. 显示您的隐私偏好（跨工具同步、匿名统计——两者均为可选项）
7. 预览您的AI身份卡 —— 立即证明价值

设置完成后重启您的AI工具。第一次对话将自动调用 get_user_context —— 您的AI已经认识您了。

随时检查健康状况：

engram doctor        # diagnose all tools
engram doctor --fix  # auto-repair issues + inject missing instructions

针对您的AI工具进行配置

# Automatic (recommended)

engram setup

# Or manual:

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

添加到 ~/.cursor/mcp.json:

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

添加到 ~/.codex/mcp.json:

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

添加到 claude_desktop_config.json:

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

任何支持通过stdio使用MCP的工具都可以工作。使用此配置：

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

对于不支持MCP的工具（ChatGPT, Gemini, Kimi）：在任何MCP工具中运行 get_identity_card 并将导出的Markdown卡片粘贴到聊天中。

实际效果展示

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 already knows you

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..."

设置完成后，运行 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: 17 tools registered

升级

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, 和 Claude Desktop的配置，并移除任何过时的服务器条目。

远程部署

在您自己的服务器上运行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": {

    "piia-engram": {

      "url": "http://your-server:8767/sse",

      "headers": {

        "Authorization": "Bearer abc123..."

      }

    }

  }

}

客户端配置 (Cursor)

{

  "mcpServers": {

    "piia-engram": {

      "url": "http://your-server:8767/sse",

      "headers": {

        "Authorization": "Bearer abc123..."

      }

    }

  }

}

安全注意事项:

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

MCP工具

piia-engram附带了61个MCP工具。默认情况下，只加载13个一级核心工具，以保持AI上下文的整洁。要解锁全部61个工具，请在您的MCP配置中添加 ENGRAM_TOOLS=all：

{

  "mcpServers": {

    "piia-engram": {

      "command": "python",

      "args": ["-m", "piia_engram.mcp_server"],

      "env": { "ENGRAM_TOOLS": "all" }

    }

  }

}

一级核心 (13个工具 — 日常工作流)

工具	目的
get_user_context	启动 — 在会话开始时加载身份+知识（支持 token_budget 控制上下文大小）
wrap_up_session	会话结束 — 在会话结束时保存见解并同步
memory_store	写回 — 统一写入端点：根据 kind 路由到 add_lesson / add_decision / add_playbook
add_lesson	存储一个可重用的学习课程
add_decision	记录带有推理的关键决策
search_knowledge	检索 — 搜索经验教训、决策和剧本（支持使用 filters_json 进行领域/层级/日期过滤）
get_relevant_knowledge	查找与当前项目相关的知识
get_identity_card	为非MCP工具导出Markdown格式的身份卡
update_identity	更新个人资料、偏好设置或质量标准
get_project_context	读取已保存的项目快照
save_project_snapshot	保存项目状态以便未来会话使用
get_recent_context	重启后恢复丢失的会话上下文

第二层级 高级（48个工具 — 知识管理、审查、导入/导出）

工具	目的
register_tool	将本地工具、运行时或CLI注册到环境映射中
find_tool	根据名称查找已注册的工具
list_tools	列出所有已注册的工具（可按类别筛选）
save_agent_context	保存AI会话检查点（也会自动运行）
list_agent_sessions	浏览跨工具保存的会话记录
refresh_quick_context	为离线/跨工具使用刷新本地 quick_context.md 快照
get_profile	读取用户配置文件（默认情况下safe=true）
get_work_style	读取工作风格偏好
get_preferences	读取沟通和工作流程偏好
get_trust_boundaries	读取数据访问边界
get_quality_standards	读取质量期望
get_playbooks	列出已保存的操作剧本
get_playbook	通过ID获取单个剧本的全部内容
get_recent_playbooks	按最近使用顺序列出剧本
update_playbook	更新剧本步骤、触发器或其他字段
archive_playbook	归档不再使用的剧本
prepare_playbook_execution	生成带有参数替换的可执行计划
update_execution_step	标记步骤为已完成、跳过或失败
get_execution_status	查看剧本当前执行进度
get_lessons	列出可重用的经验教训
get_decisions	列出关键决策及其原因
get_domains	读取领域经验统计
get_knowledge_inheritance	构建跨项目的知识入门包
list_projects	列出已保存的项目快照
extract_session_insights	从会话文本中提取经验和决策
bulk_add_knowledge	一次调用添加多个经验和决策
ingest_notes	将自由格式的笔记解析为结构化知识
update_knowledge	通过ID更新一个经验或决策
archive_knowledge	通过ID归档一个经验或决策
review_knowledge	标记知识项为已审阅
merge_knowledge	将重复项合并到主项中
link_knowledge	在条目之间创建双向链接
unlink_knowledge	移除双向知识链接
get_knowledge_overview	知识摘要、健康报告、陈旧性检查
get_related_knowledge	跟踪知识条目之间的链接
find_similar_knowledge	按内容查找相似条目
suggest_merges	扫描近似重复项并提供可操作的合并命令
get_stale_knowledge	列出需要审阅的条目
export_knowledge_report	导出可读的Markdown格式的知识报告
request_outline_review	生成交互式HTML审阅页面
apply_review	处理审阅结果（提升/归档暂存项）
export_engram	导出完整备份
import_engram	导入备份
export_engram_to_openclaw	导出兼容OpenClaw的文件
import_engram_from_openclaw	导入兼容OpenClaw的文件
read_web_content	通过本地Reader服务读取网页
get_audit_log	获取最近的审计日志条目
start_project	使用继承的知识启动项目

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

工作原理

1. 检测 — 当您调用 wrap_up_session 或 save_agent_context 时，piia-engram 会扫描过程性工作流信号：检查点步骤、动作动词和触发关键词。
2. 草稿生成 — 如果检测到工作流，则会创建一个包含步骤、陷阱、触发关键词和前提条件的 playbook 草稿。在存储之前，敏感信息（如 API 密钥、令牌、绝对路径）会被自动删除。
3. 暂存 — 草稿被保存到暂存区，不会自动提升为已验证状态。您需要审查并确认后，它才会成为可信的 playbook。
4. 重用 — 下次 AI 工具遇到类似任务时，search_knowledge 会匹配触发关键词并返回 playbook。AI 将遵循经过验证的步骤，而不是即兴发挥。

设计理念：Engram 开始，您确认，AI 完成

Playbook 自动提取并不是完全自动的。piia-engram 检测工作流并生成粗略草稿 —— 但草稿会保留在暂存区，直到您明确确认。一旦确认，AI 工具可以自主完善并遵循 playbook。这使得人类能够进行质量控制，同时消除了编写操作程序的手动工作。

置信度级别

级别	信号	AI 行为
高	从 save_agent_context 中获取 3 个或更多检查点步骤	AI 通知您：“检测到可重用的工作流，已生成 playbook 草稿。”
中	基于文本的检测（触发关键词 + 动作动词）	AI 静默保存到暂存区，不通知。

敏感信息删除

在任何草稿存储之前，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。默认是 启用。

手动创建 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/

支持的工具

工具	集成	置信度
Claude Code	MCP over stdio	✅ 已验证
Codex	MCP over stdio	✅ 已验证
Cursor	MCP over stdio	✅ 已验证
Claude Desktop	MCP over stdio	✅ 已验证
Windsurf	MCP over stdio	预期可用
GitHub Copilot	MCP over stdio	预期可用
Cline	MCP over stdio	预期可用
Roo Code	MCP over stdio	预期可用
Amazon Q	MCP over stdio	预期可用
Augment	MCP over stdio	预期可用
Zed	MCP over stdio	预期可用
OpenClaw	SOUL.md / MEMORY.md / USER.md 导入导出	✅ 已验证
ChatGPT / Gemini / Kimi	Markdown 身份卡回退	🔧 可用

对比

特性	piia-engram	Claude Memory	手动 CLAUDE.md	Mem0	Letta (MemGPT)
主要目的	跨工具用户身份	会话记忆	项目笔记	代理向量记忆	代理自编辑记忆
设计上跨工具	✅ MCP 原生（13 个核心工具）	❌ 仅 Claude	❌ 特定工具	⚠ 需要每个工具的连接	⚠ 需要每个工具的连接
存储	本地 JSON 在 ~/.engram/	云端	本地	向量数据库 + Mem0 云	Postgres 或 Letta 云
加密存储	✅ AES-256-GCM, PBKDF2 600k (可选)	取决于云	❌ 纯文本 Markdown	取决于存储配置	取决于 Postgres 配置
知识层级（用户门控）	✅ 分阶段 → 验证	❌	❌	❌	❌
冲突检测	✅	❌	❌	❌	❌
MCP 原生	✅	不适用	不适用	⚠ 第三方	⚠ 第三方
价格	免费，Apache 2.0	订阅捆绑	免费	免费 / 云层	免费 / 云层

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

数字说话

这些是关于 piia-engram 本身的事实声明，每个次要版本更新一次。

	v3.29.1 (2026-05-26)
支持的 AI 工具	13 (4 个已验证 + 7 个预期可用 + OpenClaw + ChatGPT 备用)
MCP 工具	13 核心 (默认加载) + 48 高级 (通过 ENGRAM_TOOLS=all 选择启用)
知识类型	3 (课程、决策、剧本)
测试通过	800+ (单元测试 + 集成测试)
代码覆盖率	96% 总计; mcp_server 99%, setup_wizard 93%, storage 100%, core 95%
core.py 中的行数	1097 (从 v3.14.1 前的 4277 行减少 — 请参见 architecture.md)
PBKDF2 迭代次数	600,000 (OWASP 2023+ 最低标准; 旧版 100k 仍可解密)
加密	AES-256-GCM, 每个值随机盐 + 随机数
冷启动时间	通常 < 100 ms (本地 JSON, 无网络)
核心中的网络调用	默认为 0 — 除了可选的 read_web_content 和选择加入的匿名使用统计 (本地 + 可选远程 — 隐私详情, 遥测路线图)
外部 AI 评估	4 个独立 AI 评估了遥测设计; 早期对架构进行了 3 次评估 (请参见 docs/)

构建方式

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

贡献者	角色
@Patdolitse	创建者、产品方向、策略、所有权
Claude Code	架构、任务规划、代码审查协助
Codex	实现、测试、文档协助

常见问题

什么 MCP 服务器允许我在 Claude Code 和 Cursor 之间共享内存？
piia-engram。使用 pip install piia-engram && engram setup 安装，这两个工具将从 ~/.engram/ 读取相同的标识、偏好设置和课程。无需云，无需同步服务 —— 它们都是通过 MCP 读取本地 JSON 文件。

什么是 piia-engram？
piia-engram 是 AI 工具的持久化内存层。它将您的身份、偏好、代码标准、学到的经验和关键决策作为本地 JSON 文件存储在您的机器上。每个兼容 MCP 的 AI 工具 (Claude Code, Codex, Cursor, Windsurf, Claude Desktop) 都读取相同的上下文，因此新的聊天、工具更新和工具切换永远不会抹去您的身份。

piia-engram 与官方 MCP 内存服务器有何不同？
官方的 @modelcontextprotocol/server-memory 存储了一个通用的知识图谱，包含实体和关系。piia-engram 专门针对 开发者身份：它有结构化的字段用于您的个人资料、代码标准、质量标准、学到的经验和关键决策 —— 加上 60 种知识生命周期管理工具 (搜索、审查、合并、跨项目继承)。如果您需要通用实体内存，请使用官方服务器。如果您希望每个 AI 工具都知道您的编码偏好和过去的错误，请使用 piia-engram。

**piia-engram 与 Mem0、Zep 或 Letta 等代理内存工具有何不同？**这些工具存储了AI代理的任务上下文和会话历史——即工作流中发生了什么。piia-engram则存储了你作为一个人的身份、偏好、来之不易的经验教训以及关键决策。这是一个不同的层次：身份信息在工具、会话和项目之间保持一致，而任务记忆仅限于单次代理运行。你的数据是本地的JSON文件，你可以直接拥有并编辑。

为什么不只使用AGENTS.md / CLAUDE.md / .cursorrules？
这些配置文件非常适合特定仓库的规则（如构建步骤、编码规范）。piia-engram则是为你个人服务的——你的偏好、经验教训和决策将跟随你跨越每一个仓库和每一个AI工具。它们相辅相成：用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。设置完成后重启您的AI工具。AI将在每次会话开始时调用get_user_context。

升级后，我的AI工具显示“MCP服务器已断开”。我该如何解决？
在终端中运行engram doctor --fix，然后重启您的AI工具。此命令会扫描所有已知的MCP配置文件，移除过时的服务器条目，并一次性修复损坏的路径。

piia-engram会将数据发送到云端吗？
不会。所有核心工具都不会发起网络请求。可选的匿名使用统计（工具调用次数，绝不会包含内容）可以在设置过程中启用，但默认情况下是关闭的。您可以使用engram telemetry preview检查负载，并随时通过engram telemetry off禁用。请参阅**PRIVACY.md**了解完整的数据流图、收集与未收集的内容以及您的数据权利。

piia-engram提供了多少个MCP工具？
分为两个层级，设计上大多数用户只会看到13个工具：

层级	工具数量	功能	加载方式
核心	13	身份、知识读写、项目上下文、会话恢复	默认加载
高级	48	知识回顾、合并、健康评分、工具注册表、导入导出、审计	ENGRAM_TOOLS=all

大多数用户不需要启用高级工具——核心工具已经覆盖了日常使用需求。

piia-engram免费吗？
是的。它基于Apache 2.0许可证免费且开源。无订阅费用、无云服务等级、无供应商锁定。

限制

piia-engram功能齐全且正在积极使用中，但在某些方面有意尚未实现：

领域	当前状态	计划
文件安全	带有共享portalocker文件锁的原子JSON写入	更广泛的稳定性测试
访问控制	restricted_fields 在get_user_context、get_profile（默认safe=true）、get_identity_card及资源端点中过滤个人资料	按调用者ACL被MCP调用者身份阻止
审计日志	通过 ENGRAM_AUDIT=1 环境变量可选地启用访问审计日志。日志记录到 ~/.engram/audit.log。	按调用者审计（被 MCP 规范阻止）
调用者身份	MCP 协议不传递工具身份	被 MCP 规范阻止
并发写入	通过文件锁和原子替换保护 piia-engram JSON 写入	不保证网络文件系统的边缘情况

实际意义：

• 不要在 piia-engram 中存储密码、API 密钥或客户 PII
• 任何具有读取 ~/.engram/ 权限的进程都可以读取您的数据
• restricted_fields 可以减少 piia-engram 在冷启动上下文中发出的内容，但它不是加密也不是真正的 ACL

这不是警告您避免使用 piia-engram —— 这是对它的诚实描述：一个用于个人 AI 上下文的本地内存层。对于个人使用，它目前工作得很好。

安全配置

字段级加密（可选）

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

pip install piia-engram[secure]

export ENGRAM_SECRET="your-strong-passphrase"

加密字段在 JSON 文件中存储为 enc:v1:...。没有 ENGRAM_SECRET 时，piia-engram 会正常以明文形式工作（向后兼容）。

审计日志（可选）

跟踪所有读/写操作：

export ENGRAM_AUDIT=1

日志以 JSON-lines 格式写入 ~/.engram/audit.log。可以使用 get_audit_log 工具或 grep 查询。

CLI 命令

engram setup            # Interactive install wizard

piia-engram doctor           # Check config health (all AI tools)

piia-engram doctor --fix     # Auto-repair any issues found

piia-engram stats            # Show project growth metrics (GitHub + PyPI)

piia-engram stats --log      # Append stats snapshot to local log

engram telemetry        # Manage anonymous usage statistics

engram privacy          # Show what data piia-engram stores and where

贡献

欢迎贡献、问题反馈。

参见 CONTRIBUTING.md。中文读者也可以参考 CONTRIBUTING.zh-CN.md。

许可证

Apache 2.0。piia-engram 是免费软件。您的记忆属于您自己。