Skip to main content
Glama

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

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.

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

  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:

{
  "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.

Available Tools

8 tools
journal_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 journalA
Read-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 fileA
Destructive

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 filesA
Read-only

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

Inputs: prefix.

memory_readRead a memory fileA
Read-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_statusMemory statusA
Read-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 fileA
DestructiveIdempotent

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

    A4.1/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    Eight tools are well-scoped for a memory/filesystem server with an append-only journal. Each tool has a clear role without excessive fragmentation.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides 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.
      4
      MIT