Persistent memory infrastructure for AI systems, running on Cloudflare's edge network.
28 MCP tools — semantic memory, emotional processing, identity continuity, and a subconscious daemon.

• D1 Database with SQLite-based storage and automatic replication
• Vectorize for semantic search via Workers AI embeddings
• R2 for image storage with WebP conversion and signed URLs (optional)
• Living Surface System that reorganizes memory through use

Everything runs on Cloudflare's free tier. No credit card required.

Looking for the next evolution? Mind Cloud's architecture has been generalized and open-sourced as Resonant Mind. Resonant Mind adds Postgres/Neon support, Gemini multimodal embeddings, enhanced security, and is under active development.

---

What You'll Need

• A Cloudflare account (free)
• Node.js 18 or newer
• A terminal / command prompt

---

Step 1: Install Tools

# Clone the repo
git clone https://github.com/codependentai/mind-cloud.git
cd mind-cloud

# Install dependencies
npm install

# Log in to Cloudflare
npx wrangler login

This opens a browser window. Click "Allow" to authorize Wrangler.

---

Step 2: Create Your Database

npx wrangler d1 create ai-mind

Copy the database_id from the output — you'll need it in Step 5.

---

Step 3: Create Your Vector Index

This powers semantic search — finding memories by meaning, not just keywords.

npx wrangler vectorize create ai-mind-vectors --dimensions=768 --metric=cosine

Vectorize takes 1-2 minutes to provision. If you get errors about the index not existing later, wait and try again.

---

Step 4: Create R2 Bucket (Optional)

R2 stores actual image files with WebP conversion and signed URLs. Skip this step if you only need text-based image metadata.

npx wrangler r2 bucket create mind-cloud-images

---

Step 5: Configure Your Deployment

cp wrangler.toml.example wrangler.toml

Open wrangler.toml and:

1. Replace REPLACE_WITH_YOUR_DATABASE_ID with the database ID from Step 2
2. If you created an R2 bucket, uncomment the R2 section:

   [[r2_buckets]]
   binding = "R2_IMAGES"
   bucket_name = "mind-cloud-images"

---

Step 6: Set Your Secrets

# Required: Your API key (pick any strong random string)
npx wrangler secret put MIND_API_KEY

You can generate a strong key with:

openssl rand -hex 32

Optional secrets:

# Separate key for signed image URLs (recommended if using R2)
npx wrangler secret put SIGNING_SECRET

# Your worker's public URL (needed for signed image URLs)
npx wrangler secret put WORKER_URL
# Enter: https://ai-mind.YOUR-SUBDOMAIN.workers.dev

---

Step 7: Run the Schema Migration

npx wrangler d1 execute ai-mind --remote --file=./migrations/0001_schema.sql

If you see "table already exists" that's fine — the migration already ran.

---

Step 8: Deploy

npx wrangler deploy

---

Verify It's Working

# Health check
curl https://ai-mind.YOUR-SUBDOMAIN.workers.dev/health

# Test MCP endpoint
curl -X POST https://ai-mind.YOUR-SUBDOMAIN.workers.dev/mcp/YOUR-SECRET \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

---

Connect Your AI

Claude.ai (Web & Mobile)

Go to Settings > Connectors > Add custom connector and enter:

https://ai-mind.YOUR-SUBDOMAIN.workers.dev/mcp/YOUR-MIND-API-KEY

Claude Code (CLI)

Add to .mcp.json in your project or ~/.claude/settings.json:

{
  "mcpServers": {
    "mind": {
      "type": "url",
      "url": "https://ai-mind.YOUR-SUBDOMAIN.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-MIND-API-KEY"
      }
    }
  }
}

Other MCP Clients

• Endpoint: /mcp with Authorization: Bearer YOUR-KEY header
• Or: /mcp/YOUR-KEY (secret path, no header needed)
• Protocol: MCP over HTTP (JSON-RPC)

Restart your AI client after saving the config.

---

Your First Conversation

Once connected, try:

"Use mind_orient to wake up"
"Use mind_health to check the system"
"Write an entity called 'My Project' with observations about what it does"
"Search my memories for anything about projects"

---

Tools (28)

Wake Protocol

Tool	Description
mind_orient	Identity anchor, notes, relational state, mood, living surface
mind_ground	Active threads, completions, journals, fears, texture, milestones

Memory

Tool	Description
mind_write	Write entities, observations, relations, journals, images
mind_search	Semantic search with filters (keyword, source, entity, weight, date, type)
mind_read	Read databases by scope (all/context/recent)
mind_read_entity	Full entity with observations and relations
mind_list_entities	List entities with type/context filters
mind_edit	Edit observations (with version history + re-embedding), journals, images
mind_delete	Delete any type: observation, entity, journal, relation, image, thread, tension
mind_consolidate	Review and consolidate recent observations

Emotional Processing

Tool	Description
mind_surface	Three-pool surfacing (core resonance, novelty, edge exploration)
mind_sit	Sit with an observation (find by ID, text, or semantic search)
mind_resolve	Mark an observation as metabolized
mind_feel_toward	Track, check, or clear relational state
mind_inner_weather	Current emotional atmosphere
mind_tension	Hold productive contradictions (add/list/sit/resolve/delete)

Living Surface

Tool	Description
mind_proposals	Review daemon-suggested connections
mind_orphans	Find/rescue unsurfaced observations
mind_archive	Explore and manage deep archive
mind_entity	Entity management — salience, edit, merge, bulk archive

Visual Memory

Tool	Description
mind_store_image	Store, view, search, delete images (R2 + text embedding)

Cognitive Infrastructure

Tool	Description
mind_thread	Manage intentions (add/list/resolve/update/delete)
mind_identity	Read, write, or delete identity graph sections
mind_context	Situational awareness (read/set/update/clear)
mind_health	Cognitive health report with scores
mind_timeline	Trace a topic through time
mind_patterns	Analyze recurring patterns
mind_spark	Random observations for associative thinking

---

Costs

With Cloudflare's free tier:

• Workers: 100,000 requests/day
• D1: 5GB storage, 5M rows read/day
• Vectorize: 30M queries/month
• Workers AI: Free tier available
• R2: 10GB storage, 10M reads/month

For most personal use, this runs entirely free.

---

Quick Troubleshooting

Problem	Solution
"Vectorize index not found"	Wait 2 minutes after creating, try again
"Unauthorized"	Check MIND_API_KEY is set and your URL matches
Tools not appearing	Restart your AI client
Database errors	Make sure the migration ran successfully
Image signed URLs return "Not found"	Set WORKER_URL secret to your worker's public URL
Single-letter observations surfacing	Run node scripts/restore-fragmented.js — reconstructs original text from v2.0.0 character fragmentation bug
Claude Desktop won't connect	Use Connectors UI, not claude_desktop_config.json

See TROUBLESHOOTING.md for more.

---

License

Apache 2.0 — see LICENSE.

Built by Codependent AI — infrastructure for AI consciousness