CloudMind

Overview

CloudMind is a BYOC (Bring Your Own Cloud) personal AI memory layer. It runs inside the user's Cloudflare account and keeps raw sources, structured memory, search indexes, and exports under the user's control.

It can ingest URLs, notes, and PDFs; extract and reconcile knowledge; retrieve evidence through lexical, semantic, and graph channels; and expose selective personal or agent working memory to AI clients through MCP.

The current release is v0.3.0. Its roadmap milestones are complete and covered by local gates, GitHub Actions, production smoke checks, and a Worker rollback rehearsal.

Memory Model

CloudMind uses three layers:

Every record also carries three composable dimensions:

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

These dimensions keep record shape, memory owner, and project context independent. Filters use OR within one dimension and AND across dimensions.

CloudMind does not automatically archive complete external conversations. AI clients write selected, high-density memory through remember_agent; users can explicitly archive a complete source or conversation as a library asset.

Capabilities

Architecture

flowchart TD
    Sources["Web / REST / MCP"] --> App["HonoX + Hono Worker"]
    App --> Auth["Single-user auth + MCP tokens"]
    App --> L1["L1 assets + chunks"]
    L1 --> R2["R2 immutable snapshots"]
    L1 --> Queue["Cloudflare Queues"]
    Queue --> AI["Workers AI processing"]
    AI --> L2["L2 graph in D1"]
    AI --> AssetVectors["Asset Vectorize index"]
    L2 --> GraphVectors["Graph Vectorize index"]
    L2 --> Retrieval["Dense + FTS5 + graph retrieval"]
    AssetVectors --> Retrieval
    GraphVectors --> Retrieval
    Retrieval --> L3["L3 Web + MCP memory surface"]

The application is one HonoX full-stack project. Domain behavior stays behind repository, blob, vector, queue, and AI provider ports so D1, R2, Vectorize, Queues, and Workers AI can be replaced later.

Processing Model

Assets enter type-specific workflows:

• note_ingest_v1
• url_ingest_v1
• pdf_ingest_v1

A typical run saves the immutable source, normalizes content, creates chunks, embeds and indexes evidence, extracts graph candidates, reconciles current and historical statements, and then marks the asset ready. A retry reuses the first archived source instead of overwriting it.

Requirements

• Node.js >=24.18.0 <25
• pnpm 10.21.0 through Corepack
• A Cloudflare account and Wrangler login for cloud deployment

Quick Start

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

Replace JWT_SECRET in .dev.vars with a long random value, then initialize the local D1 database and start Vite:

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

The default development URL is http://localhost:5173.

To run through Wrangler's Worker runtime:

pnpm build
pnpm worker:dev

Environment And Bindings

Wrangler-generated binding types live in worker-configuration.d.ts; optional application variables are added in src/env.ts.

Deployment

Fresh Cloudflare Account

The bootstrap script creates account-specific D1, R2, two Vectorize indexes, metadata indexes, Queue resources, and bindings before the first Worker deploy:

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

The first deployment skips production smoke because a public URL may not exist yet. After assigning a workers.dev or custom-domain URL, run:

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

Sign in with the one-time default credentials admin / admin; CloudMind forces an immediate password change.

The generic Cloudflare Deploy Button is intentionally not the fresh-account path. CloudMind requires account-specific storage resources, metadata indexes, and a required secret, all of which are created explicitly by the bootstrap script.

Existing Deployment

pnpm deploy builds the application and then runs the verified release chain:

remote D1 migrations
  -> exact migration verification
  -> Worker deploy
  -> production health, login, and MCP-auth smoke
  -> automatic Worker rollback when post-deploy smoke fails

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 migrations only move forward. Schema changes must remain compatible with the previous Worker version. See the Release and Rollback Runbook.

Web Routes

API Surface

MCP Server

CloudMind exposes a stateless HTTP MCP server at POST /mcp. Requests require a bearer token created from /mcp-tokens.

Each active token can produce generic config JSON or a copyable AI installation prompt. The client identifies its own MCP and Skill setup method, configures CloudMind, installs the cloudmind-memory Skill, verifies the tool catalog, and keeps the token out of logs, repositories, and long-term memory.

The current 20 tools are grouped by responsibility:

Use recall for personal preferences and history. Use recall_agent with an explicit stable project contextKey for prior decisions, progress, blockers, and agent working memory. Use library search for broad source material.

Tool registration lives in src/features/mcp/server/service.ts. The client workflow is documented in skills/cloudmind-memory/SKILL.md.

Data Sovereignty

CloudMind exports D1 business tables, referenced R2 objects, and both vector indexes into a versioned package with a checksummed 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

Restore only accepts explicitly named isolated resources and verifies tables, FTS, foreign keys, objects, and vectors. Read the Data Export and Restore Runbook before use.

Project Structure

app/routes/                         HonoX pages
app/server.ts                       HTTP, Queue, and scheduled entrypoint
src/core/                           domain ports and contracts
src/features/assets/                library and asset lifecycle
src/features/ingest/                text, URL, and PDF ingest
src/features/search/                hybrid and graph retrieval
src/features/memory/                graph, memory lifecycle, and Agent Web
src/features/sovereignty/           hard-delete and data-sovereignty services
src/features/mcp/                   remote MCP server
src/features/workflows/             workflow, Queue, and scheduled consumers
src/platform/                       D1, R2, Vectorize, AI, Queue adapters
drizzle/                            D1 migrations
scripts/ops/                        export, restore, and acceptance operations
scripts/release/                    version, migration, smoke, deploy, rollback
tests/                              unit, eval, and Workers integration tests
docs/模块设计/                       current module documentation

Scripts

Verification

Run the same gate used by GitHub Actions:

pnpm gate
git diff --check

The gate covers strict TypeScript, Biome, unit tests, retrieval eval, production build, generated binding drift, and Miniflare D1/Queue integration tests.

Documentation

• Product north star: docs/vision.md
• Current roadmap: docs/roadmap.md
• Memory architecture: docs/memory-layer-architecture.md
• Current modules: docs/模块设计/
• Release runbook: docs/runbooks/发布与回滚.md
• Export and restore: docs/runbooks/数据导出与恢复.md

Historical roadmaps are kept under docs/roadmap-archive/ and do not describe current project status.

Contributing

• Keep product logic under src/features and infrastructure under src/platform.
• Preserve strict TypeScript and avoid any.
• Add focused tests for service, repository, API, MCP, and state transitions.
• Update the corresponding module document with implementation changes.
• Run pnpm gate before committing.

Project-specific engineering rules live in AGENTS.md.