# Personal Memory MCP Server

A small, self-hosted server that gives any MCP-compatible AI tool (Claude
Desktop, Claude Code, and others that support MCP) a shared, persistent
memory it can read and write — independent of any single app or project.

Storage is SQLite (one file, `memory.db`). Tools exposed: `remember`,
`recall`, `list_recent`, `forget`, `list_tags`.

---

## 1. Run it locally first (sanity check)

```bash
pip install -r requirements.txt
export MEMORY_SERVER_TOKEN="pick-a-long-random-string-here"
python server.py
```

It starts on `http://localhost:8000`. Leave it running.

---

## 2. Deploy it somewhere reachable from all your devices

Pick one — all are low/no cost for personal use:

### Option A: Railway (easiest)
1. This repo is already on GitHub — good to go.
2. Go to railway.app → New Project → Deploy from GitHub repo.
3. In the service's **Variables** tab, add `MEMORY_SERVER_TOKEN` = your secret string.
4. Railway auto-detects the `Procfile` and deploys. Add a **Volume** mounted at
   `/data` and set `MEMORY_DB_PATH=/data/memory.db` so your memories survive
   redeploys.
5. Copy the generated public URL (e.g. `https://your-app.up.railway.app`).

### Option B: Render
1. New → Web Service → connect this repo.
2. Build command: `pip install -r requirements.txt`. Start command: `python server.py`.
3. Add env var `MEMORY_SERVER_TOKEN`. Attach a persistent disk at `/data`,
   set `MEMORY_DB_PATH=/data/memory.db`.

### Option C: Any VPS (DigitalOcean, Hetzner, etc.) with Docker
```bash
docker build -t memory-server .
docker run -d -p 8000:8000 \
  -e MEMORY_SERVER_TOKEN="your-secret" \
  -v ~/memory-data:/data \
  memory-server
```
Put it behind a domain + HTTPS (e.g. Caddy or nginx + Let's Encrypt) so the
token isn't sent over plain HTTP.

---

## 3. Connect Claude Desktop / Claude Code to it

Add a **remote MCP server** in Claude Desktop: Settings → Connectors → Add
custom connector, with:

- **URL**: `https://your-deployed-url/mcp`
- **Header**: `Authorization: Bearer your-secret-token`

(Exact UI wording may vary by version — search Claude's docs for "custom
connector" if the menu looks different.)

For Claude Code, add to your MCP config (e.g. `.mcp.json` or via `claude mcp add`):

```json
{
  "mcpServers": {
    "personal-memory": {
      "url": "https://your-deployed-url/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}
```

Any other MCP-compatible client (some third-party tools support MCP
connectors too) can point at the same URL + token to share the exact same
memory store.

---

## 4. Using it

Once connected, just talk naturally:
- "Remember that my Mayo outreach uses 'research fellow' not 'postdoc'."
- "What have I saved about the heme-onc template?"
- "Forget memory #7."

The AI tool decides when to call these tools based on your conversation —
you don't need to invoke them manually.

---

## Notes / limitations

- **Security**: the bearer token is the only protection. Keep it secret,
  use HTTPS in production, and don't commit `.env` or `memory.db` to git
  (already in `.gitignore`).
- **Search is basic**: `recall` does a plain SQL `LIKE` match, not semantic
  search. Fine for a personal memory store with dozens–hundreds of entries;
  if it grows large and keyword search stops finding things, this is the
  first place to upgrade (e.g. add embeddings + a vector column).
- **Backups**: it's one SQLite file — back it up periodically (e.g. a cron
  job copying `/data/memory.db` somewhere safe) since most free hosting
  tiers don't guarantee volume durability.
- **This is separate from Claude's built-in memory** — that still exists
  and works automatically within Claude. This server is for context you
  want to persist and be readable across *different* tools, not just Claude.