内容
# memlawb
[](https://github.com/Gitlawb/memlawb/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@gitlawb/memlawb)
[](#license)
**开源、可自行托管、零知识证明的智能代理内存。**
内存层是智能代理栈的一部分 — 为任意智能代理提供持久性内存，可跨会话存储，数据存储在服务器上，但服务器无法读取。
> Gitlawb 栈的一部分：opengateway（推理）·
> node（代码）· openclaude（智能代理）· **memlawb（内存）**。
---
## 为什么
智能代理在会话之间会忘记所有事情。现有的解决方案 — 将内存同步到供应商的云端 — 意味着第三方可以读取智能代理学习到的关于您和您的代码的一切。memlawb 是另一种选择：
- **零知识证明。** 内存会在您的机器上加密后上传。服务器仅存储和提供密文（AES-256-GCM，密钥从您的通行短语中导出）。我们提供存储服务，但我们无法读取。
- **可自行托管。** 一个二进制文件，可插入存储（文件系统，S3/Tigris/R2，更多）。在我们的云端或您自己的服务器上运行。
- **提供者中立。** 内置的 **MCP 服务器** 为 Claude Code、Cursor、opencode 和 SDK 智能代理提供内存工具（`memory_save`/`recall`/`search`/`list`/`delete`）；一个简单的同步 API 任何智能代理都可以访问。
- **增量同步。** 确定性加密意味着只有更改的条目会被上传，即使服务器从未看到明文。
- **机密感知。** 客户端扫描器拒绝上传可能包含活动凭证的条目 — 在它们被加密或发送之前。
## 工作原理
```
智能代理 / CLI / MCP
│ 明文输入，明文输出
▼ [ client/crypto.ts — 使用从通行短语导出的密钥加密 ]
│ 密文
▼
memlawb 服务器（加密盲服务器 — 仅看到密文）
▼
BlobStore: fs | s3 (Tigris/R2/AWS) | ipfs/git （计划中）
```
服务器是 **加密盲服务器**：它对密文执行增量同步、重复数据删除和存储。加密密钥永远不会离开客户端。
## 快速入门（自行托管）
```bash
bun install
# 1. 运行服务器（文件系统存储，单用户开放模式）
ALLOW_UNAUTHENTICATED=true STORE=fs DATA_DIR=./data bun run src/index.ts
# 2. 同步内存目录，端到端加密
export MEMLAWB_URL=http://localhost:8080
export MEMLAWB_PASSPHRASE='your-zero-knowledge-passphrase' # 永远不会发送到服务器
bun run bin/memlawb.ts push ./my-memories user:me # 加密 + 上传
bun run bin/memlawb.ts pull ./restored user:me # 下载 + 解密
```
服务器上存储的是密文 — 在您的 `grep` 数据目录中查找任何明文，您将找不到。
> ⚠️ **零知识证明意味着无法恢复。** 如果您丢失了通行短语，主机
> 无法帮助您 — 数据对除密钥持有者之外的所有人都是不可读的。请备份您的通行短语。
## 作为库使用
```ts
import { MemlawbClient } from '@gitlawb/memlawb'
const memory = new MemlawbClient({
url: 'https://memory.gitlawb.com',
apiKey: process.env.MEMLAWB_API_KEY,
passphrase: process.env.MEMLAWB_PASSPHRASE, // 保存在本地
})
await memory.push('user:me', { 'MEMORY.md': '# 我知道关于用户的...' })
const { entries } = await memory.pull('user:me')
```
## 从任意智能代理（MCP）使用
memlawb 在同一个包中提供了一个 MCP 服务器，因此任何支持 MCP 的智能代理都可以通过添加一个配置块来获得持久的加密内存。添加到您的客户端的 MCP 配置中（Claude Code 示例）：
```json
{
"mcpServers": {
"memlawb": {
"command": "bunx",
"args": ["-y", "@gitlawb/memlawb", "mcp"],
"env": {
"MEMLAWB_URL": "https://memory.gitlawb.com",
"MEMLAWB_API_KEY": "mk_live_...",
"MEMLAWB_PASSPHRASE": "your-zero-knowledge-passphrase",
"MEMLAWB_NAMESPACE": "user:me"
}
}
}
}
```
MCP 服务器在本地运行，持有通行短语，并在进程中加密/解密 — 因此远程服务器仍然只看到密文。工具：
| 工具 | 用途 |
|---|---|
| `memory_save(key, content)` | 持久保存一个事实 |
| `memory_recall(query)` | 按相关性排序存储的记忆（本地） |
| `memory_search(query)` | 字面关键词/子字符串搜索 |
| `memory_list()` | 列出条目键 |
| `memory_delete(key)` | 删除一个条目 |
对于自行托管，省略 `MEMLAWB_API_KEY` 并将 `MEMLAWB_URL` 指向您的服务器。
### 教会智能代理使用内存
工具本身并不能使智能代理很好地使用内存 — 它需要 *自律*
（在回答前回忆，保存持久的事实，不要重复）。这存在于一个地方，[`skills/memlawb-memory/SKILL.md`](./skills/memlawb-memory/SKILL.md):
- **Claude Code:** 将其作为技能安装（将文件夹放入您的技能目录），智能代理在内存相关时读取它。
- **任意 MCP 客户端：** 服务器通过 `memory_guide` 提示和其启动 `instructions` 中的简短版本公开相同的文本，因此 Cursor / opencode / SDK 智能代理无需单独的文件即可获得协议。
## API
所有正文都是密文；服务器在不解密的情况下验证大小/哈希。
| 方法 | 路由 | 用途 |
|---|---|---|
| `GET` | `/health` | 存活性和活动存储 |
| `GET` | `/api/memory/:ns` | 完整数据（密文条目 + 校验和） |
| `GET` | `/api/memory/:ns?view=hashes` | 每个密钥的校验和（用于增量） |
| `PUT` | `/api/memory/:ns` | 增量更新 `{ entries, deletions? }` |
| `DELETE` | `/api/memory/:ns?key=<entryKey>` | 删除一个条目 |
命名空间（`user:me`、`repo:owner/name`、`agent:intern`）是作用域的单位。条目键镜像 memdir 布局（`MEMORY.md`、`feedback/x.md`）。
## 配置
参见 [`.env.example`](./.env.example)。主要参数：`STORE`（`fs`|`s3`）、
`ALLOW_UNAUTHENTICATED`、`STATIC_API_KEYS` / Supabase 认证和每个命名空间的大小/计数限制。
## 安全模型
- **加密：** AES-256-GCM；密钥 = `scrypt(passphrase, salt=sha256("memlawb:"+namespace))`。
- **完整性：** 条目键是 GCM 附加认证数据，因此 blob 与其密钥绑定，不能交换或重放。
- **确定性：** 合成 IV 启用增量同步；唯一的泄漏是
两个条目是否是字节相同的。
- **纵深防御：** 客户端秘密扫描器在加密和（默认情况下）阻止上传包含类似实时凭证的内容。覆盖 `MEMLAWB_SCAN=warn|off`。
- **租户隔离：** 每个 API 密钥映射到一个所有者，该所有者控制其自己的 `user:<owner>` 命名空间子树（严格的分段匹配，无子字符串转义）；
每个帐户的配额和每个所有者的速率限制在服务器端强制执行。
- **升级路径：** 每个 blob 上的版本号允许迁移到
XChaCha20-Poly1305 + Argon2id 而不会破坏现有数据。
参见 [`PLAN.md`](./PLAN.md) 以获取完整的路线图（MCP 服务器、openclaude 插件、
git-backed 签名历史、共享/分叉、计费）。
## 状态
**测试版。** 加密盲服务器、客户端加密、CLI、MCP 服务器、秘密扫描器、
每个帐户的配额和速率限制已实现并测试（`bun test` — 50 个测试）。在 `memory.gitlawb.com` 上免费托管测试版。接下来：
自行服务控制台、openclaude 原生插件和 Postgres 索引用于水平扩展（托管测试版运行在单个机器上 —
参见 [`PLAN.md`](./PLAN.md) §7）。
## 开发
```bash
bun install
bun test # 运行测试套件
bun run type-check # tsc --noEmit
bun run check # biome lint + 格式检查
```
对于贡献者，代码库根据信任边界干净地分为：
```
client/ 零知识客户端 — 在此处加密；持有密钥
src/ 加密盲服务器 — 仅看到密文
src/mcp/ 客户端上的 MCP 服务器（内存工具）
bin/ CLI（push | pull | mcp | serve）
```
基本规则：**明文、通行短语和派生密钥永远不会到达服务器。**
参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 以获取完整的指南。
## 贡献
欢迎提出问题和 PR。请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)（开发设置、设计原则、Conventional Commits、DCO 签署）和我们的
[行为准则](./CODE_OF_CONDUCT.md)。
## 安全
memlawb 是安全软件。请私下报告漏洞 — **不要公开问题。**
参见 [SECURITY.md](./SECURITY.md) 以获取流程和威胁模型。
## 许可证
在 [MIT](./LICENSE-MIT) 或 [Apache-2.0](./LICENSE-APACHE) 下双重许可，您可任选其一。贡献者在相同的双重许可下被接受（参见 SPDX 头文件和 [CONTRIBUTING.md](./CONTRIBUTING.md)）。
