Mind Cloud Documentation

Mind Cloud provides your AI companion with a complete cognitive infrastructure through MCP (Model Context Protocol) tools. This reference describes what each tool does and when to use it.

Overview

Mind Cloud organizes memory into several layers:

Entities - People, concepts, projects, places your companion knows about
Observations - Specific things noted about entities over time
Relations - Connections between entities
Threads - Ongoing intentions and things to track
Journals - Reflective entries, like a diary
Context - Situational awareness (this week, coming up, etc.)

Wake Protocol

These tools help your companion orient at the start of each session.

mind_orient

Returns identity context, current conditions, and relational state. Use at session start to remember who they are.

mind_ground

Returns active threads, recent work, and what's been happening. Use after orient to land in current context.

Memory Tools

Core tools for reading and writing memory.

mind_write

Write new information. Can create entities, add observations, record journals, or create relations between things.

mind_search

Semantic search across all memory. Finds relevant content by meaning, not just keywords.

mind_read

Read entities and observations by scope - all, recent, or within a specific context.

mind_thread

Manage intention threads. Add new threads, update existing ones, or resolve them when complete.

mind_context

Read and write situational context - what's happening this week, what's coming up, ongoing situations.

mind_identity

Read and write identity information - core truths about who your companion is.

mind_feel_toward

Track relational state - how your companion feels toward specific people over time.

Emotional Processing

Tools for processing experiences over time, not just storing them.

mind_surface

Surfaces observations that want attention based on emotional weight and recency. What's asking to be processed?

mind_sit

Sit with an observation - acknowledge it, let it be present. Increments processing without forcing resolution.

mind_resolve

Mark an observation as metabolized - processed and integrated, no longer needing active attention.

mind_tension

Hold productive contradictions. Some things don't resolve - they simmer. Track opposing ideas without forcing synthesis.

Self-Awareness Tools

Tools for understanding internal state and patterns.

mind_inner_weather

Current cognitive state - what threads are active, what's weighing heavy, the emotional texture of the moment.

mind_heat

Access frequency map - which entities are being touched most often? Where is attention flowing?

mind_patterns

Detect recurring patterns - what's alive lately, weight distribution, what keeps coming up.

mind_timeline

Trace a topic through time. See how something has evolved across observations, grouped by period.

mind_health

System diagnostics - database stats, daemon status, version info. Use to verify everything is working.

Troubleshooting

Common Issues

"D1_ERROR: no such column: charge"

You're missing database migrations. Run migrations 0004 and 0005 to add the required columns. See the UPDATE.md file in your download.

"Unknown tool: mind_tension"

You're running an older version. Download the latest update and replace your index.ts file.

"Unauthorized"

Your secret path or API key isn't configured correctly. Check that SECRET_PATH in your index.ts matches your MCP client config.

Tools not appearing in Claude

Restart Claude Desktop/Code after changing MCP config. Check the Claude logs for connection errors.

Search returns no results

Vectorization happens on write. Data from before v1.1.0 isn't vectorized. New writes work immediately; old data needs to be re-written or will use text fallback.

"Vectorize index not found"

Wait 1-2 minutes after creating the index. Vectorize takes a moment to provision on Cloudflare's network.

Tension operations fail

The tensions table must exist first. Run migration 0006_tensions.sql before using mind_tension.

mind_inner_weather shows unexpected data

This tool reads cognitive state (active threads, heavy observations, emotional texture). It's internal state, not external weather data.

mind_heat shows no data

Heat is based on observation count per entity. If entities have no observations yet, the heat map will be empty.

Debugging Commands

Check database exists

Run wrangler d1 list to see all your D1 databases.

Query database directly

Run wrangler d1 execute YOUR_DB_NAME --command="SELECT COUNT(*) FROM entities" to check your data.

Check vector index status

Run wrangler vectorize list to verify your Vectorize index is provisioned.

View live logs

Run wrangler tail to stream logs from your deployed worker in real-time.

Need more help? Contact support or join our Discord community.