server-memory

server-memory is a local-first Model Context Protocol server for durable agent memory: entities, observations, relations, tags, activity, and fast recall backed by SQLite and FTS5.

It is intentionally boring where memory should be boring. Data stays in local databases unless you export it, the default MCP transport is stdio, and the optional shared HTTP daemon is bound to localhost by default.

What it does

• Stores a small knowledge graph in SQLite with WAL mode and FTS5 search.

• Exposes 20 MCP tools for graph writes, recall, timeline queries, import/export, tagging, backup, and statistics.

• Provides compact memory_context output for token-budgeted agent context.

• Supports optional embedding-assisted retrieval through the embeddings extra.

• Keeps workspace memory and global preference memory separate by default.

• Includes a localhost HTTP daemon plus stdio proxy for clients that need one shared process.

• Uses platform-native per-user data and runtime directories through platformdirs.

MCP client
  |
  | stdio: server-memory
  v
FastMCP server
  |
  +-- workspace SQLite DB: entities, observations, relations, tags, activity
  |
  +-- optional global preferences DB

Optional shared mode:
MCP client -> stdio_proxy.py -> http://127.0.0.1:8765/mcp -> serve.py

Related MCP server: recall-mcp

Requirements

• Python 3.10 or newer

• SQLite with FTS5 enabled

• macOS, Ubuntu, or Windows for the GitHub Actions support matrix

The CI workflow is configured to test Python 3.10 through 3.14 on Ubuntu and Python 3.10 plus 3.14 on ubuntu-latest, windows-latest, and macos-latest.

Install

From this GitHub repository:

python -m pip install "server-memory @ git+https://github.com/MK-986123/server-memory.git"

For local development from a checkout:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Optional extras:

python -m pip install -e ".[embeddings]"
python -m pip install -e ".[desktop-proxy]"
python -m pip install -e ".[benchmark]"

Quick start

Run the stdio MCP server:

server-memory

Equivalent module form:

python -m server_memory

Use a dedicated database for one project:

MEMORY_DB_PATH=<PROJECT_ROOT>/memory.db server-memory

Run the shared localhost daemon:

python serve.py --host 127.0.0.1 --port 8765 --transport streamable-http

Connect stdio-only clients to that daemon:

python stdio_proxy.py --url http://127.0.0.1:8765/mcp

MCP client config

Stdio server:

{
  "mcpServers": {
    "server-memory": {
      "command": "server-memory",
      "env": {
        "MEMORY_PROJECT": "<PROJECT_NAME>"
      }
    }
  }
}

Shared daemon proxy:

{
  "mcpServers": {
    "server-memory": {
      "command": "python",
      "args": ["<PROJECT_ROOT>/stdio_proxy.py", "--url", "http://127.0.0.1:8765/mcp"]
    }
  }
}

Tools

server-memory registers tools only; it does not register MCP resources or prompts.

Write tools modify the configured SQLite database. backup_memory writes a database backup. export_graph can print sensitive memory content, so review exports before sharing.

Configuration

Configuration is environment-driven.

.env.example contains a safe template with empty override values.

Development

python -m pip install -e ".[dev]"
python -m compileall -q src tests scripts
python -m ruff check .
python -m pytest
python -m build
python -m twine check dist/*
python -m pip_audit
python scripts/smoke_stdio.py server-memory

The smoke test sends an MCP initialize request to the installed stdio entry point and fails if stdout contains non-protocol text.

Security and privacy

• Memory databases, exports, backups, and benchmark outputs can contain sensitive user data.

• The stdio server writes protocol data to stdout; diagnostics should go to stderr or logs.

• The shared HTTP daemon defaults to 127.0.0.1 and local bearer-token auth.

• The bearer token is generated locally and stored under a platform-native runtime directory unless MEMORY_AUTH_TOKEN_PATH is set.

• No external service credentials are required for the core server.

• Optional embeddings may load local or cached model files depending on your environment and installed extras.

Report vulnerabilities through GitHub private vulnerability reporting when available. Do not include secrets or private memory exports in public issues.

CI and supply chain

GitHub Actions run syntax checks, Ruff, pytest, package build, wheel installation, MCP stdio smoke tests, pip-audit, CodeQL, and Dependency Review. Dependabot is configured for Python dependencies and GitHub Actions.

The workflow uses GitHub-hosted ubuntu-latest, windows-latest, and macos-latest labels. GitHub defines those as the latest stable runner images it provides, which can lag the newest vendor OS release during image migrations.

Troubleshooting

License

No open-source license has been selected. Public visibility does not grant reuse rights by itself.