server-memory

Overview

server-memory is a local-first Model Context Protocol (MCP) 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.

At a glance

Highlights

• Local knowledge graph: Stores entities, observations, relations, tags, and activity in SQLite with WAL mode and FTS5 search.

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

• Compact context: Provides token-budgeted memory_context output for routine agent recall.

• Optional embeddings: Supports embedding-assisted retrieval through the embeddings extra.

• Memory scopes: Keeps workspace memory and global preference memory separate by default.

• Shared mode: Provides a localhost HTTP daemon and stdio proxy for clients that need one shared process.

• Platform-native paths: Uses platformdirs for per-user data and runtime directories.

Related MCP server: tartarus-mcp

Architecture

Default stdio mode

┌────────────┐         stdio         ┌─────────────────────┐
│ MCP client │ ────────────────────> │    server-memory    │
└────────────┘                       │    FastMCP server   │
                                     ├─────────────────────┤
                                     │ Workspace SQLite DB │
                                     │                     │
                                     │ Global preferences  │
                                     │ DB, when enabled    │
                                     └─────────────────────┘

Optional shared mode

┌────────────┐      stdio       ┌─────────────────────┐
│ MCP client │ ───────────────> │ server-memory-proxy │
└────────────┘                  └──────────┬──────────┘
                                         │
                                         │ HTTP
                                         │ 127.0.0.1:8765/mcp
                                         ▼
                              ┌─────────────────────┐
                              │ server-memory-serve │
                              │ FastMCP daemon      │
                              └─────────────────────┘

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

• Python 3.10 and 3.14 on ubuntu-latest

• Python 3.10 and 3.14 on windows-latest

• Python 3.10 and 3.14 on macos-latest

Installation

Core installation

Install directly from this GitHub repository:

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

Installation with embeddings

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

Development checkout

git clone https://github.com/MK-986123/server-memory.git
cd server-memory

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

On Windows PowerShell:

.venv\Scripts\Activate.ps1

Install development and embedding dependencies together:

python -m pip install -e ".[dev,embeddings]"

Quick start

Run the stdio server

server-memory

Equivalent module form:

python -m server_memory

Use a dedicated project database

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

Use the equivalent environment-variable syntax for your shell when running on Windows.

Run the shared localhost daemon

server-memory-serve \
  --host 127.0.0.1 \
  --port 8765 \
  --transport streamable-http

Connect a stdio-only client to the daemon

server-memory-proxy --url http://127.0.0.1:8765/mcp

MCP client configuration

Direct stdio server

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

Shared daemon proxy

Start server-memory-serve separately, then configure the MCP client to launch the proxy:

{
  "mcpServers": {
    "server-memory": {
      "command": "server-memory-proxy",
      "args": [
        "--url",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

Tool reference

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

Scope behavior

Most tools accept one of three scopes:

Preference-tagged writes still auto-route to the global database when global preference routing is enabled.

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

Configuration

Configuration is environment-driven. Empty path overrides in .env.example use the platform defaults.

Storage and scope

Retrieval and compression

Runtime and shared daemon

Development

Install the development dependencies:

python -m pip install -e ".[dev]"

Run the local validation sequence:

python -m compileall -q src tests scripts
python -m ruff check .
python -m pytest -q
python -m build
python -m twine check dist/*
python scripts/inspect_wheel.py dist
python -m pip_audit

Verify the installed entry points:

python scripts/smoke_stdio.py server-memory
server-memory-serve --help
server-memory-proxy --help

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

See CONTRIBUTING.md for contribution guidance.

Security and privacy

• 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 authentication.

• 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 the environment and installed extras.

• Review exported graph content before sharing it.

• Do not commit live memory databases, token files, or backups.

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

See SECURITY.md for the project security policy.

CI and supply chain

GitHub Actions are configured to run:

• syntax validation

• Ruff linting

• pytest across the supported Python and operating-system matrix

• wheel and source distribution builds

• wheel-content inspection

• clean installed-package checks outside the repository checkout

• MCP stdio and installed-command smoke tests

• pip-audit

• CodeQL

• Dependency Review

Dependabot is configured for Python dependencies and GitHub Actions.

The workflow uses GitHub-hosted ubuntu-latest, windows-latest, and macos-latest labels. These labels refer to GitHub's latest stable runner images and can temporarily lag the newest vendor operating-system release during image migrations.

Troubleshooting

License