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