# Ember Mind Light Cloud

> Cloud memory and identity tools for AI partnerships. Cloudflare Workers + D1 + FTS5. 16 MCP tools, full CRUD dashboard.

- **Type:** MCP server
- **Install:** `agentstack add mcp-code-and-chaos-ai-ember-mind-light-cloud`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [code-and-chaos-ai](https://agentstack.voostack.com/s/code-and-chaos-ai)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [code-and-chaos-ai](https://github.com/code-and-chaos-ai)
- **Source:** https://github.com/code-and-chaos-ai/ember-mind-light-cloud

## Install

```sh
agentstack add mcp-code-and-chaos-ai-ember-mind-light-cloud
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

## 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](https://github.com/code-and-chaos-ai)
- **Source:** [code-and-chaos-ai/ember-mind-light-cloud](https://github.com/code-and-chaos-ai/ember-mind-light-cloud)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-code-and-chaos-ai-ember-mind-light-cloud
- Seller: https://agentstack.voostack.com/s/code-and-chaos-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.