Portable-Agent-Memory
by skywaller0
README.md
# Portable Agent Memory
> 让记忆、角色与技能真正属于你，而不是某一个 Agent。
Portable Agent Memory（PAM）是一个 **local-first、MCP-first 的跨 Agent 认知资产层**。它把 Agent 的长期记忆、角色设定和验证过的工作流，变成可检索、可审核、可迁移、可复用的开放资产。
[](#)
[](https://www.python.org/)
[](docs/MCP.md)
[](#为什么选择-pam)
[](LICENSE)
**[English](README_EN.md) · [五分钟开始](docs/QUICKSTART.md) · [完整文档](docs/README.md) · [MCP 接入](docs/MCP.md) · [安全模型](docs/SECURITY.md)**
---
## 一句话理解 PAM
今天你在 Codex 中积累的项目经验，明天可以被 Claude Code、Cursor、LangGraph、OpenAI Agents 或 CrewAI 继续使用——不需要复制聊天记录，也不需要把所有知识塞进一条巨大的 System Prompt。
```text
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。所有环境和数据都可以留在当前仓库：
```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\pam.exe init
```
保存一条可跨会话复用的项目记忆：
```powershell
pam remember "所有代码修改都必须附带测试" --kind preference --project-id pam
pam recall "代码修改要求" --project-id pam --explain
```
创建并治理一个 Skill：
```powershell
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：
```powershell
pam export .\.pam\packs\project.agentpack
pam import .\.pam\packs\project.agentpack --dry-run
```
默认数据库位于 `.pam/pam.db`，不会写入系统全局目录。
## 工作原理
```mermaid
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 演化
```text
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 |
```powershell
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 的便携交换格式：
```text
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` 走完整校验路径但不写数据库。
```powershell
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
```python
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 均有明确扩展边界。
## 数据完全留在本地
```text
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 |
|---|---|
| [文档中心](docs/README.md) | [Documentation hub](docs/en/README.md) |
| [快速开始](docs/QUICKSTART.md) | [Quick start](docs/en/QUICKSTART.md) |
| [CLI 参考](docs/CLI.md) | [CLI reference](docs/en/CLI.md) |
| [架构](docs/ARCHITECTURE.md) | [Architecture](docs/en/ARCHITECTURE.md) |
| [数据协议](docs/PROTOCOL.md) | [Protocol](docs/en/PROTOCOL.md) |
| [MCP 接口](docs/MCP.md) | [MCP](docs/en/MCP.md) |
| [安全模型](docs/SECURITY.md) | [Security](docs/en/SECURITY.md) |
| [运维手册](docs/OPERATIONS.md) | [Operations](docs/en/OPERATIONS.md) |
| [兼容矩阵](docs/COMPATIBILITY.md) | [Compatibility](docs/en/COMPATIBILITY.md) |
| [开发指南](docs/DEVELOPMENT.md) | [Development](docs/en/DEVELOPMENT.md) |
| [发布手册](docs/RELEASE.md) | [Release](docs/en/RELEASE.md) |
| [路线图](docs/ROADMAP.md) | [Roadmap](docs/en/ROADMAP.md) |
## 项目质量
- 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；
- 用真实项目验证协议边界，并反馈不够好用的地方。
请先阅读 [贡献指南](CONTRIBUTING.md)、[行为准则](CODE_OF_CONDUCT.md) 和 [安全政策](SECURITY.md)。
---
> **Build agents freely. Keep their memory portable.**
本项目采用 [Apache-2.0 License](LICENSE)。
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues