# ultramem-mcp

**Give any MCP client durable, cross-session memory.** An [MCP](https://modelcontextprotocol.io) server that exposes an [UltraMem](https://github.com/Akpughe/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](https://github.com/Akpughe/ultramem) — `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:

```bash
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>

```jsonc
{
  "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

```bash
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:

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

## License

[Apache-2.0](LICENSE).