# keephaven-mcp

Your agent's memory, on a box in your house. An MCP server that gives an AI agent a long-term memory stored on a [Keephaven](https://github.com/dafarusd/keephaven), not on a vendor's server.

Works with MCP clients that run local servers, like Claude Desktop, Claude Code and Cursor.

## What the agent gets

| Tool | What it does |
|---|---|
| `memory_write` | Save a file, like `people/dafarus.md` or `projects/keephaven.md`. Optional etag check so two sessions don't overwrite each other. |
| `memory_read` | Read a file back, with its etag. |
| `memory_list` | List files, optionally under a folder. |
| `memory_search` | Case-insensitive search across files and journal. |
| `memory_delete` | Delete a file. |
| `journal_append` | Add an entry to an append-only journal. The agent can add to it, never edit or delete it. |
| `journal_read` | Read recent journal entries, oldest first. |
| `memory_status` | Name, read-only or not, quota used. |

## What the owner keeps

- Each agent gets its own folder and can't see any other agent's.
- You add an agent in Keephaven's **Settings > Agents** and get a token, shown once. The box stores only a fingerprint of it.
- Revoke cuts the agent off at once. Its files stay until you delete them.
- Set a size limit per agent, or make one read-only.
- If your Keephaven backs up to a second box, the agent's folder is part of that backup, and the backup box refuses every delete. That part isn't tested between two real boxes yet.

## Set it up

1. On the Keephaven: **Settings > Agents > Add an agent**. Copy the two values it shows.
2. Add the server to your MCP client. For Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "keephaven": {
      "command": "npx",
      "args": ["-y", "github:dafarusd/keephaven-mcp"],
      "env": {
        "KEEPHAVEN_URL": "http://keephaven-xxxx.local:8790",
        "KEEPHAVEN_TOKEN": "khm_..."
      }
    }
  }
}
```

For Claude Code:

```
claude mcp add keephaven -e KEEPHAVEN_URL=http://keephaven-xxxx.local:8790 -e KEEPHAVEN_TOKEN=khm_... -- npx -y github:dafarusd/keephaven-mcp
```

It installs straight from GitHub, so the first start takes a minute while it builds. Needs Node 20 or newer.

The machine running the agent has to reach the box: same home network, the Keephaven's own Wi-Fi, or your Tailscale tailnet when Remote access is on.

## Try it with no box

The box runs one Python file with no dependencies. Run that same file anywhere with Python 3:

```
python3 agent-memory.py serve --data ./mem --bind 127.0.0.1 --dev-token khm_try-it-locally
```

Then point the MCP server at `http://127.0.0.1:8790` with that token. The file is `modules/agent-memory.py` in the Keephaven repo.

## Status, honestly

- The memory service is built and tested: 22 API tests, and a two-VM NixOS test where the service runs as its own locked-down user and a second machine uses it over the network.
- This MCP server has 7 end-to-end tests: the official MCP client, this server over stdio, and the real memory service.
- It ships in Keephaven Agent Memory, released 2026-10-25 for a Pi 5 and for a USB SSD on a Windows PC: https://keephaven.co/agent-memory. The Pi edition passed its release checks on one Pi 5, the SSD edition on a real drive on a Windows PC. Backup ran from a real Pi 5 (pre-release build) to a PC build in a VM over Tailscale — **not** yet between two real boxes. Home and Photos boxes don't have it.
- Tokens travel in plain HTTP on your home network, like the rest of the box's local pages. Over Tailscale they're encrypted.



## Agent skill

`skill/keephaven/` is an agent skill (a `SKILL.md` plus a read-only `check.py`): how to use a Keephaven as memory, and how to boot one in a VM and report what works. `check.py` was run against the Photos SSD image booted in QEMU: setup page, then ready, Photos up, Immich 3.0.3.

Built by [@Dafarusd](https://x.com/Dafarusd). MIT License.