MnemeBrain MCP Server

MCP server for the MnemeBrain belief memory system. Exposes 13 tools that let LLM agents store, query, revise, and reason over beliefs with evidence, confidence tracking, and Belnap four-valued logic (true / false / both / neither).

Quick Start

# Install dependencies
uv sync

# Run via stdio (default — used by Claude Desktop and most MCP hosts)
uv run mnemebrain-mcp

# Run via HTTP transport on port 3001
uv run mnemebrain-mcp --transport http --port 3001

The server connects to a running MnemeBrain backend. Set MNEMEBRAIN_URL to point at it before starting.

Configuration

Variable	Default	Description
MNEMEBRAIN_URL	http://localhost:8000	Base URL of the MnemeBrain backend
MNEMEBRAIN_API_KEY	(empty)	API key sent as Authorization: Bearer <key> header
MNEMEBRAIN_TIMEOUT	30	HTTP request timeout in seconds

Claude Desktop Config

Add the following to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "mnemebrain": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mnemebrain-mcp",
        "run",
        "mnemebrain-mcp"
      ],
      "env": {
        "MNEMEBRAIN_URL": "http://localhost:8000",
        "MNEMEBRAIN_API_KEY": "your-api-key"
      }
    }
  }
}

Tools Reference

Core Belief Operations

Tool	Description
health	Check if the MnemeBrain backend is running and healthy
believe	Store a belief with supporting or attacking evidence; merges into existing beliefs on semantic match
retract	Invalidate a piece of evidence and recompute all affected belief states
explain	Get the full justification chain (supporting, attacking, expired evidence) for a belief
revise	Add new evidence to an existing belief and recompute its truth state
search	Semantic search over beliefs with blended similarity and confidence ranking
list_beliefs	List beliefs with optional filters by truth state, type, tag, and confidence range

Working Memory Frames

Frames are ephemeral context buffers for multi-step reasoning episodes.

Tool	Description
frame_open	Open a working memory frame; auto-loads relevant beliefs via semantic search
frame_add	Load an additional belief into an active frame by claim
frame_scratchpad	Store intermediate reasoning results in a frame's scratchpad
frame_context	Get all loaded beliefs, scratchpad contents, conflicts, and step count for a frame
frame_commit	Commit new beliefs and revisions from a frame back to the belief graph
frame_close	Close a frame without committing (marks it as abandoned)

Development

Running Tests

# Unit tests (no backend required)
uv run pytest tests/ -v -k "not integration and not e2e"

# Integration tests (requires running backend at MNEMEBRAIN_URL)
MNEMEBRAIN_URL=http://localhost:8000 uv run pytest tests/test_integration.py -v -m integration

# E2E tests (requires running backend; launches the MCP server as a subprocess)
MNEMEBRAIN_URL=http://localhost:8000 uv run pytest tests/test_e2e.py -v -m e2e

Project Layout

src/mnemebrain_mcp/
  __main__.py   entry point
  server.py     tool registration and transport setup
  client.py     HTTP client for the MnemeBrain backend
  config.py     environment-variable configuration
tests/
  test_config.py       unit tests for Settings
  test_client.py       unit tests for MnemeBrainClient
  test_tools.py        unit tests for all 13 MCP tools (mocked HTTP)
  test_integration.py  integration tests against a live backend
  test_e2e.py          E2E tests via MCP stdio client

License

MIT