cf-agent-memory

Personal agent memory that lives on Cloudflare's free tier. 一个跑在 Cloudflare 免费额度上的个人 Agent 长期记忆服务：MCP 协议接入，语义 + 关键词混合召回，零服务器、零数据库运维。

Claude Code / Cursor / CodeBuddy / 任何 MCP 客户端
                 │  MCP over HTTP
                 ▼
        ┌────────────────────┐
        │  Worker (Hono)     │  鉴权 · 限流 · 路由
        └───┬────────┬───────┘
            │        │
     ┌──────▼──┐  ┌──▼─────────┐
     │   D1    │  │ Vectorize  │   ← 原文 / 全文索引 / 语义索引
     │  SQLite │  │  1024 维    │
     └────┬────┘  └──┬─────────┘
          └────┬─────┘
               ▼
        RRF 融合 + 时间加权  →  top-k 记忆

为什么做这个

市面上的 Agent 记忆方案大多要求你跑一个 Python 服务、维护一个向量库，或者接受 SaaS 的数据托管。个人用其实只需要三件事：

1. 记住值得长期保留的事实、偏好、决策；

2. 召回时不靠模型自觉，而是给一个稳定的检索接口；

3. 不花钱、不运维。

这个项目把这三件事压进一个 Worker：D1 存原文与全文索引，Vectorize 存语义向量，Workers AI 提供 embedding，全部在 Cloudflare 免费额度内。

Related MCP server: MCP Memory

特性

• MCP 原生：12 个工具（记忆 6 + 技能 6），Claude Code、Cursor、CodeBuddy 等直接接入

• 代理注入：把 ANTHROPIC_BASE_URL 指向本服务，自动把召回的记忆与技能列表插进当前轮次，不依赖模型自觉

• 混合召回：语义（Vectorize）+ 关键词（FTS5 + 中文 bigram）+ RRF 融合 + 时间加权，任一路失败自动降级

• 同键覆盖：key='project.database' 写入新值自动 supersede 旧值，不会积累互相矛盾的记忆

• 技能库：SKILL.md 托管 + 版本快照 + R2 资源文件 + 按 agent 分配，同名再导入自动升版本

• 分层字段：l0/l1/l2/l3 + fact/event/instruction/task，为后续的自动提炼留好结构

• REST API：与 MCP 工具一一对应，方便脚本、Web UI、自定义客户端

• 自带面板：单页 Web UI，记忆与技能两个标签页

• 限流：每个用户一个 Durable Object 做固定窗口限流，跨边缘强一致

• 一键部署：npm run setup && npm run deploy，自动创建 D1 / Vectorize / R2 / secret

快速开始

方式一：一键部署（推荐）

点击顶部 Deploy to Cloudflare 按钮。Cloudflare 会克隆仓库到你自己的账号，自动创建 D1、Vectorize 索引和 Durable Object，回填 database_id，并在部署时执行 schema.sql 建表。唯一需要你填的是 ADMIN_TOKEN：

openssl rand -hex 32     # 生成一个，粘到部署页面

也可以在本地部署：

git clone https://github.com/xxynly/cf-agent-memory.git
cd cf-agent-memory
npm install
npx wrangler login     # 只需一次
npm run setup          # 创建 D1 + Vectorize + 表结构 + ADMIN_TOKEN
npm run deploy         # 建表（幂等）后发布 Worker

npm run setup 会打印 ADMIN_TOKEN，并写入 .dev.vars（已 gitignore）；它也可重复执行，已存在的资源会跳过。

方式二：本地调试

npm run setup
npm run dev     # http://localhost:8787

本地调试同样需要远程 D1/Vectorize（--experimental-vectorize-bind-to-prod 已在 dev 脚本外说明，见 docs/deploy.md）。

接入 MCP 客户端

把 <WORKER_URL> 和 <TOKEN> 换成部署输出与 npm run setup 打印的值。

Claude Code（~/.claude.json 或项目 .mcp.json）：

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "https://<WORKER_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <TOKEN>",
        "X-User-Id": "personal"
      }
    }
  }
}

Cursor / CodeBuddy / 其他 MCP 客户端：同样填 HTTP 类型的 URL 与两个 header。

接好之后，让 Agent「记住这个」，它会调用 memory_remember；下次新会话问「我们之前定的数据库是什么」，会走 memory_recall。

代理注入（自动记忆，不依赖模型自觉）

如果你不想依赖模型主动调工具，把客户端指到本服务即可。请求经过时，Worker 会拿最后一条用户消息当 query 召回记忆、列出可用技能，插到那一轮之前，再转发给上游。

# Claude Code
export ANTHROPIC_BASE_URL="https://<WORKER_URL>"
export ANTHROPIC_AUTH_TOKEN="<PROXY_TOKEN>"

# 上游 API key 二选一：
#   1. 存进 Worker：npx wrangler secret put ANTHROPIC_API_KEY
#   2. 或客户端自己带 x-api-key（用谁的就扣谁的额度）

三个可观测响应头，调试时很好用：

body_too_large 是有意的保护：免费层每请求只有 10ms CPU，一个带完整历史的 Claude Code 请求体解析+重新序列化就可能超预算。超过 MAX_PROXY_BODY_BYTES（默认 512KB）就原样转发，最坏情况就是这轮没有记忆——绝不会因为注入把请求搞失败。

代理路由用独立的 PROXY_TOKEN，与 ADMIN_TOKEN 分开：它花的是真实 LLM 额度。没配 PROXY_TOKEN 时该路由返回 503，其他接口不受影响。

详细设计与代价分析见 docs/proxy-injection.md。

工具一览

记忆

技能

REST 接口与之一一对应，见 docs/api.md。

召回是怎么工作的

query ──┬─► Workers AI embedding ──► Vectorize top-20 ─┐
        │                                              ├─► RRF(k=60) ─► 时间加权 ─► top-k
        └─► 分词（latin 词 + 中文 bigram）──► FTS5 top-20 ┘

• 写入和查询用同一个分词函数，避免两边 token 不一致导致召回静默失效

• RRF 不需要两路分数可比，天然适合语义 + 关键词融合

• 时间加权只在相关度接近时起作用（半衰期 30 天，权重 0.15）

• Vectorize 或 embedding 挂掉时自动降级为纯关键词，接口不报错

免费额度够用吗

Vectorize 装不下之后（约 4900 条）：把 embedding 换成 384 维模型（免费额度约 1.3 万条），或只对 l2/l3 建向量、l1 只走关键词。取舍见 docs/architecture.md。

已知限制

• Vectorize 写入有最终一致性：新记忆通常几秒到 1 分钟内可被语义召回命中，关键词召回立即可用

• MCP 是无状态的：每次请求独立，不维护会话；记忆状态都在 D1 里

• 单用户模型：用 X-User-Id 区分，但没有多租户 ACL。多人共用请自行加一层网关

• 中文分词用 bigram：对短句足够，长文档的召回质量不如专业分词器

• 代理只支持 Anthropic 兼容协议：Claude Code / CodeBuddy / WorkBuddy 可直接用；Codex、Cursor 等 OpenAI 协议客户端需要后续适配

• 代理不做响应侧提取：对话不会自动写回记忆，仍需模型调 memory_remember 或调 /v1/ingest

• 代理能看到 LLM Key：客户端自带 x-api-key 时会经过 Worker；介意的话用 Worker 上存的 ANTHROPIC_API_KEY

开发

npm run typecheck
npm test
npm run dev
npm run tail      # 线上日志

目录结构：

src/
├── index.ts          # Hono 路由 + MCP 挂载
├── mcp.ts            # 6 个 MCP 工具
├── auth.ts           # Bearer 鉴权 + DO 限流
├── memory/
│   ├── store.ts      # D1 读写 + FTS5
│   ├── vector.ts     # Workers AI embedding + Vectorize
│   ├── recall.ts     # 混合召回
│   └── ingest.ts     # 批量写入
├── do/user-memory.ts # 每用户限流
└── lib/              # 分词 / RRF / id

路线图

• 对话批量摄入 + 可选 LLM 提炼（L0 → L1）

• 自动去重与冲突检测（除了 key 覆盖之外的语义重复）

• 记忆导出 / 导入（JSON）

• 定时归档：冷数据转 R2，只保留摘要向量

• 多用户 ACL 与共享空间

与同类项目的区别

本项目的定位是「个人用、够用、可维护」：不做团队资产化，但把记忆的写入、覆盖、召回做扎实。

License

MIT