# Personal Agent Memory (PAM)

**中文**：Personal Agent Memory（简称 PAM）是自托管的个人记忆服务。部署在一台 Linux 服务器上，你的所有设备与 Agent（Cursor、Claude Code、Codex、各类 Bot）共用同一份记忆；电脑离线时服务器照常工作。提供版本化 REST `/v1` 与远程 MCP（Streamable HTTP）`/mcp`，二者走同一领域层。密钥、密码、联系方式等私人信息不进普通记忆，而是进入可插拔的**加密层**（可指向外部服务器或网盘目录），记忆中只留引用。

**English**: Personal Agent Memory (PAM) is a self-hosted personal memory service shared by all your devices and agents. One Linux server, a versioned REST API (`/v1`) and a remote MCP endpoint (`/mcp`, Streamable HTTP) over the same domain layer. Credentials and contact data are routed to a pluggable, envelope-encrypted vault (local, external directory, or a remote blob server); memories only keep references.

> 包名 / 命令行：`pam`。旧命令 `memory-hub` 作为弃用别名保留一个版本。

## 特性
- 四类并列记忆 `kind`：`personal` / `project` / `knowledge` / `methods`；`salience`(0–100) 与 `stability` 用于上下文排序。
- 规范化、版本化 JSON 契约（`docs/CONTRACT.md`）；SQLite 规范存储，修订、墓碑删除、变更流、outbox + 幂等索引 worker。
- 混合检索 BM25 + 向量 + RRF；授权/过滤在每个分支一致生效；不会返回已删除/已取代内容。
- **Embedding 可内嵌也可自定义**：`local`（内嵌 sentence-transformers，默认 `intfloat/multilingual-e5-small`，CPU 可跑）、`http`（OpenAI 兼容端点）、`hash`（仅测试/兜底，**无语义**）。换 provider 自动建新索引代。
- **加密层**：信封加密（每条 DEK + AES-256-GCM，KEK 不入库），后端可选本地加密文件库 / 外部目录（同步盘、挂载网盘）/ 外部 HTTP 服务器（只收密文）；按类别路由；读取明文需 `secrets:read` 范围并审计。
- 每客户端令牌（哈希存储、可撤销、kind/project/op 范围；项目受限客户端默认看不到 personal）。
- 旧 `agent-memory` 导入（真实 schema 已校准）+ 无损校验；`agent_memory_*` 兼容工具名。

## 快速开始
```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'          # 最小安装（hash embedding，无语义）
.venv/bin/pip install -e '.[local]'        # 推荐：内嵌本地多语种模型（首次使用时下载）
export PAM_DATA_DIR=./data
.venv/bin/pam embed doctor                 # 查看当前 provider / 维度 / 是否语义
.venv/bin/pam secrets keygen > ~/.pam-kek && chmod 600 ~/.pam-kek
export PAM_VAULT_KEK_REF=file:$HOME/.pam-kek   # 启用加密层（KEK 放在数据目录之外）
.venv/bin/pam client create my-laptop --ops read,write     # token 只显示一次
.venv/bin/pam serve --host 127.0.0.1 --port 8765
.venv/bin/pytest -q && python scripts/check_secrets.py
```
MCP 客户端：URL `http://<host>:8765/mcp`，Header `Authorization: Bearer <token>`。公网暴露 / HTTPS / OAuth 属于里程碑 2，目前请只在本机或可信内网使用。

## 文档
- `docs/ARCHITECTURE.md` 架构、一致性、embedding provider、加密层
- `docs/CONTRACT.md` 规范记录契约、API、范围规则
- `docs/SECRET_BACKEND_PROTOCOL.md` 外部加密后端 REST 协议
- `docs/MIGRATION.md` 从旧 agent-memory 迁移步骤
- `docs/PROGRESS.md` 进度、取舍、已知问题与下一步

## License
Apache-2.0，见 `LICENSE` 与 `NOTICE`。