memory-mcp

A standalone MCP server for persistent agent memory — short/long-term tiers, measurable reliability, and lifecycle maintenance — backed by SQLite (FTS5 + sqlite-vec) with local MiniLM embeddings. No external services, no API keys.

Requirements

• Node.js >= 22
• The package ships compiled JavaScript, so no TypeScript toolchain is needed at runtime.

Install

npm install @jommar/memory-mcp

Two executables are provided:

Command	Purpose
memory-mcp-server	The MCP server (stdio by default, HTTP via MEMORY_TRANSPORT)
memory-mcp	Store maintenance CLI (export, import, reindex, stats)

Quickstart

stdio (default)

Point your MCP client at the server binary:

{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp-server"
    }
  }
}

Or run it directly:

memory-mcp-server

With npx, select the server bin explicitly (installs the package on first use):

npx -y -p @jommar/memory-mcp memory-mcp-server

HTTP (localhost only)

MEMORY_TRANSPORT=http memory-mcp-server

The HTTP endpoint binds to 127.0.0.1:3000 by default and serves both the modern (2026-07-28) and legacy (2025-11-25) protocol revisions from the same endpoint, so any MCP client can connect. The server is stateless — no session id is required.

First run

The store is created automatically at ~/.memory-mcp/memory.db. Embeddings are offline-first: no model is downloaded unless you opt in.

# opt in to the one-time model download (about 23 MB, MiniLM-L6, q8 quantized)
MEMORY_EMBEDDING_OFFLINE=false memory-mcp-server

Until a model is available, remember and recall still work — they fall back to keyword search only. Use the CLI reindex to backfill vectors after the model is in place.

Configuration

All configuration is via MEMORY_* environment variables (no config file):

Variable	Default	Purpose
MEMORY_DB_PATH	~/.memory-mcp/memory.db	SQLite database file
MEMORY_TRANSPORT	stdio	stdio or http
MEMORY_HTTP_HOST	127.0.0.1	HTTP bind host (localhost only)
MEMORY_HTTP_PORT	3000	HTTP bind port
MEMORY_EMBEDDING_OFFLINE	true	false opts in to the one-time model download
MEMORY_EMBEDDING_DOWNLOAD_TIMEOUT_MS	300000	Timeout for a model download attempt
MEMORY_EMBEDDING_CACHE_DIR	~/.memory-mcp/cache	Where downloaded models are cached
MEMORY_UI_PORT	3001	Explorer UI port (dev tool; auto-increments when busy)

Tools

Ten tools are registered: remember, recall, get, update, forget, list, confirm, contradict, promote, consolidate. See docs/tools.md for the full reference with inputs and behaviors.

remember accepts an interactive opt-in: when it finds near-duplicate entries it can ask the client to merge or create (MRTR), and degrades gracefully for clients without interactive support.

Maintenance CLI

memory-mcp export ./out      # write every memory as a markdown frontmatter file
memory-mcp import ./staging  # validate, then import (never overwrites existing keys)
memory-mcp reindex           # rebuild FTS + vector indexes from stored content
memory-mcp stats             # print store counts

Memory explorer (UI)

A read-only visual explorer for the store: links graph (React Flow, force-directed layout clustered by type), reliability breakdown per memory, history, supersession chains, filters by scope/type/tier/status, and a maintenance drawer listing consolidate proposals (orphans, stale entries, duplicate clusters) with click-to-select. It opens the SQLite database read-only, so it is safe to run alongside a live server and cannot mutate data.

The UI lives in the ui/ workspace and is a development tool — it is not part of the published package:

npm run ui:build   # compile the API server + bundle the frontend
npm run ui:start   # serve at http://127.0.0.1:3001

For frontend development with hot reload: npm run ui:dev in one terminal (proxies /api to 3001) and npm run ui:start in another.

If the port is taken, the server auto-increments (3001 → 3010) and prints the bound URL. Configuration: MEMORY_DB_PATH (same store as the server) and MEMORY_UI_PORT (default 3001). The bind host is always 127.0.0.1.

Documentation

• docs/tools.md — tool reference
• docs/reliability.md — reliability model and lifecycle rules (the report-only maintenance engine behind consolidate)

License

MIT — see LICENSE.