MCP Memory Server

A knowledge-graph-based persistent memory server for the Model Context Protocol (MCP). Stores entities, observations, and relations in SQLite with semantic vector search, temporal versioning, and cursor-based pagination.

Attribution

This project is derived from @modelcontextprotocol/server-memory by Anthropic, PBC, originally published under the MIT License as part of the MCP Servers monorepo. The original LICENSE file is preserved in this repository.

Related MCP server: MCP Memory Server

Features

• SQLite storage with WAL mode, foreign key constraints, and database-level deduplication

• Semantic vector search via sqlite-vec + local ONNX embeddings (384-dim; all-MiniLM-L6-v2 by default, swappable via MEMORY_EMBED_MODEL)

• Relevance-ranked search — search_nodes with orderBy: 'relevance' fuses LIKE, BM25 full-text, vector, and activation signals via reciprocal-rank fusion

• Temporal versioning — observations and relations track superseded_at timestamps; old data is preserved for history but hidden from active queries

• Point-in-time queries — as_of parameter on read/search operations recovers the graph state at any past timestamp

• Entity soft-delete — delete_entities marks entities as superseded (preserving history) rather than hard-deleting

• Entity name normalization — surface variants like Dustin-Space, dustin/space, and DUSTIN SPACE all resolve to the same identity key

• Observation metadata — importance (1-5 scale), context_layer (L0/L1/null), memory_type classification, and caller-supplied valid-time (validFrom/validUntil) on observations

• Context layers — get_context_layers returns L0 (always-loaded rules) and a two-tier L1 (session-start context): a featured tier of full text plus a per-entity breadcrumb index for the overflow, both under char budgets

• Session-start briefing — get_summary returns top observations by importance, recently updated entities, and aggregate stats

• Entity timeline — view full change history (active + superseded + tombstoned observations and relations)

• Similarity detection — add_observations warns when new observations are semantically similar to existing ones

• Four-tier eviction — Active → Superseded → Tombstoned → Hard-deleted degradation chain with 6-month LRU shield and configurable size cap (default 1 GB)

• Cursor-based pagination — sorted by most-recently-updated, stable under concurrent use

• Project scoping — optional projectId parameter isolates entities by project

• Auto-migration — an existing JSONL file is upgraded to SQLite automatically on first run (the JSONL backend itself was retired in v1.6.0)

Installation

npm install
npm run build

Note: better-sqlite3 is a native C addon. You'll need C build tools (gcc, make) installed. On Fedora: sudo dnf install gcc make. On Ubuntu/Debian: sudo apt install build-essential.

Full harness install (recommended for Claude Code)

The server alone provides the storage layer. To replicate the full session-lifecycle integration — auto-loaded L0 context, freshness scanning, pre/post-compact agents, noise gating, /audit-memory and /checkpoint skills, custom QA agents — see harness/README.md:

cd harness
./install.sh

The installer is idempotent, backs up existing files, and prints the manual integration steps (settings.json merge, MCP registration, CLAUDE.md fragments) at the end.

Usage

With Claude Code

Add to your MCP server configuration:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-memory-server/dist/index.js"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/your/memory.db"
      }
    }
  }
}

Environment Variables

Tools

Data Model

• Entities — named nodes with a type, a project scope, and timestamped observations. Entity names are normalized (case-insensitive, separator-insensitive) for identity matching while preserving the original display form.

• Relations — directed edges between entities with temporal tracking (createdAt, supersededAt)

• Observations — { content, createdAt, importance, contextLayer, memoryType } objects attached to an entity (the atomic unit of knowledge)

Temporal Versioning

Observations, relations, and entities support a four-tier lifecycle:

• Active items appear in read_graph, search_nodes, and open_nodes

• Superseded items are hidden from active queries but preserved for history and as_of recovery

• Tombstoned items have their content stripped by the eviction system but preserve the existence skeleton

• Hard-deleted items are permanently removed when under extreme size pressure

• Use entity_timeline to see the full history of any entity (all tiers)

• Use as_of parameter on read_graph/search_nodes/open_nodes to recover the graph at any past timestamp

Vector Search

Vector search is automatic when using the SQLite backend:

• Uses sqlite-vec (brute-force KNN) with local ONNX embeddings (384 dimensions; all-MiniLM-L6-v2 by default, configurable via MEMORY_EMBED_MODEL)

• Model downloads ~23MB on first startup (cached thereafter)

• LIKE substring search always runs; vector search adds supplementary semantic matches

• Set MEMORY_VECTOR_SEARCH=off to disable

• If the model fails to load, the system degrades gracefully to LIKE-only search

Storage Backends

SQLite (default, recommended)

SQLite is the default and recommended backend. Features: WAL mode, FK constraints, database-level deduplication, vector search, temporal versioning, schema migrations.

JSONL (retired in v1.6.0)

The JSONL flat-file backend was deprecated since v1.0.0 and removed in v1.6.0. SQLite is now the only live backend. The one-time upgrade path remains: point MEMORY_FILE_PATH at an existing .jsonl file (or keep the same path across the upgrade) and the server migrates it into SQLite once. A .jsonl path with no file behind it errors, since there is nothing to migrate.

Migration from JSONL

1. Change MEMORY_FILE_PATH to a .db path (or point it at your existing .jsonl — the server redirects to the sibling .db)

2. On first run, the server auto-migrates data from the .jsonl file into SQLite in a single transaction

3. The original JSONL file is renamed to .jsonl.bak

Known Limitations

• Entity names are globally unique across all projects (relations use names as FK)

• Project filtering is advisory, not a security boundary

• Paginated relations use either-endpoint semantics — each page carries every relation touching one of its entities (the partner may be on another page; it's a name — open_nodes it for content). The deduped union across all pages is the complete active relation set

• Vector search is best-effort — degrades to LIKE-only if model/extension unavailable

• vec0 is brute-force KNN — fine at current scale, consider ANN at ~50,000+ observations

• Context layers and memory types are caller-managed — the server stores them but does not auto-classify

See CLAUDE.md for detailed architecture documentation and the full limitations list.

Development

npm test           # run tests (539 non-vector tests across 17 files, plus the opt-in 16-test vector-integration suite)
npm run test:watch # run tests in watch mode
npm run build      # compile TypeScript
npm run watch      # compile in watch mode

Set SKIP_VECTOR_INTEGRATION=1 to skip the vector integration tests (which load the embedding model) for faster CI runs. The vector-integration suite should be run single-fork (it loads a real ONNX model) — see MEMORY_VECTOR_SEARCH/SKIP_VECTOR_INTEGRATION and the test-pool notes in CLAUDE.md.

License

See LICENSE for the full text and original copyright notices. The upstream project is transitioning from MIT to Apache-2.0; documentation is licensed under CC-BY-4.0.