Content
# 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](https://cloudflare.com).
2. **Node.js 18 or newer** — download from [nodejs.org](https://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](https://www.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
```bash
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):**
```powershell
.\deploy.ps1
```
**On macOS / Linux:**
```bash
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:
```bash
pip install fastmcp httpx
```
**Step 3b.** Open `bridge_template.py` in any text editor (Notepad works). Find these two lines near the top:
```python
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.
```json
{
"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
```bash
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](https://ko-fi.com/codeandchaos)
