Piia Engram：给每个 AI 工具装上你的「记忆大脑」

你是否有过这样的崩溃时刻？刚在 Claude Code 里花了半小时解释清楚你的代码规范、测试偏好和架构决策，一换到 Cursor 或 Codex，一切归零——AI 又变回了「一无所知的外星人」。每次新建对话、切换工具、更新版本，辛辛苦苦积累的上下文就像泼出去的水，再也收不回来。

这不怪 AI 工具，是行业现状：AI 的记忆被锁在工具里，而不是属于你。

piia-engram 试图解决这个问题。它是一个本地优先的个人 AI 身份层——不是「任务记忆数据库」，而是「你本人」的数字投影：你的偏好、你的教训、你的决策逻辑、你定义的质量标准。你的每一个 AI 工具，都从这个共同的身份层出发，而不是每次从零开始。

Memory Lens — 精确预览 AI 调用者将收到的内容：哪些知识暴露、哪些被治理规则过滤、预算消耗多少

图1：Memory Lens（记忆透镜）——在 AI 真正调用之前，精确预览它将收到什么内容，包括哪些条目被暴露、哪些被治理规则拦截、敏感内容显示为 [REDACTED]

背景：为什么 AI 工具的「记忆」是个伪命题

目前主流 AI 编码工具（Claude Code、Cursor、Codex、Windsurf）都在构建各自的记忆系统：内置 Memory、Rules、System Prompts。这些系统有用，但有两个根本性缺陷：

第一，数据属于工具，不属于你。 工具更新、订阅到期或切换产品，你的记忆随之消失，没有导出、没有审查、也无法迁移。你对自己的「AI 人格」没有任何控制权。

第二，记忆被困在单一工具里。 在 Claude Code 里训练好的上下文，无法带到 Codex。跨工具切换意味着从头解释——关于你、你的风格、你项目的一切，重复了无数遍。

piia-engram 的出现正是对这两个问题的正面回应：让你拥有并控制自己的 AI 记忆层，并且这份记忆能被所有兼容 MCP 协议的 AI 工具共享。

核心功能：身份层的三层结构

piia-engram 将「AI 身份」分解为三种知识类型：

Lessons（教训）：从错误中学到的经验，比如「这个模块的并发问题要特别小心」或「这个 API 有隐藏的副作用」。这些教训会被 AI 在相关场景下主动想起，而不是重复踩坑。

Decisions（决策）：架构选型、依赖决策、设计原理的记录。每个决策附带背景和理由，当 AI 面临类似抉择时可以参考「你当时是怎么想的」。

Playbooks（ playbook）：工作流 SOP、最佳实践清单、项目专属规范。相当于给 AI 一份「新人培训手册」，覆盖测试流程、提交流程、代码审查标准等。

这三种知识类型统一存储在 ~/.engram/ 本地目录下，以 JSON 和 Markdown 格式保存，数据完全归你所有。

技术架构：三层分离的 Facade 模式

项目的代码架构清晰，采用三层分离设计：

第一层：Transport（传输层） —— mcp_server.py + mcp_tools_*.py（共 4 个文件），负责 MCP 协议接入。每个 AI 工具通过 MCP stdio 连接到一个独立的 engram 进程。默认暴露 17 个核心工具（Tier-1），开启 ENGRAM_TOOLS=all 后可解锁 40 个高级工具，总计 57 个 MCP 工具。

第二层：Domain（领域层） —— Engram facade 类（core.py，约 1770 行核心逻辑）配合多个 Mixin 混入类：RetrievalMixin（检索）、ContextMixin（上下文）、ReconcileMixin（冲突协调）、ReportsMixin（报告生成）。每个 Mixin 专注单一职责，通过组合而非继承实现功能扩展。

第三层：Storage（存储层） —— ~/.engram/ 目录下的 JSON 文件集合，使用 portalocker 实现跨进程原子写入。默认零依赖（无数据库），可通过可选的 sqlite-vec + fastembed 扩展向量语义搜索能力。

这个架构的精妙之处在于：传输层薄、领域层纯、存储层稳。MCP 服务器只是薄薄的异步封装，核心业务逻辑完全不依赖协议细节，存储层用最朴素的 JSON + 文件锁保证可靠性。

三层架构：从 AI 工具到本地存储的完整数据流

图2：piia-engram 三层架构——Transport（stdio/HTTP）→ Domain（Engram Facade + Mixins）→ Storage（~/.engram/ JSON），数据流清晰分离

信任模型：AI 写什么，你说了算

piia-engram 内置了一套精细的治理机制（Governance System），对 AI 的写入操作分级管控：

低风险条目（普通知识记录）：自动吸收，完全可审计、可回滚。

中风险条目（偏好调整、流程规范）：自动吸收但生成变更报告，供你事后审查。

高风险条目（凭证、Shell 命令、MCP 配置、权限规则）：默认等待人工审批，设置 ENGRAM_APPROVAL=strict 可将所有写入全部 gate。

Memory Lens 功能（engram preview --html）让你在任何信息被发送出去之前，精确预览 AI 调用者将收到哪些内容——包括哪些条目被暴露、哪些被治理规则过滤、哪些敏感内容被标记为 [REDACTED]。数据透明、可审计、可覆盖，这是「本地优先」的安全底线。

加密方面，默认存储为明文 JSON，可选字段级 AES-256-GCM 加密（需安装 cryptography 依赖），PBKDF2 密钥派生使用 600,000 次迭代（OWASP 2023+ 标准）。

跨工具连续性：从 Claude Code 写到 Codex 读出

piia-engram 的核心竞争力之一是跨工具上下文连续性。项目提供了经过验证的证据链（cross-tool continuity proof）：Claude Code 写入的记忆，能被 Codex 正确读取，且整个过程基于同一个本地存储文件，无任何云端中转。

支持的工具列表覆盖了主流 AI 编码产品：Claude Code、Codex、Cursor、Claude Desktop、Windsurf、Cline、Roo Code、GitHub Copilot、Zed、Trae 等，均通过 MCP stdio 协议连接，OpenClaw 还支持 SOUL.md/MEMORY.md 静态文件桥接。

上手门槛：pip 一键安装，全程向导

部署极其简单，只需要 Python 3.10+ 和 pip：

pip install piia-engram && engram setup

setup 向导会自动检测你系统上安装的 AI 工具（Claude Code、Cursor、Claude Desktop 等），列出将要修改的配置文件，逐项等待你确认后才写入，所有操作自动备份，拒绝则无任何变更。整个配置过程不超过 5 分钟。

如果需要 Docker 方式运行，项目提供了官方 Dockerfile，基于 python:3.12-slim，非 root 用户运行，容器内运行 MCP server 通过 stdio 传输数据。

硬件需求几乎为零：无需 GPU，典型冷启动时间 < 100ms，内存占用 ~256MB，磁盘占用 ~50MB，默认无任何网络调用（除非你主动使用 read_web_content 抓取网页内容）。

与 Mem0/Zep/Letta 的本质区别

piia-engram 明确将自己与任务记忆库区分开来：

Mem0、Zep、Letta 这类工具存储的是「任务执行过程中的上下文」——会话历史、任务步骤、中间结果。而 piia-engram 存储的是「执行任务的人」——你是谁、你关心什么、你有过什么教训、你的质量标准是什么。

打个比方：如果 AI 工具是一座工厂，Mem0/Zep 记录的是工厂里流水线上发生了什么，而 piia-engram 记录的是工厂老板的性格、管理风格和做过的关键决策。两者互补，不相互替代。

局限与争议

多用户场景支持有限：当前设计面向单用户本地使用，多人协作场景需要额外的权限隔离机制。

记忆质量依赖人工维护：知识库的价值取决于你输入内容的质量，AI 辅助写入虽然降低了维护门槛，但低质量的记忆反而会误导 AI——项目坦承「垃圾进、垃圾出」的风险。

跨工具验证尚未全覆盖：支持的 16 种工具中，部分仅达到 L1/L2 验证级别（安装验证/读写搜索路径），L4 级别的跨工具连续性证明目前只有 Claude Code → Codex 这一条路径，其他工具的跨工具能力属于「Expected to work」而非「已验证」。

向量搜索为可选项：语义搜索能力需要额外安装 ~230-280MB 的嵌入模型（fastembed），默认 FTS5 索引仅支持关键词匹配，对复杂语义查询场景有一定限制。

行业意义：让 AI「记住你」从不可能变为可能

piia-engram 代表了一个重要趋势：AI 工具的个性化从「工具私有」走向「用户主权」。当行业还在争论哪个 AI 助手的记忆更好用时，piia-engram 给出了另一个答案——记忆应该属于用户，而不应该是平台锁定的资产。

随着 MCP 协议逐渐成为 AI 工具间通信的事实标准，类似的跨工具身份层会越来越重要。piia-engram 作为最早一批深度集成 MCP 的个人身份工具，为这一方向提供了有价值的实践样本。

如果你经常在多个 AI 编码工具之间切换，或者希望 AI 能真正「理解你是谁」而不仅仅是「完成当前任务」，piia-engram 值得一试——它装起来简单，用起来透明，最重要的是：你的数据永远在你的机器上。