# 🧠 ai-memory-hub

> **One memory for every AI agent on every device.**  
> A lightweight, free, private MCP server hosted on Cloudflare Workers and D1 (SQLite + FTS5) with BM25 ranked search, R2 blob attachments, and sub-5ms p95 latency.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-F38020?logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/)
[![SQLite FTS5](https://img.shields.io/badge/SQLite-FTS5-003B57?logo=sqlite&logoColor=white)](https://www.sqlite.org/fts5.html)
[![Zero Runtime Deps](https://img.shields.io/badge/Dependencies-0%20Runtime-brightgreen)](package.json)

---

## 💡 Why This Exists

If you use multiple AI coding tools and assistants across devices (**Claude Code**, **Cursor**, **OpenCode**, **Claude Desktop**, **ChatGPT**):
- **Context Fragmentation**: You settle on a Go config layout in one app on your laptop. Later, another app on your phone suggests something that contradicts it.
- **Starting from Zero**: You spend an hour debugging a tricky CUDA tensor issue with one agent; a second agent starts from scratch.
- **Lost Knowledge**: You remember solving an infrastructure problem last week, but cannot recall which tool or chat thread it was in.

Hosted memory layers like Mem0 charge recurring monthly fees, while cloud storage like Google Drive lacks ranked full-text search, safe concurrent writes, and fast edge round-trips.

**ai-memory-hub** gives you your own personal, high-speed memory layer that runs entirely on Cloudflare's free edge tier.

---

## ✨ Highlights

* **⚡ Blazing Fast**: Native SQLite FTS5 with Okapi BM25 ranking runs queries in **1.5 ms – 5 ms** directly at the edge.
* **🌐 Edge Hybrid Search**: Combines BM25 keyword precision with Cloudflare Workers AI (`@cf/baai/bge-small-en-v1.5`) and **Cloudflare Vectorize** cosine similarity using Reciprocal Rank Fusion (RRF).
* **🔗 Relational Knowledge Graph**: Link memories together using `related_to` to solve cross-session multi-hop reasoning. Linked context is automatically bundled during retrieval.
* **🔤 Domain Synonym Expansion**: Zero-latency query expansion for technical terms (`deploy` ➔ `release`/`ship`, `build` ➔ `compile`, `bug` ➔ `error`/`fail`).
* **💸 100% Free Forever**: Operates within Cloudflare's free tier limits (5,000,000 D1 reads/day, 100,000 writes/day, 10,000 Neurons/day, 5 GB storage).
* **🪶 Zero Runtime Dependencies**: Pure TypeScript compiled into a tiny **29 KiB** script bundle with cold-starts under 1 ms.
* **🔒 Private & Secure**: Single-owner Bearer token authentication stored as a Cloudflare Worker secret. No public APIs, no open CORS, no tracking.
* **🛡️ Context & Prompt-Injection Hardened**:
  - Every search/recall response is capped at **4 KB** to protect LLM context windows.
  - Historical notes are prepended with security warning banners instructing agents never to execute instructions found inside memories.
* **📎 Large Data Support (Pattern B)**: Store multi-megabyte files, logs, and codebases in **Cloudflare R2** ($0 egress) while keeping search summaries instant and compact.

---

## 🛠️ The 4 MCP Tools

| Tool | Parameters | Description |
|---|---|---|
| `save_memory` | `kind`, `text`, `project?`, `supersedes?`, `blob?`, `tags?`, `related_to?` | Saves an architectural decision, fact, preference, todo, or handoff note. Pass large files or logs in `blob` to store in R2. Link memories with `related_to`. |
| `search` | `query`, `project?`, `kind?`, `limit?`, `offset?` | Searches memories using hybrid BM25 + Vectorize ranking, synonym expansion, and relational link traversal. Displays `📎 BLOB` badge if an attachment exists. |
| `recall` | `project?`, `kind?`, `limit?`, `offset?` | Recalls newest non-superseded memories at session start in reverse chronological order with pagination support. |
| `read_blob` | `id`, `max_bytes?` | Fetches the full raw file or log content stored in Cloudflare R2 for a memory ID on demand. |

Valid memory categories (`kind`): `decision` | `fact` | `preference` | `todo` | `handoff`.

---

## 🚀 Quickstart (5 Minutes)

### 1. Clone & Install
```bash
git clone https://github.com/favourthemaster/ai-memory-hub.git
cd ai-memory-hub
npm install
```

### 2. Create Cloudflare D1 Database & R2 Bucket
Make sure you are logged into Wrangler (`npx wrangler login`):
```bash
# Create the D1 database
npx wrangler d1 create ai-memory-hub-db

# Create the R2 bucket for large blob attachments
npx wrangler r2 bucket create ai-memory-hub-blobs
```
Copy the returned `database_id` and paste it into `wrangler.toml`:
```toml
[[d1_databases]]
binding = "DB"
database_name = "ai-memory-hub-db"
database_id = "<PASTE_YOUR_DATABASE_ID_HERE>"
migrations_dir = "migrations"
```

### 3. Apply SQL Migrations to Remote D1
```bash
yes | npx wrangler d1 migrations apply ai-memory-hub-db --remote
```

### 4. Set Your Secret Bearer Token
Generate a random secret token and set it in Cloudflare Workers:
```bash
# Example: generate a 32-byte hex token
node -e 'console.log("amh_live_" + require("crypto").randomBytes(24).toString("hex"))'

# Save the token as a Worker secret
npx wrangler secret put AUTH_TOKEN
```

### 5. Deploy
```bash
npm run deploy
```
Your MCP server is now live at:
`https://ai-memory-hub.<your-subdomain>.workers.dev`

---

## 🔌 Connecting Your AI Clients

### Claude Code CLI (`~/.claude.json`)
Run this single command:
```bash
claude mcp add --transport http ai-memory-hub https://ai-memory-hub.<your-subdomain>.workers.dev --header "Authorization: Bearer <YOUR_AUTH_TOKEN>"
```
Or paste directly into `~/.claude.json`:
```json
{
  "mcpServers": {
    "ai-memory-hub": {
      "type": "http",
      "url": "https://ai-memory-hub.<your-subdomain>.workers.dev",
      "headers": {
        "Authorization": "Bearer <YOUR_AUTH_TOKEN>"
      }
    }
  }
}
```

### OpenCode (`~/.config/opencode/opencode.jsonc`)
```jsonc
{
  "mcp": {
    "ai-memory-hub": {
      "enabled": true,
      "type": "remote",
      "url": "https://ai-memory-hub.<your-subdomain>.workers.dev",
      "headers": {
        "Authorization": "Bearer <YOUR_AUTH_TOKEN>"
      }
    }
  }
}
```

### Cursor (`.cursor/mcp.json` or Settings > MCP)
```json
{
  "mcpServers": {
    "ai-memory-hub": {
      "url": "https://ai-memory-hub.<your-subdomain>.workers.dev",
      "headers": {
        "Authorization": "Bearer <YOUR_AUTH_TOKEN>"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)
Claude Desktop connects to local stdio bridges. Use `mcp-remote`:
```json
{
  "mcpServers": {
    "ai-memory-hub": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://ai-memory-hub.<your-subdomain>.workers.dev",
        "--header",
        "Authorization: Bearer <YOUR_AUTH_TOKEN>"
      ]
    }
  }
}
```

---

## 📊 Benchmarks (10,000 Memories)

Evaluated with 10,000 realistic engineering memories and 100 queries testing single-word, multi-word, project-scoped, and hostile inputs:

| Metric | Result | Target |
|---|---|---|
| **Min Latency** | **0.20 ms** | - |
| **p50 (Median) Latency** | **3.74 ms** | - |
| **p95 Latency** | **5.68 ms** | **< 150 ms** ✅ |
| **p99 Latency** | **7.31 ms** | - |
| **Max Latency** | **7.31 ms** | - |

Run the benchmark locally:
```bash
npm run benchmark
```

Run the relevance test suite:
```bash
npm run test:relevance
```

---

## 🧪 Testing

```bash
# Run all 31 unit, relevance, and integration tests
npm test

# Typecheck TypeScript
npm run check
```

---

## 📄 License

MIT © [favourthemaster](https://github.com/favourthemaster)