AI Cloud Memory Community Edition

Your own shared memory, project board and long-term roadmap for AI clients, running in your Cloudflare account and owned through your GitHub identity.

AI Cloud Memory gives Codex, Claude Code, OpenCode and compatible web clients one authenticated MCP endpoint for durable memory and project lifecycle work. D1 is canonical. Search works in lexical and temporal mode by default, while Vectorize and Workers AI can be enabled later for semantic retrieval and reranking.

No n8n, home server, vendor account or service operated by this project is required. Each adopter deploys an isolated copy to their own Cloudflare and GitHub accounts.

What you get

• Owner-only GitHub OAuth and scoped MCP OAuth

• Memories and standing directives with provenance, labels, archive, supersession and review

• Projects, Kanban tasks, completion receipts, archived work and Done history

• Longer-term project roadmaps with safe promotion into tasks

• Temporal query handling, bounded ranking boosts and semantic deduplication

• Explainable search results and a private relevance benchmark

• Managed Obsidian Markdown projection and portable encrypted exports

• Responsive dashboard designed for desktop and mobile Safari

• 24 narrowly scoped cloudmemory_* MCP tools

• Optional connectors and automation credentials, without making an automation platform a dependency

Architecture

Codex · Claude · OpenCode · compatible web clients
                         │
                 OAuth-protected MCP
                         │
             Cloudflare Worker + dashboard
                ┌────────┼────────┐
                │        │        │
               D1       KV    Static assets
           canonical   OAuth      UI
                │
       optional derived services
       Vectorize · Workers AI
                │
       optional encrypted export
             your GitHub repo

The Worker, database, OAuth state and optional AI index belong to the adopter. The public project has no central memory service and no access to deployed instances. See Architecture and Privacy.

Deploy

1. Create your copy

Use the Deploy to Cloudflare button above. Cloudflare can create a GitHub copy and provision supported Worker bindings from wrangler.jsonc.

If automatic Vectorize provisioning is unavailable in your account, create the optional index before enabling semantic search:

npx wrangler vectorize create ai-cloud-memory --dimensions=768 --metric=cosine

Keep SEMANTIC_SEARCH_ENABLED=false until that index exists. The base product does not call Workers AI or Vectorize in this mode.

2. Choose the final URL

Use the generated workers.dev origin or attach your final custom domain. Record the exact HTTPS origin without a trailing slash, for example:

https://ai-cloud-memory.your-subdomain.workers.dev

Set PUBLIC_ORIGIN to that origin. auto is useful only during initial deployment. Setting the final origin before creating GitHub OAuth avoids a second OAuth callback migration.

3. Create a GitHub OAuth App

In GitHub, open Settings → Developer settings → OAuth Apps → New OAuth App.

Record the client ID and generate a client secret. Never commit the secret.

4. Configure the owner lock

Set these non-secret Worker variables in wrangler.jsonc or the Cloudflare dashboard:

ALLOWED_GITHUB_USER_ID=your numeric GitHub user ID
ALLOWED_GITHUB_LOGIN=your GitHub login
PUBLIC_ORIGIN=https://your-final-origin.example
SEMANTIC_SEARCH_ENABLED=false

The numeric user ID is the immutable security boundary; the login is display metadata. Set the secrets from a trusted terminal:

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY

5. Migrate and deploy

npm ci
npm run check
npm run deploy

The deploy command intentionally publishes twice on a fresh account: the first pass lets Cloudflare auto-provision declared resources, migrations then initialise D1, and the final pass becomes the verified application release. The placeholder owner lock keeps the bootstrap deployment inaccessible until you replace it.

Then open /setup.html on your deployed origin for the local, browser-only checklist. Full instructions are in Deployment and Onboarding.

Connect an AI client

Your remote MCP endpoint is:

https://your-final-origin.example/mcp

Common native clients:

# Codex
codex mcp add cloud-memory --url https://your-final-origin.example/mcp

# Claude Code
claude mcp add --transport http cloud-memory https://your-final-origin.example/mcp

OpenCode can use a remote MCP entry in opencode.json:

{
  "mcp": {
    "cloud-memory": {
      "type": "remote",
      "url": "https://your-final-origin.example/mcp",
      "enabled": true
    }
  }
}

Complete OAuth separately in every client. Verify cloudmemory_health, cloudmemory_board, a harmless search and one explicitly approved write. Web-client capabilities and plan restrictions vary. See Client setup.

Required and optional services

Cloudflare’s limits and pricing can change. Check the current Workers pricing, D1 pricing, Vectorize pricing and Workers AI pricing before enabling optional services. This project does not enable paid usage or billing on your behalf.

Semantic search

The safe default is lexical-only:

SEMANTIC_SEARCH_ENABLED=false

New memories remain canonical in D1 with a pending vector state. When you set the variable to true, deploy, then choose Repair index in Settings, Cloud Memory backfills vectors in bounded batches. The configured BGE model uses a 768-dimensional cosine index. See Semantic search.

Backups and recovery

The dashboard can create an encrypted download without a GitHub token. Optional GitHub delivery needs:

• EXPORT_ENCRYPTION_KEY, retained somewhere safe outside the repository

• GITHUB_EXPORT_TOKEN, a fine-grained token scoped to Contents access on one backup repository

• GITHUB_EXPORT_REPOSITORY, in owner/repository form

Losing the encryption key makes existing encrypted exports unrecoverable. D1 remains canonical; Obsidian and GitHub outputs are projections and recovery artefacts, not concurrent writers.

Local development

Requires Node.js 22.12 or newer.

npm ci
npm run dev
npm run check

The complete check runs repository safety validation, deployment-template validation, lint, type checking, unit tests, Worker/D1 tests and a production build.

Project governance

• Security policy

• Contributing

• Support

• Code of Conduct

• Changelog

Codex Cloud automated review is not part of AI Cloud Memory. Maintainers may connect this GitHub repository to a Codex Cloud environment as external repository administration; no review agent, token or feature is shipped in the product.

Licence

MIT. Cloudflare, GitHub, Claude, ChatGPT, Codex, OpenCode, Obsidian and n8n are trademarks of their respective owners and are not affiliated with this project.