# 🧠 NFTS Memory MCP

One shared memory for **claude.ai**, **Claude Desktop**, and **Claude Code** — on any computer. Save something in one, it's there in all of them.

Self-hosted, SQLite-backed, zero recurring cost. Runs as one systemd service on your MCP Hub, same pattern as your other custom MCP servers.

---

## How it works

```
                        ┌─────────────────────────┐
  claude.ai ───────────▶│                          │
  (connector, OAuth)    │   nfts-memory-mcp        │
                        │   ─────────────────      │
  Claude Desktop ───────▶│   Express + MCP SDK      │
  (MCP config, OAuth)    │   SQLite + FTS5 search   │──▶ data/memory.db
                        │   Built-in OAuth server   │
  Claude Code ──────────▶│   Web dashboard          │
  (MCP config, OAuth)    │                          │
                        └─────────────────────────┘
```

- **One process, one database.** Every client talks to the same SQLite file over HTTP — there's nothing to sync, because there's only ever one copy.
- **9 MCP tools** let Claude save, search, update, and organize memories: `memory_save`, `memory_search`, `memory_recent`, `memory_context`, `memory_update`, `memory_archive`, `memory_delete`, `memory_list_projects`, `memory_stats`.
- **Full-text search** via SQLite FTS5 (porter stemming, ranked results, snippet highlighting) — fast even at tens of thousands of memories.
- **Built-in OAuth 2.0 server** (with PKCE + dynamic client registration) so claude.ai, Desktop and Code can each connect as their own authorized client — this is what makes it usable as a claude.ai connector, not just a local tool.
- **Web dashboard** at your domain root — browse, search, manually add/edit/archive memories, see stats, and manage which apps are connected.
- **Projects & categories.** Every memory is tagged with a project (`nfts`, `aural`, `dantectl`, `general`, ...) and a category (`fact`, `decision`, `preference`, `todo`, `config`, `contact`, `idea`), so Claude can filter context to what's relevant.

---

## Deploy

On your MCP Hub (or any box with Node 18+):

```bash
# 1. Copy this whole folder to the server, then:
cd nfts-memory-mcp
sudo bash deploy/deploy.sh
```

The script installs a `nftsmemory` system user, copies files to `/opt/nfts-memory-mcp`, installs dependencies, and sets up the systemd service. It prints the remaining manual steps (edit `.env`, nginx + certbot, start the service) — takes about 5 minutes.

**Suggested subdomain:** `memory.nftech-apps.net`, following your existing `mqtt.` / `mcp.` pattern.

Once it's running:

```bash
curl https://memory.nftech-apps.net/healthz
# {"ok":true,"service":"nfts-memory-mcp"}
```

### Verifying the full flow

`scripts/verify.sh` runs an end-to-end test against a running server (client registration → OAuth login → token → save/search a memory). Point it at your server with `BASE_URL` if testing remotely, otherwise it defaults to localhost.

---

## Connect each client

All three go through the same OAuth flow — sign in with the `ADMIN_USER` / `ADMIN_PASSWORD` you set in `.env`.

### claude.ai (web / mobile)
Settings → Connectors → Add connector → paste `https://memory.nftech-apps.net/mcp` → Connect → sign in. Done — every conversation on any device now has access.

### Claude Desktop
Settings → Connectors → Add custom connector → same URL, same login. (Desktop already shares claude.ai's account memory — this adds Code-style tool access on top, so Desktop can *search and save* memories explicitly, not just passively recall.)

### Claude Code (CLI)
```bash
claude mcp add --transport http nfts-memory https://memory.nftech-apps.net/mcp
```
It'll open a browser for the same OAuth login. After that, every `claude` session on every machine you run this on shares the same memory.

Check **Connections** in the web dashboard afterwards — you'll see all three listed with their own token, so you can revoke any one independently (e.g. if you get a new laptop and want to kill the old token).

---

## Using it day to day

You don't need to do anything special — just talk normally:

- *"Remember that the Xero email endpoint is POST /Invoices/{id}/Email"* → Claude calls `memory_save`
- *"What did we decide about the WiFi upgrade proposal pricing?"* → Claude calls `memory_search`
- *"Catch me up on dantectl"* → Claude calls `memory_context` with `project="dantectl"`

Claude decides when to save/search based on the conversation — you can also be explicit ("save this to memory", "search memory for...") if you want to force it.

The **dashboard** (`https://memory.nftech-apps.net/`) is for you: browsing everything, manually adding a memory, archiving stale ones, and seeing which apps are connected.

---

## Maintenance

**Backups** — it's one SQLite file. Add to your existing weekly Vultr snapshot routine, or simply:
```bash
sqlite3 /opt/nfts-memory-mcp/data/memory.db ".backup /path/to/backup-$(date +%F).db"
```

**Logs:**
```bash
journalctl -u nfts-memory-mcp -f
```

**Updating code:** re-run `deploy/deploy.sh` (it won't touch your `.env` or `data/`), then `systemctl restart nfts-memory-mcp`.

**Revoking a lost/compromised device:** dashboard → Connections → Revoke next to that client's token.

---

## Why this instead of claude-mem

[claude-mem](https://github.com/thedotmack/claude-mem) only hooks into Claude Code's session lifecycle — it can't reach claude.ai or Desktop, and it doesn't sync across machines on its own. This is a plain MCP server, so it works identically everywhere Claude can connect to an MCP server, self-hosted on infrastructure you already run, with no per-seat or per-token SaaS cost.

---

## Tech stack

Node.js, Express, `@modelcontextprotocol/sdk` (Streamable HTTP transport), `better-sqlite3` (WAL mode + FTS5), zero build step — it's plain JS, matching the rest of your MCP Hub services.