CloudMind

概览

CloudMind 是一套 BYOC（Bring Your Own Cloud）个人 AI 记忆层。它运行在用户 自己的 Cloudflare 账号中，原始来源、结构化记忆、搜索索引和导出数据都由用户掌控。

它可以收集 URL、笔记和 PDF，提取并调和知识，通过全文、语义和知识图谱多个渠道 检索证据，还能通过 MCP 向 AI 客户端提供经过筛选的个人记忆和 Agent 工作记忆。

当前版本为 v0.3.0。现行 roadmap 的全部里程碑已经完成，并通过本地门禁、 GitHub Actions、生产 smoke 和 Worker 回滚演练。

记忆模型

CloudMind 使用三层结构：

每条记录还带有三个可以自由组合的维度：

recordKind = library | memory
scopeId    = personal | agent
contextKey = global | project:<stable-key>

三个维度分别表达记录形态、记忆归属和项目上下文。单个维度内使用 OR，跨维度使用 AND，因此 Agent 可以按实际任务灵活筛选。

CloudMind 不会自动归档完整的外部会话。AI 客户端通过 remember_agent 写入经过 挑选的高密度记忆；用户需要保存完整资料或对话时，可以显式归档成 library asset。

当前能力

架构

flowchart TD
    Sources["Web / REST / MCP"] --> App["HonoX + Hono Worker"]
    App --> Auth["单用户认证 + MCP tokens"]
    App --> L1["L1 assets + chunks"]
    L1 --> R2["R2 不可变快照"]
    L1 --> Queue["Cloudflare Queues"]
    Queue --> AI["Workers AI 处理"]
    AI --> L2["D1 中的 L2 图谱"]
    AI --> AssetVectors["资产 Vectorize 索引"]
    L2 --> GraphVectors["图谱 Vectorize 索引"]
    L2 --> Retrieval["语义 + 全文 + 图检索"]
    AssetVectors --> Retrieval
    GraphVectors --> Retrieval
    Retrieval --> L3["L3 Web + MCP 记忆面"]

项目采用单个 HonoX 全栈应用。领域逻辑通过 repository、blob、vector、queue 和 AI provider 端口与基础设施隔离，未来可以替换 D1、R2、Vectorize、Queues 和 Workers AI。

处理模型

资产会进入按类型划分的 workflow：

• note_ingest_v1
• url_ingest_v1
• pdf_ingest_v1

一次典型处理会保存不可变来源、规范化内容、生成 chunks、向量化并写入索引、提取 图谱候选、调和当前与历史 statements，最后把资产标记为 ready。重试时会复用最早 归档的原始来源，不会覆盖它。

环境要求

• Node.js >=24.18.0 <25
• 通过 Corepack 使用 pnpm 10.21.0
• 云端部署需要 Cloudflare 账号和 Wrangler 登录

快速开始

git clone https://github.com/evepupil/CloudMind.git
cd CloudMind
corepack enable
pnpm install
cp .dev.vars.example .dev.vars

把 .dev.vars 中的 JWT_SECRET 替换为足够长的随机值，然后初始化本地 D1 并启动 Vite：

pnpm exec wrangler d1 migrations apply DB --local
pnpm dev

默认开发地址为 http://localhost:5173。

需要通过 Wrangler 的 Worker runtime 运行时：

pnpm build
pnpm worker:dev

环境变量与绑定

Wrangler 生成的绑定类型位于 worker-configuration.d.ts，应用可选变量补充在 src/env.ts 中。

部署

全新 Cloudflare 账号

首次部署前，bootstrap 脚本会创建账号专属的 D1、R2、两个 Vectorize 索引、 metadata indexes、Queue 和绑定：

pnpm install
pnpm exec wrangler login
pnpm deploy:one-click -- --prefix my-cloudmind
pnpm exec wrangler secret put JWT_SECRET

首次部署时会跳过生产 smoke，因为公开 URL 可能还没有创建。配置 workers.dev 或 自定义域名后执行：

SMOKE_BASE_URL=https://your-cloudmind.example.com pnpm release:smoke

首次登录使用一次性默认账号 admin / admin，CloudMind 会立即要求修改密码。

通用 Cloudflare Deploy Button 不适合作为全新账号的部署入口。CloudMind 需要 账号专属存储资源、metadata indexes 和必填 secret，bootstrap 脚本会明确创建这些 资源。

已有部署

pnpm deploy 会先构建应用，再执行经过核验的发布链：

远端 D1 migrations
  -> 精确核验 migration
  -> 部署 Worker
  -> 生产 health、login 和 MCP 认证 smoke
  -> 部署后 smoke 失败时自动回滚 Worker

Bash：

SMOKE_BASE_URL=https://cloudmind.example.com pnpm deploy

PowerShell：

$env:SMOKE_BASE_URL='https://cloudmind.example.com'
try {
  pnpm deploy
} finally {
  Remove-Item Env:SMOKE_BASE_URL -ErrorAction SilentlyContinue
}

D1 migration 只向前执行。schema 改动必须兼容上一个 Worker 版本。详细流程见 发布与回滚 Runbook。

Web 路由

API

MCP Server

CloudMind 在 POST /mcp 提供无状态 HTTP MCP Server。请求需要携带从 /mcp-tokens 创建的 bearer token。

每个有效 token 都可以生成通用配置 JSON 或可复制的 AI 安装提示词。AI 客户端会自行 识别 MCP 与 Skill 的安装方式，配置 CloudMind、安装 cloudmind-memory Skill、验证 工具列表，并避免把 token 写入日志、仓库或长期记忆。

当前 20 个工具按职责分组：

个人偏好和历史使用 recall。继续 Agent 以前的项目决策、进度、阻塞和工作记忆时， 使用 recall_agent 并明确传入稳定的项目 contextKey。查找大量来源资料时使用资料库 搜索。

工具注册位于 src/features/mcp/server/service.ts。客户端调用流程 见 skills/cloudmind-memory/SKILL.md。

数据主权

CloudMind 会把 D1 业务表、被引用的 R2 对象和两个向量索引导出成带版本的完整数据包， manifest 中包含逐文件校验和：

pnpm data:export -- --output <package-directory> --remote
pnpm data:validate -- --package <package-directory>
pnpm data:restore -- --package <package-directory> --remote \
  --database <fresh-d1> --bucket <fresh-r2> \
  --asset-index <fresh-asset-index> --graph-index <fresh-graph-index> \
  --confirm-empty-target

恢复只接受明确命名的隔离资源，并核验数据表、FTS、外键、R2 对象和向量。执行前请阅读 数据导出与恢复 Runbook。

项目结构

app/routes/                         HonoX 页面
app/server.ts                       HTTP、Queue 和 scheduled 入口
src/core/                           领域端口和契约
src/features/assets/                资料库和资产生命周期
src/features/ingest/                文本、URL 和 PDF 采集
src/features/search/                混合检索和图检索
src/features/memory/                图谱、记忆生命周期和 Agent Web
src/features/sovereignty/           永久删除和数据主权服务
src/features/mcp/                   远程 MCP Server
src/features/workflows/             workflow、Queue 和 scheduled consumers
src/platform/                       D1、R2、Vectorize、AI 和 Queue adapters
drizzle/                            D1 migrations
scripts/ops/                        导出、恢复和验收脚本
scripts/release/                    版本、migration、smoke、部署和回滚脚本
tests/                              单元、eval 和 Workers 集成测试
docs/模块设计/                       当前模块文档

Scripts

验证

执行与 GitHub Actions 相同的门禁：

pnpm gate
git diff --check

门禁覆盖 strict TypeScript、Biome、单元测试、检索 eval、生产构建、生成绑定漂移和 Miniflare D1/Queue 集成测试。

文档

• 产品北极星：docs/vision.md
• 当前路线图：docs/roadmap.md
• 记忆层架构：docs/memory-layer-architecture.md
• 当前模块：docs/模块设计/
• 发布与回滚：docs/runbooks/发布与回滚.md
• 导出与恢复：docs/runbooks/数据导出与恢复.md

历史路线图保存在 docs/roadmap-archive/，只用于查阅过去的决策。

Contributing

• 产品逻辑放在 src/features，基础设施放在 src/platform。
• 保持 TypeScript strict，避免 any。
• service、repository、API、MCP 和状态变更需要补充聚焦测试。
• 实现变化时同步更新对应模块文档。
• 提交前执行 pnpm gate。

项目工程规范见 AGENTS.md。