keephaven-mcp
This MCP server lets an AI agent manage its own long-term memory on a self-hosted Keephaven instance.
Check identity, write permission, and quota usage with
memory_status.List memory files, optionally under a folder prefix like
peopleorprojects/keephaven.Read a memory file and get its etag for conflict-safe updates.
Create or replace UTF-8 memory files up to 10 MB, with optional etag check via
if_match.Delete memory files, except journal files; paired backup boxes keep already-received copies.
Append immutable journal entries with text up to 16,000 chars, optional tags, and structured data.
Read recent journal entries oldest first, with optional date filter and limit.
Search case-insensitively across memory files and the journal, returning matching lines with file and line number.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@keephaven-mcp remember that Alice prefers email over Slack"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, 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 |
| Save a file, like |
| Read a file back, with its etag. |
| List files, optionally under a folder. |
| Case-insensitive search across files and journal. |
| Delete a file. |
| Add an entry to an append-only journal. The agent can add to it, never edit or delete it. |
| Read recent journal entries, oldest first. |
| Name, read-only or not, quota used. |
Related MCP server: fimemory
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
On the Keephaven: Settings > Agents > Add an agent. Copy the two values it shows.
Add the server to your MCP client. For Claude Desktop, in
claude_desktop_config.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-mcpIt 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-locallyThen 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. Keephaven Home has it too from 2026.10.30, switched off — turn it on in Settings > Agent memory. 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. MIT License.
Available Tools
8 toolsjournal_appendAdd to your journalA
Append one entry to your append-only journal: what you did, decided, or learned. Nothing in the journal can be edited or deleted afterwards, so it's the record your future sessions can trust.
Inputs: text (required), data, tags.
journal_readRead your journalARead-only
Read your most recent journal entries, oldest first. Use at the start of a session to pick up where you left off.
Inputs: limit, since.
memory_deleteDelete a memory fileADestructive
Delete one file from your memory on the box. Journal files can't be deleted. A paired backup box keeps what it already received.
Inputs: path (required).
memory_listList memory filesARead-only
List the files in your memory, optionally under a folder prefix like 'people' or 'projects/keephaven'.
Inputs: prefix.
memory_readRead a memory fileARead-only
Read one file from your memory. Returns its text and an etag; pass the etag to memory_write to avoid overwriting a newer copy.
Inputs: path (required).
memory_searchSearch your memoryARead-only
Case-insensitive text search across your memory files and journal. Returns matching lines with file and line number.
Inputs: query (required), limit.
memory_statusMemory statusARead-only
Who you are on this Keephaven, whether you can write, and how much of your quota is used.
Inputs: no named parameters.
memory_writeWrite a memory fileADestructiveIdempotent
Create or replace one file in your memory (UTF-8 text, up to 10 MB). Paths are plain segments of letters, digits, _ . - separated by '/'. journal/ is not writable here: use journal_append.
Inputs: path (required), content (required), if_match.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource-action pair: memory file operations, append-only journal operations, search, and status. The boundary between memory_write and journal_append is explicitly clarified, preventing likely misselection.
All tools follow a predictable resource_action pattern: memory_* for file memory and journal_* for journal operations. The convention is consistent and easy to infer.
Eight tools are well-scoped for a memory/filesystem server with an append-only journal. Each tool has a clear role without excessive fragmentation.
The set covers memory file CRUD (read/write/list/delete), identity and quota status, search across memory and journal, and append/read journal lifecycle. The append-only journal intentionally omits edit/delete operations, so the surface is complete for the stated domain.
Maintenance
Related MCP Connectors
One memory for your AI agents: scoped, expiring, revocable per-agent tokens and an audit log.
Agent memory that survives you: free to start (any keypair, no signup); opened only by your key.
Persistent agent memory paid per call via x402 USDC. Your wallet is your private memory namespace.
Private memory, scratchpads, context export/restore and task handoff for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides non-custodial, post-quantum encrypted memory for AI agents, enabling portable memory across models with provable erasure.1Apache 2.0

fimemoryofficial
FlicenseNot gradedqualityCmaintenanceEnables AI assistants to read and write a local, encrypted-by-default memory store, so they can share persistent notes and context across sessions and models on your machine.48 npm-- AlicenseNot gradedqualityCmaintenanceEnables AI agents to store, read, extend, and share encrypted persistent memory, with pay-per-use access via x402 payments on Base.MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent memory for AI agents via MCP, enabling agents to store and access notes, files, and session context across sessions and clients while under user control.4MIT