memocat-mcp

# MemoCat MCP Server — Self-Hosted AI Agent Memory and Vector RAG

<!-- mcp-name: io.github.MontyGovernance/memocat-mcp -->

[![PyPI](https://img.shields.io/pypi/v/memocat-mcp.svg)](https://pypi.org/project/memocat-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/memocat-mcp.svg)](https://pypi.org/project/memocat-mcp/)
[![License](https://img.shields.io/github/license/MontyGovernance/memocat-mcp.svg)](https://github.com/MontyGovernance/memocat-mcp/blob/master/LICENSE)

**MemoCat is a self-hosted MCP memory server for Claude Desktop, Cursor,
ChatGPT integrations, and autonomous AI agents.** It gives MCP clients private,
persistent, semantically searchable long-term memory. `memocat-mcp` is a
[Model Context Protocol](https://modelcontextprotocol.io) server for
[Montycat](https://montygovernance.com), an **all-in-one, self-hosted data and
memory engine for AI agents**.

Montycat combines the database, vector search, on-device embeddings, persistent
and in-memory storage, real-time subscriptions, and data governance in one
engine. MemoCat exposes those capabilities through MCP, so an agent does not
need a separate vector database, embedding API, event broker, or governance
service to build persistent memory and retrieval-augmented generation (RAG).

Memories are embedded on-device and recalled by meaning, metadata, timestamp,
or exact key. No cloud vector database, external embedding API, or per-query
bill.

## Features

- Self-hosted long-term memory for MCP-compatible AI agents.
- Semantic vector search with metadata and time-range filtering for RAG.
- Persistent memory, in-memory working spaces, bulk writes, updates, and deletion.
- Real-time memory-change subscriptions without database polling.
- Multi-agent scopes, shared memory, delegated-owner governance, and policy explanations.
- Keyspace lifecycle, semantic-model controls, snapshots, and revocation-safe watch buffers.
- One-command `uvx memocat-mcp` entry point with native/Docker engine bootstrap.

## Why

LLM agents forget context between runs. MemoCat stores each fact in Montycat,
embeds and indexes it automatically, and retrieves relevant memories through 22
agent-readable MCP tools. It is both a retrieval layer for RAG and a durable
memory layer for autonomous agents. Unlike a collection of separate database,
vector, embedding, messaging, and policy services, Montycat provides the full
memory stack as one all-in-one engine that can run under your control.

## Install MemoCat MCP

The fastest option is [`uvx`](https://docs.astral.sh/uv/guides/tools/), which
runs the latest published package in an isolated environment:

```bash
uvx memocat-mcp
```

If `uvx` is not installed yet:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx memocat-mcp
```

For a persistent command-line installation, use `pipx`:

```bash
pipx install memocat-mcp
memocat-mcp
```

You can also install it into an existing Python environment:

```bash
python -m pip install memocat-mcp
memocat-mcp
```

MemoCat requires Python 3.10 or newer. The package is published as
[`memocat-mcp` on PyPI](https://pypi.org/project/memocat-mcp/).

## Quick start with a Montycat engine

MemoCat reuses a configured Montycat Semantic engine or attempts the supported
native/Docker bootstrap path. For an existing engine:

```bash
export MONTYCAT_URI="montycat://memory-agent:password@localhost:21210/memories"
uvx memocat-mcp
```

## Tools

| Tool | What it does |
|------|--------------|
| `memocat_semantic_search` | Recall by **meaning** (vector kNN), with text or a supplied query vector. |
| `memocat_remember` | Store a fact/record; embedded automatically or indexed with a supplied vector. |
| `memocat_remember_bulk` | Store many memories at once. |
| `memocat_recall` | Fetch by exact key or by field filter. |
| `memocat_list_memories` | Browse / list stored memories (optionally most-recent first). |
| `memocat_update` | Revise a memory in place — memory is mutable. |
| `memocat_forget` | Delete a stored record. |
| `memocat_list_keyspaces` | Discover available memory namespaces. |
| `memocat_create_keyspace` | Provision a namespace; superowners also create a missing configured store in the same engine request. |
| `memocat_remove_keyspace` | Permanently remove an authorized memory namespace with safe watch cleanup. |
| `memocat_enable_semantic` | Enable semantic search and backfill one authorized keyspace. |
| `memocat_enable_external_vectors` | Enroll one keyspace for caller-supplied vectors and a named embedding space. |
| `memocat_semantic_status` | Inspect semantic configuration and backfill state. |
| `memocat_reembed_semantic` | Replace an enrolled text embedding model and backfill the keyspace. |
| `memocat_disable_semantic` | Disable semantic search for one authorized keyspace. |
| `memocat_start_snapshots` | Start scheduled snapshots for one authorized in-memory keyspace. |
| `memocat_stop_snapshots` | Stop scheduled snapshots for one authorized in-memory keyspace. |
| `memocat_clean_snapshots` | Delete snapshot files for one authorized in-memory keyspace. |
| `memocat_policy_view` | View the configured owner's effective governance policy and constraints. |
| `memocat_policy_explain` | Explain whether a proposed governed action is allowed and why. |
| `memocat_policy_history` | View governance history visible to the configured owner. |
| `memocat_await_memory_change` | **Wait for memory to change** — returns the moment another agent or session writes. Live subscription, not polling. |

## Real-time memory watch

Other memory servers can only be polled: ask again, and again, in case something
changed. Montycat has **native live subscriptions**, so this one pushes.

```
agent B: memocat_await_memory_change(scope="shared", timeout_sec=60)
                    ⏳ sleeps — no polling, no wasted tokens
agent A: memocat_remember({"text": "the deploy key rotated"}, scope="shared")
agent B: ← returns in milliseconds with the key, the value, and the event
```

Two agents, one shared scope, one notices what the other just learned. Pass the
returned `next_seq` back as `since_seq` to resume exactly where you left off —
changes that happen between calls are buffered, not lost.

Memory namespaces are also exposed as MCP **resources**
(`memocat://memory/<keyspace>`) with `resources.subscribe` support, so clients
that implement resource subscriptions get `notifications/resources/updated`
pushed to them as well. Both surfaces share one engine subscription.

Subscriptions open on demand and close when idle
(`MONTYCAT_WATCH_IDLE_TIMEOUT`), so users who never watch pay nothing.

## Montycat Semantic engine requirements

- Python 3.10+ when installing MemoCat through `uv`, `pipx`, or `pip`.
- Access to a **Montycat Semantic** engine. `uvx memocat-mcp` first reuses an
  existing engine, then attempts the supported native/platform installation
  path, and finally falls back to Docker. Semantic search is enabled by default
  in the Semantic edition.

  To start the engine manually with Docker, pick the tag for your CPU—the tag
  carries the architecture:

  **Apple Silicon (M1/M2/M3/M4) — use `arm64-semantic`:**
  ```bash
  docker run -d --name montycat -p 21210:21210 -p 21211:21211 \
    -e MONTYCAT_SUPEROWNER="admin" -e MONTYCAT_PASSWORD="change-me" \
    -v montycat_data:/var/lib/.montycat \
    montygovernance/montycat:arm64-semantic
  ```

  **Intel / AMD (x86_64) — use `semantic`:**
  ```bash
  docker run -d --name montycat -p 21210:21210 -p 21211:21211 \
    -e MONTYCAT_SUPEROWNER="admin" -e MONTYCAT_PASSWORD="change-me" \
    -v montycat_data:/var/lib/.montycat \
    montygovernance/montycat:semantic
  ```

  > On Apple Silicon the plain `semantic` tag is the amd64 image and runs under
  > emulation, where the embedding runtime's warm-up crashes. Use
  > `arm64-semantic` — a native build, not a workaround. Unsure which you have?
  > `uname -m` prints `arm64` on Apple Silicon and `x86_64` on Intel.

  Port `21211` is the subscription server and is required for
  `memocat_await_memory_change` (real-time watch); without it the other tools
  still work.

## Docker Compose deployment

Use Compose when you want a reproducible local deployment with a persistent
Semantic engine and an MCP container on the same private Docker network. Docker
is optional when you already manage a reachable Montycat server.

Create a `.env` file beside `compose.yaml`:

```dotenv
MONTYCAT_USERNAME=admin
MONTYCAT_PASSWORD=replace-with-a-strong-password
MONTYCAT_STORE=memories
MEMOCAT_VERSION=0.4.2
# Apple Silicon: arm64-semantic. Intel/AMD64: semantic.
MONTYCAT_IMAGE_TAG=semantic
```

Start the engine and build the MCP image:

```bash
docker compose up -d montycat
docker compose build mcp
```

After the public Docker image is released, use it instead of building from
source:

```bash
docker pull montygovernance/memocat-mcp:0.4.2
```

The Compose service uses `montygovernance/memocat-mcp:${MEMOCAT_VERSION}` and
waits for the Semantic engine health check before launching MCP. The image runs
as an unprivileged `memocat` user and supports both AMD64 and ARM64.

The image installs the released `montycat>=1.2.2,<2` Python client declared in
the package metadata.

The engine data is stored in the named `montycat_data` volume. Ports `21210`
and `21211` are published for debugging and external clients; the MCP container
uses the private `montycat:21210` network address. Credentials are passed as
separate environment variables, so passwords with URL-special characters need
no URL encoding. Port `21211` carries live subscription traffic for
`memocat_await_memory_change`.

MCP uses stdio, so do **not** run it as a web service. Configure a desktop MCP
client to invoke the Compose service on demand:

```json
{
  "mcpServers": {
    "memocat": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/memocat-mcp/compose.yaml",
        "run", "--rm", "-T", "mcp"
      ]
    }
  }
}
```

For Apple Silicon