Portable Agent Memory

让记忆、角色与技能真正属于你，而不是某一个 Agent。

Portable Agent Memory（PAM）是一个 local-first、MCP-first 的跨 Agent 认知资产层。它把 Agent 的长期记忆、角色设定和验证过的工作流，变成可检索、可审核、可迁移、可复用的开放资产。

English · 五分钟开始 · 完整文档 · MCP 接入 · 安全模型

---

一句话理解 PAM

今天你在 Codex 中积累的项目经验，明天可以被 Claude Code、Cursor、LangGraph、OpenAI Agents 或 CrewAI 继续使用——不需要复制聊天记录，也不需要把所有知识塞进一条巨大的 System Prompt。

Agent 运行轨迹
      │
      ├── 稳定事实与偏好 ───────────▶ Memory
      ├── 职责与行为边界 ───────────▶ Role
      └── 反复验证成功的工作流 ─────▶ Skill Candidate
                                         │
                                验证 · 回放 · 风险审核
                                         │
                                      人工批准
                                         ▼
                                    Active Skill
                                         │
                    ┌────────────────────┼────────────────────┐
                    ▼                    ▼                    ▼
                  Codex             Claude Code           LangGraph…

PAM 不是另一个 Agent 框架，也不是另一个向量数据库。它位于 Agent 和存储之间，专门解决长期认知资产的协议、治理、检索与迁移问题。

为什么选择 PAM

大多数 Agent 的“记忆”仍然被锁在对话、框架状态或厂商格式中：

• 换一个 Agent，项目经验几乎从零开始；
• Prompt 越堆越长，却没有版本、来源和有效期；
• 自动生成的 Skill 可能混入错误步骤或 Prompt Injection；
• 导出的 JSON 缺少引用闭包、完整性校验和发布者身份；
• 团队很难回答：这条记忆从哪里来、谁批准、何时失效？

PAM 将这些问题拆成稳定资产和明确边界：

常见做法	PAM v1.1
记忆藏在聊天记录里	Canonical Memory + Evidence + Scope
手工复制 System Prompt	Role/Skill 可检索、可编译、可迁移
模型自动覆盖旧事实	冲突 Candidate + 人工裁决 + 修订链
Skill 生成后直接执行	Candidate → 验证 → 回放 → 风险审核 → 批准
与单一 Agent SDK 绑定	MCP + Python Adapter + AgentPack
导出普通 JSON/ZIP	SHA-256、历史闭包、配额、可选 Ed25519 签名
云端服务才能运行	SQLite + FTS5，默认零外部服务

30 秒体验

要求 Python 3.11–3.13。所有环境和数据都可以留在当前仓库：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\pam.exe init

保存一条可跨会话复用的项目记忆：

pam remember "所有代码修改都必须附带测试" --kind preference --project-id pam
pam recall "代码修改要求" --project-id pam --explain

创建并治理一个 Skill：

pam skill run-tests "运行测试，定位失败原因，并报告验证结果" --project-id pam
pam review CANDIDATE_ID --html .\.pam\skill-review.html
pam replay-template .\replay.json
pam skill-replay CANDIDATE_ID --file .\replay.json
pam promote CANDIDATE_ID

把审核后的资产迁移给另一个 Agent：

pam export .\.pam\packs\project.agentpack
pam import .\.pam\packs\project.agentpack --dry-run

默认数据库位于 .pam/pam.db，不会写入系统全局目录。

工作原理

flowchart LR
    A["Agent Runtimes"]
    M["MCP stdio: Tools and Prompt"]
    P["PAM Service: Lifecycle, Scope, Governance"]
    R["Retrieval: FTS5, CJK, Local Hybrid"]
    G["Skill Governance: Diff, Validation, Replay, Risk"]
    S[("SQLite and FTS5 Local Store")]
    K["AgentPack 1.1: Integrity, Signature, Migration"]
    C["Compiler: Agent Skills, Prompt, SDK Context"]

    A --> M
    M --> A
    M --> P
    P --> M
    P --> R
    P --> G
    R --> S
    S --> R
    G --> S
    S --> G
    S --> K
    K --> S
    S --> C
    C --> A

核心设计原则：

1. 资产与 Runtime 解耦：同一份 Memory/Role/Skill 可进入不同 Agent。
2. 自动提炼，人工治理：Agent 可以提出 Candidate，但不能自行固化长期 Skill。
3. 来源优先：Evidence、版本、时间与 Scope 都是一等字段。
4. 安全默认值：MCP 没有 Promote、Delete、Import、Export 等 Govern 权限。
5. 最简安装优先：不安装数据库服务，不下载模型，不要求 API Key。

v1.1 已完成能力

可迁移认知资产

• Memory：事实、偏好、事件、过程知识和产物引用；
• Role：职责、风格、约束和协作边界；
• Skill：经过验证、可重复调用的工作流；
• Evidence：来源与证据，不拥有指令权限；
• Feedback：运行结果与最小必要轨迹，用于提炼 Candidate。

记忆正确性与检索

• 并发幂等去重和 Evidence 合并；
• conflict_key 冲突检测与人工裁决；
• supersedes / superseded_by 双向修订链；
• 五级 Scope：组织、用户、项目、Agent、会话；
• 有效期、历史时间点、metadata 精确过滤；
• FTS5、多词和中文 CJK 子串检索；
• 可选 dependency-free 本地 Hashing Embedding 混合重排与 SQLite 持久缓存；
• 内容哈希自动失效，以及全量/Scope 缓存重建；
• --explain 展示命中字段、Scope 和分数组成。

安全 Skill 演化

Feedback / Trace
       │
       ▼
Skill Candidate ──▶ Diff ──▶ Validator ──▶ Replay ──▶ Risk Review
                                                           │
                                              Human approve / reject
                                                           │
                                                           ▼
                                                      Active Skill

• allowlist 验证命令，使用 shell=False、超时和输出限制；
• 可执行 JSON Replay Suite、逐用例断言、超时与结果明细；
• 回放成功率阈值与兼容的手工测试套件记录；
• 验证和回放结果绑定 Skill 内容 SHA-256；
• 中英文 Prompt Injection 确定性风险信号；
• 高风险或门禁失败默认阻止晋升；
• 人工覆盖必须给出原因并写入审计；
• 只读 HTML 审核页面、版本历史与回滚 Candidate。

跨 Agent 接入

接入方式	状态	用途
MCP stdio 1.x/2.x	✅	通用 Tool 和 Prompt 调用
Codex	✅	输出 TOML MCP 配置
Claude Code	✅	输出 CLI/JSON MCP 配置
Cursor	✅	输出 MCP Server JSON
LangGraph Adapter	✅	注入 state，回写 trace
OpenAI Agents Adapter	✅	注入 instructions，回写 run items
CrewAI Adapter	✅	注入 task context，回写 crew output
JSON/JSONL Adapter	✅	自研 Agent Runtime

python -m pip install -e ".[mcp]"
pam connect codex
pam connect claude-code
pam connect cursor

这些命令只打印配置，不会修改客户端文件。

MCP 权限边界

PAM 提供 10 个 MCP Tool 和一个 pam_context Prompt：

能力	MCP	CLI
检索 Active Memory/Role/Skill	✅	✅
按精确 Scope 读取 Asset/Evidence/历史	✅	✅
写入或修订 Memory	可配置	✅
写入 Feedback / 摄取 Trace	可配置	✅
创建或晋升 Role/Skill	❌	✅
冲突裁决、删除、导入导出、签名	❌	✅

这意味着普通 Agent 可以学习和反馈，但不能悄悄修改自己的长期权限或行为规则。

AgentPack：不只是一个 ZIP

AgentPack 1.1 是 PAM 的便携交换格式：

project.agentpack
├── manifest.json
├── checksums.json
├── signature.json          # 可选 Ed25519
├── memories/assets.jsonl
├── roles/assets.jsonl
├── skills/assets.jsonl
├── evidence/*.json
└── skills/*/SKILL.md

• 自动补齐 Memory/Skill 历史闭包；
• SHA-256 检查 Payload 完整性；
• ZIP 路径、文件数、大小和压缩比限制；
• 可选 Ed25519 发布者签名与本地受信任公钥；
• 写入 1.1，读取 1.0/1.1，并支持 pack-migrate；
• import --dry-run 走完整校验路径但不写数据库。

python -m pip install -e ".[crypto]"
pam keygen --private .\.pam\keys\publisher.pem --public .\.pam\keys\publisher.pub.pem
pam export release.agentpack --signing-key .\.pam\keys\publisher.pem --publisher "My Project"

Python API

from pathlib import Path

from pam import AssetKind, PAMService, Scope

service = PAMService.at(Path(".pam"))
service.initialize()

scope = Scope(user_id="alice", project_id="pam")
service.remember("Project runtime is Python 3.13", scope=scope)

results = service.recall(
    "runtime",
    kinds=[AssetKind.MEMORY],
    scope=scope,
    explain=True,
)

for result in results:
    print(result.asset.content, result.score, result.explanation)

pam.__all__ 是 v1.x 稳定公共 API。第三方 Store、Adapter 和 Embedding Provider 均有明确扩展边界。

数据完全留在本地

PAM/.pam/
├── config.json
├── pam.db
├── backups/
├── packs/
├── skills/
└── logs/

• .pam/、数据库、私钥和 AgentPack 已被 .gitignore 排除；
• 严格配置默认阻止数据路径越出 PAM_HOME；
• Schema 升级前自动创建 SQLite 一致性备份；
• pam backup create|list|verify 与 pam restore --yes 提供可验证的本地恢复闭环；
• Scope 删除、Retention 和 GC 默认仅预览，--yes 才执行。

边界与诚实说明

PAM v1.1 是完整的 local-first 开源基线，但不包含服务化能力：

• 没有 PostgreSQL Store 和多租户 IAM；
• 没有网络 MCP、TLS 和限流；
• 没有字段级加密与密钥轮换；
• Hashing Embedding 提供本地模糊相似性，不等同于大模型语义理解；
• Prompt Injection 风险评分是审核信号，不是万能检测器；
• SQLite/WAL/SSD/备份中的旧字节不能通过应用层删除保证物理擦除。

不要把本地 stdio Server 直接暴露到公网，也不要存储密码、Token、支付、医疗、身份或未经授权的机密数据。

文档地图

中文	English
文档中心	Documentation hub
快速开始	Quick start
CLI 参考	CLI reference
架构	Architecture
数据协议	Protocol
MCP 接口	MCP
安全模型	Security
运维手册	Operations
兼容矩阵	Compatibility
开发指南	Development
发布手册	Release
路线图	Roadmap

项目质量

• Python 3.11 / 3.12 / 3.13 CI；
• MCP SDK 1.x / 2.x stdio 集成测试；
• pytest、mypy strict、ruff、compileall；
• SQLite v1→v3 和 AgentPack 1.0→1.1 固定兼容 Fixture；
• Scope、权限、签名、ZIP、删除和 Skill 门禁负向安全测试；
• Apache-2.0、Security Policy、Code of Conduct、Issue/PR 模板。

如果 PAM 对你有帮助

如果你也认为 Agent 的长期记忆和技能应该可携带、可解释、可治理，而不是被锁在某个框架里：

• 给项目一个 ⭐，让更多 Agent 开发者看到它；
• 在 Issue 中分享你希望支持的 Runtime 或实际迁移场景；
• 贡献新的 Adapter、Store 或离线 Embedding Provider；
• 用真实项目验证协议边界，并反馈不够好用的地方。

请先阅读 贡献指南、行为准则 和 安全政策。

---

Build agents freely. Keep their memory portable.

本项目采用 Apache-2.0 License。