Metadata-Version: 2.4
Name: brainmemory-mcp
Version: 0.1.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>=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, summarize, and forget
information across sessions through standardized MCP tool calls.

The server speaks MCP over **HTTP + Server-Sent Events (SSE)**, 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

| Tool | Description |
|------|-------------|
| `store_memory` | Persist a new memory (content, category, tags, importance). |
| `recall_memory` | Fetch a single memory by its id. |
| `search_memory` | Find memories by free text, category, tags and/or importance. |
| `list_memories` | List stored memories (most important & recent first). |
| `update_memory` | Modify an existing memory (only supplied fields change). |
| `forget_memory` | Delete a memory by id. |
| `summarize_memories` | Summary statistics: totals, categories, top tags. |

A read-only resource `brainmemory://stats` exposes the same summary as JSON.

## Install

From PyPI (once published):

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

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

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

# Or without the console script
python3 -m brainmemory_mcp
```

Endpoints once running:

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

### Configuration

| Option | Env var | Default |
|--------|---------|---------|
| `--host` | `BRAINMEMORY_HOST` | `127.0.0.1` |
| `--port` | `BRAINMEMORY_PORT` | `8765` |
| `--data-dir` | `BRAINMEMORY_HOME` | `~/.brainmemory-mcp` |

## Connect a client

Point any MCP client that supports SSE at the `/sse` endpoint. Example client
configuration (URL-based transport):

```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). Each memory
has: `id`, `content`, `category`, `tags`, `importance` (1–5), `created_at`,
`updated_at`. Nothing is ever silently deleted — removal only happens through
`forget_memory`.

## License

MIT
