ultramem-mcp

Give any MCP client durable, cross-session memory. An MCP server that exposes an UltraMem deployment's memory layer to Claude Desktop/Code, Cursor, and any other MCP client — so your agent remembers across sessions.

It's a thin client of the UltraMem HTTP API: every tool is a call to your running ultramem-server, so there's one source of truth and nothing to keep in sync.

Tools

Tool	What it does	API
recall_search	Semantic search → relevant documents + distilled facts	POST /v1/search
recall_timeline	Newest-first enumeration over a recent window (optionally by source)	GET /v1/timeline
add_memory	Write a memory back (task outcomes, user statements)	POST /v1/memories
get_profile	The standing static + dynamic profile to inject as context	GET /v1/profile

Prerequisites

A running UltraMem server (see the UltraMem repo — cargo run -p ultramem-server or docker compose up). You need its URL and API key.

Install (one line)

No clone, no build — npx runs it straight from GitHub:

claude mcp add ultramem \
  -e ULTRAMEM_API_URL=http://localhost:8080 \
  -e ULTRAMEM_API_KEY=your-key \
  -e ULTRAMEM_CONTAINER_TAG=user_123 \
  -- npx -y github:Akpughe/ultramem-mcp

<details> <summary>Cursor / other MCP clients (raw config)</summary>

{
  "mcpServers": {
    "ultramem": {
      "command": "npx",
      "args": ["-y", "github:Akpughe/ultramem-mcp"],
      "env": {
        "ULTRAMEM_API_URL": "http://localhost:8080",
        "ULTRAMEM_API_KEY": "your-key",
        "ULTRAMEM_CONTAINER_TAG": "user_123"
      }
    }
  }
}

</details>

Configuration

Env var	Required	Default	Purpose
ULTRAMEM_API_URL	no	http://localhost:8080	Base URL of your ultramem-server.
ULTRAMEM_API_KEY	yes (if the server enforces auth)	—	Sent as Authorization: Bearer <key>.
ULTRAMEM_CONTAINER_TAG	no	server default	Namespace (one per user/agent). A tool's container_tag argument overrides it.

Security: the API key scopes a namespace — treat it like a password and never commit it.

The agent pattern

On session start, call get_profile and prepend it to the system prompt ("what you always know about the user"). During the task, recall_search for specifics and add_memory to persist outcomes. That's the "always-known context" trick, self-hosted.

Develop locally

git clone https://github.com/Akpughe/ultramem-mcp && cd ultramem-mcp
npm install          # also builds via the prepare script
node dist/index.js   # speaks JSON-RPC over stdio

Smoke-test by hand:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | ULTRAMEM_API_URL=http://localhost:8080 node dist/index.js

License

Apache-2.0.