Keephaven Mcp

io.github.dafarusdPublished by GitHub account dafarusdv0.1.0Updated Oct 29, 2026

Agent memory on your own Keephaven home server: files, append-only journal, search.

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & Memory

Overview

AI-generated overview

Gives an AI assistant a persistent file-and-journal memory stored on the user's own Keephaven home server, with search, read, write and delete tools.

What you can do
  • Check identity, write permission and quota usage for the agent's memory space
  • List, read, create, replace and delete memory files, with etag checks to avoid overwriting newer copies
  • Append entries to an append-only journal and read recent entries back, oldest first
  • Search memory files and the journal case-insensitively, returning matching lines with file and line numbers
When to use it
Useful when you want an assistant to carry durable facts, preferences and project notes across sessions and context windows, while keeping that data on a box in your own home rather than a vendor's server. Suited to local MCP clients such as Claude Desktop, Claude Code or Cursor.
Requirements
Runs as a local stdio process via npx, installing from GitHub, so the first start builds and needs Node 20 or newer. Requires KEEPHAVEN_URL pointing at the box's memory API and KEEPHAVEN_TOKEN, an agent token created in Settings > Agents. The machine running the agent must reach the box over the home network, its Wi-Fi, or a Tailscale tailnet.
Before you install
The token is sent over plain HTTP on the home network, so it is only encrypted over Tailscale. The assistant can create, overwrite and delete files in its folder, and journal entries can never be edited or removed. The owner can see stored content, revoke access or delete the folder, and the instructions say not to store passwords or keys there. Backup behaviour between two real boxes is untested.

Installation

In SourceWeft

  1. Open Keephaven Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

ToolWhat it does
memory_writeSave a file, like people/dafarus.md or projects/keephaven.md. Optional etag check so two sessions don't overwrite each other.
memory_readRead a file back, with its etag.
memory_listList files, optionally under a folder.
memory_searchCase-insensitive search across files and journal.
memory_deleteDelete a file.
journal_appendAdd an entry to an append-only journal. The agent can add to it, never edit or delete it.
journal_readRead recent journal entries, oldest first.
memory_statusName, 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. 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.

Source: README.md at commit 8d6f316

Tools

8

memory_status

Memory status

Who you are on this Keephaven, whether you can write, and how much of your quota is used.

Takes no parameters.

memory_list

List memory files

List the files in your memory, optionally under a folder prefix like 'people' or 'projects/keephaven'.

Parametersprefix

memory_read

Read a memory file

Read one file from your memory. Returns its text and an etag; pass the etag to memory_write to avoid overwriting a newer copy.

Parameterspathrequired

memory_write

Write a memory file

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.

Parameterspathrequiredcontentrequiredif_match

memory_delete

Delete a memory file

Delete one file from your memory on the box. Journal files can't be deleted. A paired backup box keeps what it already received.

Parameterspathrequired

journal_append

Add to your journal

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.

Parametersdatatagstextrequired

journal_read

Read your journal

Read your most recent journal entries, oldest first. Use at the start of a session to pick up where you left off.

Parameterslimitsince

Version history

1
  1. v0.1.0LatestOct 26, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts