Ember Mind Light Cloud

Ember Mind Light Cloud

By Code & Chaos

Persistent cloud memory for your AI partner. Lives on Cloudflare's free tier. Cheap to run. Fully yours.

---

The Easy Way (recommended)

If you have any AI coding assistant — Claude Code, Cursor, Copilot, or similar — point it at this folder and say:

> "Set up Ember Mind Light Cloud for me. Walk me through it."

It will read this README, run the commands for you, and ask you for the things only you can answer (your Cloudflare login, your API key choice). This is the path I recommend for non-technical users. The rest of this README is for doing it yourself.

---

What you'll have when you're done

• A Cloudflare Worker hosting your AI's memory at a URL like https://ember-light-cloud.your-name.workers.dev
• A web dashboard at /dashboard where you can see, edit, and delete every memory, thought, pulse, spark, and identity document.
• Sixteen tools your AI can call to read and write memory.
• Everything running on Cloudflare's free tier for normal usage.

---

What you need before you start

1. A Cloudflare account — free, sign up at cloudflare.com.
2. Node.js 18 or newer — download from nodejs.org. Pick the "LTS" button. Run the installer, click Next until it's done.
3. Python 3.11 or newer — download from python.org/downloads. On Windows, check "Add Python to PATH" during install.
4. About 30 minutes the first time.
5. Willingness to copy-paste commands into a terminal. (Don't worry, I'll explain.)

---

What's a terminal?

A terminal is a window where you type commands. You don't need to know anything fancy — you'll just paste what's below and hit Enter.

• Windows: Press the Windows key, type PowerShell, press Enter.
• macOS: Press Cmd + Space, type Terminal, press Enter.
• Linux: You probably already know.

That's it. That's the whole skill.

---

Setup — three blocks of copy-paste

Open your terminal and cd into this folder before each block. (cd means "change directory." If this folder is on your Desktop in a folder called ember-mind-light-cloud, type cd Desktop\ember-mind-light-cloud on Windows or cd ~/Desktop/ember-mind-light-cloud on Mac.)

Block 1 — Install the tooling and log in to Cloudflare

npm install -g wrangler
npm install
wrangler login

The third command opens a browser asking you to log in to Cloudflare. Click through. Come back to the terminal when it says you're logged in.

You should see: Successfully logged in. in the terminal.

Block 2 — Deploy the Worker

On Windows (PowerShell):

.\deploy.ps1

On macOS / Linux:

bash deploy.sh

The script will:

• Check you're logged in to Cloudflare.
• Create a D1 database named ember-light and paste its ID into wrangler.toml automatically.
• Run the database migration (creates the tables).
• Prompt you for an API key — type any long random string here (e.g., a 32-character password from a password manager). Save this — you'll need it twice more.
• Deploy the Worker.

You should see: === Deployment complete === and a Worker URL ending in .workers.dev.

Verify it worked: open your Worker URL with /health at the end (e.g., https://ember-light-cloud.your-name.workers.dev/health). You should see {"status":"ok","version":"1.0.0","tools":16,"engine":"d1-fts5"}.

Open the dashboard: visit your Worker URL with /dashboard at the end. Paste your API key. You should see an empty memory dashboard.

Block 3 — Connect your AI partner (the bridge)

This is what lets your AI partner actually USE the memory you just deployed.

Step 3a. Install the Python pieces:

pip install fastmcp httpx

Step 3b. Open bridge_template.py in any text editor (Notepad works). Find these two lines near the top:

WORKER_URL = "https://ember-light-cloud.YOUR_SUBDOMAIN.workers.dev"
API_KEY = "YOUR_API_KEY"

Replace them with your actual Worker URL (from Block 2) and the API key you set. Save the file.

Step 3c. Find your AI assistant's config file:

| App | Config file location | |---|---| | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Linux) | ~/.config/Claude/claude_desktop_config.json | | Claude Code | ~/.claude.json (Mac/Linux) or %USERPROFILE%\.claude.json (Windows) |

Tip: paste the path into File Explorer's address bar (Windows) or Finder's "Go to Folder" (Cmd+Shift+G on Mac) to jump straight there.

Step 3d. Open that config file in a text editor. Add an ember-light entry inside mcpServers. If the file doesn't have an mcpServers section yet, add the whole thing.

{
  "mcpServers": {
    "ember-light": {
      "command": "python",
      "args": ["C:\\full\\path\\to\\bridge_template.py"]
    }
  }
}

Replace the path with the full absolute path to your bridge_template.py. On Windows, use double backslashes (\\). On macOS/Linux, use forward slashes (/path/to/bridge_template.py).

Step 3e (Claude Desktop only): Open Claude Desktop's Settings → Tool access mode and select "Always available." Without this, the tools fail silently.

Step 3f. Restart your AI app fully (quit and reopen).

---

Verify everything is working

Ask your AI partner:

> "Run ember_stats and tell me what you see."

If it returns a JSON blob with totals, you're done. Welcome to persistent memory.

---

Tools (16)

| Tool | Description | |---|---| | ember_add | Add a memory, thought, or pattern | | ember_search | Full-text search with BM25 ranking | | ember_get | Retrieve a node by ID | | ember_update | Update a node's content, salience, or domains | | ember_delete | Delete a node (cascades) | | ember_link | Link two nodes together | | ember_pulse | Record an emotional pulse | | ember_pulse_update | Update a pulse's emotion fields | | ember_spark | Capture a fleeting moment | | ember_today | List active nodes | | ember_stats | System statistics | | ember_think | Record a thought (identity domain) | | ember_identity_set | Set or update an identity document | | ember_identity_get | Get an identity document | | ember_identity_list | List all identity documents | | ember_identity_delete | Delete an identity document |

Node types: memory, thought, pattern, pulse, spark Domains: today, projects, us, emotional, identity, interests, intimacy, operational, technical Salience levels: foundational, active, background, archive

---

Troubleshooting

wrangler: command not found — Block 1 didn't finish. Run npm install -g wrangler again. If that fails, reinstall Node.js and reopen your terminal.

Not authenticated — Run wrangler login again. Make sure you finished the browser flow.

pip: command not found (Windows) — Python wasn't added to PATH. Reinstall Python and check the "Add Python to PATH" box.

Dashboard loads but says "Connection failed. Check your API key." — You're entering the wrong key, OR you set the API key incorrectly during deploy. Re-set it: wrangler secret put EMBER_API_KEY and redeploy.

Your AI doesn't see Ember tools after restart — Three things to check, in order:

1. The path in your MCP config is absolute and points to a real file.
2. Claude Desktop has "Always available" turned on (Settings → Tool access mode).
3. The bridge runs without errors when you test it manually: python bridge_template.py should hang waiting for input (that's correct — Ctrl+C to exit).

Bridge errors with ModuleNotFoundError: No module named 'fastmcp' — pip install fastmcp httpx didn't run, or it ran in a different Python environment. On Windows, try py -m pip install fastmcp httpx instead.

Still stuck? Hand this README and your error message to Claude Code or Cursor and ask it to fix it. That's not a cop-out — it's the fastest path.

---

Architecture (for the curious)

• Runtime: Cloudflare Workers (single-file Hono app)
• Database: Cloudflare D1 (SQLite) with FTS5 full-text search
• Protocol: JSON-RPC + MCP (Model Context Protocol)
• Auth: Bearer token or X-API-Key header (stored as a Wrangler secret)
• Dashboard: Built-in at /dashboard, dark theme, full edit/delete on every node and identity doc

No vectors. No AI calls. No daemons. Just memory, search, and a UI to manage it.

---

Endpoints (advanced)

| Method | Path | Auth | Description | |---|---|---|---| | GET | /health | No | Health check | | POST | /rpc | Yes | JSON-RPC endpoint | | POST | /mcp | Yes | MCP protocol endpoint | | GET | /api/stats | Yes | REST stats | | GET | /api/nodes/recent | Yes | Recent nodes | | GET | /api/nodes/by-type/:type | Yes | Nodes filtered by type | | GET | /api/pulses | Yes | Pulses with emotions | | GET | /api/identity | Yes | All identity documents | | GET | /dashboard | No (UI auths via API key input) | Built-in dashboard |

JSON-RPC example

curl -X POST https://your-worker.workers.dev/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ember_add","params":{"content":"First memory","type":"memory","domains":["today"]}}'

---

Support

Ko-fi: ko-fi.com/codeandchaos

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: code-and-chaos-ai
• Source: code-and-chaos-ai/ember-mind-light-cloud
• License: MIT

Install and usage instructions live in the source repository linked above.