Memory MCP Server

A Model Context Protocol (MCP) server that gives AI agents persistent memory. Memories are stored in a local SQLite database (auto-created, zero-config) and exposed through forty tools following a tools-first architecture. Built on the template-mcp-server production scaffold (FastMCP + FastAPI, structured logging, containers, OpenShift manifests, CI).

Features

• 40 MCP tools across four domains: memory, tasks, time (reminders/alerts), dashboard

• Seven memory tools: store, get, search, list, update, delete, projects

• Seven todo tools: create/search/list/get/update/complete/delete with priority and due dates

• Eight kanban tools: boards with configurable columns; card add/move/update/delete

• Seven tracker tools: status trackers whose entries roll up into progress metrics

• SQLite persistence via aiosqlite — single file, tuned WAL baseline, auto-created

• Full-text keyword search — whole-word, porter-stemmed matching over an FTS5 index, ranked by relevance (best match first)

• Tags & metadata on memories and todos

• FastMCP + FastAPI with multiple transports (HTTP, SSE, streamable-HTTP)

• Pydantic configuration via environment variables

• Structured JSON logging with structlog

• OAuth integration (disabled by default; see docs/authentication.md)

• Container-ready (Red Hat UBI base image) and OpenShift manifests included

Search & storage behavior

Search (memory_search, todo_search) matches whole-word tokens over a porter-stemmed full-text index: partial words never match (querying check will not match checklist), punctuation and operators are treated literally, and results are ranked by bm25 relevance — strongest match first, newest first on ties. Note that unicode61 tokenization treats a whole CJK sentence as a single token, so whole-word matching assumes space-delimited scripts.

Databases run in WAL mode with synchronous=NORMAL: recently committed transactions can be lost on an OS crash or power failure (an accepted tradeoff for notes/tasks — not suitable as a system of record). Steady-state WAL size is bounded by wal_autocheckpoint (~1000 pages ≈ 4 MiB); journal_size_limit (8 MiB) only lets SQLite truncate the WAL file back once checkpoints free it. Maintenance (PRAGMA optimize + a wal_checkpoint(TRUNCATE) pass) runs inline in the reminder poll loop every tenth tick and may briefly delay a tick; it is bounded by the per-hook timeout and the database busy timeout.

Quick Start

git clone https://github.com/redhat-data-and-ai/memory-mcp-server
cd memory-mcp-server
make install        # creates venv, installs deps + pre-commit hooks
make local          # starts server on localhost:5001

Verify in another terminal:

curl http://localhost:5001/health

Manual setup (without Make):

# Create venv and install
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit install

# Configure and run
cp .env.example .env
memory-mcp-server

# Verify
curl http://localhost:5001/health

Tools

Memory

Todos

Kanban

Reminders & Alerts

A background scheduler converts due reminders into alerts server-side; query them at session start with alert_list(acknowledged=false).

Dashboard

Trackers

All tools return {status: "success" | "error", ...} dictionaries and never raise across the tool boundary.

Configuration

* ENABLE_AUTH defaults to False in .env.example. Always copy .env.example to .env to start with auth disabled.

Connecting an MCP Client

Point your MCP client at the server endpoint:

{
  "mcpServers": {
    "memory": {
      "url": "http://localhost:5001/mcp"
    }
  }
}

See examples/fastmcp_client.py for a working client that stores and searches memories.

Development

make lint     # ruff + mypy
make test     # pytest with coverage
make pre-commit  # run all pre-commit hooks

Documentation

License

Apache 2.0 — derived from redhat-data-and-ai/template-mcp-server.