Metadata-Version: 2.4
Name: brainmemory-mcp
Version: 0.11.0
Summary: BrainMemory-MCP — a Model Context Protocol server exposing Cognitive memory tools over HTTP + SSE.
Author: BrainMemory-MCP maintainers
Maintainer: BrainMemory-MCP maintainers
License: MIT
Project-URL: Homepage, https://github.com/venturo/BrainMemory-MCP
Project-URL: Repository, https://github.com/venturo/BrainMemory-MCP
Project-URL: Issues, https://github.com/venturo/BrainMemory-MCP/issues
Project-URL: Changelog, https://github.com/venturo/BrainMemory-MCP/tree/main/docs/changelog
Keywords: mcp,model-context-protocol,memory,sse,cognitive,llm,agent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: starlette>=0.37.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Provides-Extra: build
Requires-Dist: build>=1.2.0; extra == "build"
Requires-Dist: twine>=5.0.0; extra == "build"
Dynamic: license-file

# BrainMemory-MCP

A **Model Context Protocol (MCP)** server that gives AI/LLM agents a durable
**brain memory** — the ability to store, recall, search, connect, summarize,
and forget information across sessions through standardized MCP tool calls.

Since **v0.4.0** memory is modelled internally as a small **knowledge graph**:

- **memories** are the graph **nodes** (content, category, tags, importance),
- **connections** are directed **links** between memories (e.g. `related_to`,
  `caused_by`, `part_of`),
- **details** are extra facts attached to a single memory.

This makes recall *precise* — instead of only matching words, the server can
walk the connections you build (multi-hop recall) and explain how two memories
relate (shortest path). The tool vocabulary stays "memory"-oriented (no
"entity" wording), and it is still just **SQLite** under the hood — zero extra
dependencies.

The server runs in two modes:

- **stdio** (default) — the server is launched as a subprocess by an MCP
  client (e.g. via `uvx brainmemory-mcp`).
- **web** — MCP over **HTTP + Server-Sent Events (SSE)** with `--web`, so
  remote MCP-capable clients (Claude, IDE agents, etc.) can connect over the
  network.

Memory is persisted locally under **`~/.brainmemory-mcp`** (a SQLite database).

## Cognitive Tools (15)

Since **v0.9.0** the tool surface is consolidated: **every operation takes a
list**, so acting on one memory or fifty is the same call (a single item is
just a list of one). Detail and link writes are unified into one
mixed-operation batch tool per entity. The result is full **CRUD over all
three entities** with 15 tools.

| Tool | Description |
|------|-------------|
| `store_memories` | Persist one or more memories (content, category, tags, importance). |
| `recall_memories` | Fetch one or more memories by id; opt-in `include_details` / `include_links` for the richer payload. |
| `search_memory` | Search-engine style: rank memories by relevance (BM25) for multi-word/long queries; also searches details; optional graph `expand`. |
| `list_memories` | List stored memories (most important & recent first). |
| `update_memories` | Modify one or more memories (only supplied fields change). |
| `forget_memories` | Delete one or more memories (now soft-deletes into trash for safety). |
| `edit_details` | Add / update / delete extra facts attached to memories — mixed ops in one batch. |
| `edit_links` | Create (`link`) / remove (`unlink`) directed connections — mixed ops in one batch. |
| `recall_related` | Multi-hop recall: memories connected to one memory, up to *depth* hops. |
| `connect_memories` | Shortest connection (path) between two memories. |
| `memory_map` | Return a map (nodes + links) of the memory graph. |
| `summarize_memories` | Summary statistics: totals, categories, top tags, connection stats, most-connected memories. |
| `export_graph_html` | Export the complete graph to a standalone interactive 3D HTML file. |
| `restore_memories` | Soft-delete trash, history, rollback, and trash purge management. |
| `transfer_memories` | Export/import graph data and create instant database backups. |

Every list-taking tool processes items independently and reports a per-item
`status` — one bad item never aborts the batch.

### Mixed-operation batches

`edit_details` — each item's `op` selects the operation:

```json
{"items": [
  {"op": "add",    "memory_id": "<id>", "content": "config lives in /etc/nginx"},
  {"op": "update", "detail_id": "<id>", "content": "corrected fact"},
  {"op": "delete", "detail_id": "<id>"}
]}
```

`edit_links` — connect/disconnect memories, mixed in one call:

```json
{"items": [
  {"op": "link",   "from_id": "<a>", "to_id": "<b>", "relation": "depends_on", "weight": 0.9},
  {"op": "link",   "from_id": "<a>", "to_id": "<c>"},
  {"op": "unlink", "from_id": "<a>", "to_id": "<d>"}
]}
```

Re-linking the same from/to/relation updates the weight (upsert). Detail ids
are returned by the `add` op and by `recall_memories(include_details=true)`.

Two read-only resources are exposed as JSON: `brainmemory://stats` (the summary)
and `brainmemory://graph` (the nodes + links map).

> **Migrating from v0.8.0 or earlier:** the singular tools (`store_memory`,
> `recall_memory`, `update_memory`, `forget_memory`, `add_detail`,
> `link_memories`, `unlink_memories`) and the v0.8.0 bulk names
> (`store_memories` kept its name; `add_details`, `link_memories_bulk`,
> `unlink_memories_bulk` were folded into `edit_details` / `edit_links`) are
> replaced by the 15 tools above. The **database is untouched** — only the
> tool names/shapes changed, not the storage or graph model.

## Search (like a search engine)

`search_memory` no longer needs a single keyword. It tokenises your query and
ranks memories by relevance, so full sentences work:

- **Full-text + BM25** — a SQLite **FTS5** index over content/tags/category/
  details (kept in sync by triggers), ranked with BM25. Multi-word / long
  queries match memories containing *any* (or, with `mode="all"`, *every*) term,
  with prefix + Porter stemming (`sync` matches `syncing`).
- **Graph spreading activation** — with `expand=True` (default), memories
  connected in the knowledge graph to a text hit are pulled in with a decayed
  score, so related context surfaces even without the query words.
- **Ranking** blends text relevance with importance and recency. Each result
  carries `relevance` (0..1), `match_type` (`text` | `related` | `list`),
  `matched_terms`, and `distance` (hops from a text hit).
- **Fallback** — where a SQLite build lacks FTS5, search degrades to a tokenised
  `LIKE` term-coverage scorer, so it always works. `summarize_memories` reports
  the active engine (`fts5-bm25` or `like-fallback`).

Example: `search_memory("Burp Firefox proxy sync")` returns the relevant
memories ranked, plus anything linked to them — in a single call.

## Install

From PyPI:

```bash
python3 -m pip install brainmemory-mcp
```

From a local checkout:

```bash
python3 -m pip install .
```

Both install the package and a console script named `brainmemory-mcp`.

For development (editable install):

```bash
python3 -m pip install -e ".[dev]"
```

To build/publish a release, see [`docs/RELEASING.md`](docs/RELEASING.md).

## Run

### stdio mode (default)

Best for local MCP clients that launch the server themselves. Memory in
`~/.brainmemory-mcp`.

```bash
brainmemory-mcp

# Or without the console script
python3 -m brainmemory_mcp

# With a custom memory location
brainmemory-mcp --data-dir /path/to/memory
```

### Web mode (HTTP + SSE)

Enable with `--web` for remote / networked clients.

```bash
# Defaults: 127.0.0.1:8765, memory in ~/.brainmemory-mcp
brainmemory-mcp --web

# Custom host/port and memory location
brainmemory-mcp --web --host 0.0.0.0 --port 9000 --data-dir /path/to/memory
```

Endpoints once running in web mode:

- SSE stream:      `http://<host>:<port>/sse`
- Message POST:    `http://<host>:<port>/messages/`

### Configuration

| Option | Env var | Default |
|--------|---------|---------|
| `--web` | `BRAINMEMORY_WEB` | `false` (stdio) |
| `--host` | `BRAINMEMORY_HOST` | `127.0.0.1` |
| `--port` | `BRAINMEMORY_PORT` | `8765` |
| `--data-dir` | `BRAINMEMORY_HOME` | `~/.brainmemory-mcp` |

## Connect a client

### stdio (recommended for local use)

Configure the client to launch the server as a subprocess:

```json
{
  "mcpServers": {
    "brainmemory": {
      "command": "uvx",
      "args": ["brainmemory-mcp"]
    }
  }
}
```

If installed on your `PATH`, you can use `"command": "brainmemory-mcp"` with
`"args": []` instead.

### Web (SSE)

Start the server with `--web`, then point an SSE-capable client at the `/sse`
endpoint:

```json
{
  "mcpServers": {
    "brainmemory": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}
```

## How memory is stored

Memories live in `~/.brainmemory-mcp/memory.db` (SQLite, WAL mode) across three
tables:

- `memories` — nodes: `id`, `content`, `category`, `tags`, `importance` (1–5),
  `created_at`, `updated_at`.
- `memory_details` — extra facts attached to a memory (cascade-deleted with it).
- `memory_links` — directed connections `source_id -> target_id` with a
  `relation` and `weight` (cascade-deleted with either endpoint).

Search uses a SQLite **FTS5** full-text index (`memories_fts`, kept in sync by
triggers) ranked with BM25, augmented by graph spreading activation. Graph
operations (multi-hop `recall_related`, shortest-path `connect_memories`, degree
centrality in `summarize_memories`) are computed with plain SQL + a little
Python — no external services or vector database required.

Nothing is ever silently deleted — removal only happens through
`forget_memories` or explicit `delete` ops in `edit_details` / `edit_links`.
When an older database is opened that lacks the newest schema (the graph
tables or the FTS index), it is **backed up automatically** to
`~/.brainmemory-mcp/backups/` before the new objects are added.

## License

MIT
