# combine-memory-mcp

MCP server providing a **persistent, shared memory of CMS Combine
lessons** for the [combine-assistant](https://github.com/maxgalli/combine-assistant)
stack. It complements the other two servers:

| Piece | Repo | Role |
|---|---|---|
| Retrieval MCP | [`combine-mcp`](https://github.com/maxgalli/combine-mcp) | Search/fetch over docs, paper, code, forum. |
| Execution MCP | [`combine-run-mcp`](https://github.com/maxgalli/combine-run-mcp) | Run a Combine command in a sandbox. |
| **Memory MCP** | this repo | **Remember confirmed lessons across sessions and users.** |

An entry is a short, distilled lesson — a confirmed error → cause → fix
chain, or a non-obvious behavior verified against the docs/code/forum.
It is **not** a session log: size caps at save time and a deliberately
conservative save policy ("save less rather than too much", enforced via
the server instructions) keep the store small and useful.

## Tools

- `save_memory(title, lesson, namespace?, combine_version?, refs?, author?)`
  — persist one lesson. Validation (size caps, namespace rules) happens
  server-side; rejected entries return `{"error": ...}`.
- `search_memory(query, namespace?, limit?)` — BM25-ranked hits
  (`id`, `title`, `score`, `snippet`, …). Same ranking approach as
  combine-mcp, so scores read consistently across the stack.
- `fetch_memory(entry_id)` — the full lesson for one hit.

Namespaces: `shared` (default — lessons useful to everyone) and
`user:<name>` (personal context). **Note:** there is no authentication;
namespaces are organizational, not access control. Nothing in this
store is private — the server instructions forbid saving user analysis
specifics.

## Storage

SQLite (WAL mode), one table. The path comes from, in order: the
`--db` flag, the `COMBINE_MEMORY_DB` env var, `./memory.db`. The BM25
index is in-memory and rebuilds lazily whenever the store changes, so
searches see saves immediately.

## Running

```bash
pip install .

# local (stdio), DB in the current directory:
combine-memory-mcp serve

# remote (HTTP):
combine-memory-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000 \
    --db /data/memory.db
```

## Container / CERN PaaS

The `Dockerfile` builds a plain `python:3.11-slim` image (no Combine
inside) that serves streamable-HTTP on port 8000 and expects the store
at `/data/memory.db`. Deployment notes:

- **Attach a persistent volume (PVC) at `/data`** — the pod filesystem
  is ephemeral; without the PVC the memory is wiped on every redeploy.
- **Run a single replica** — SQLite has one writer; two pods sharing
  the file would corrupt it.
- The image handles OpenShift's arbitrary-UID model (`chgrp 0` /
  `chmod g=u`).

## Tests

```bash
pip install -e ".[dev]" && pytest    # or: uv run pytest
```

## License

[MIT](LICENSE)