mcp-memory

SQLite-backed persistent memory MCP server with FTS5 search and project scoping.

Features

• Project-scoped data - all tools take a project parameter to isolate data per project
• FTS5 full-text search - BM25-ranked search across entity names, types, and observations
• Graph traversal - explore entity relationships with filtering by type
• Safe observation updates - append or delete individual observations without overwriting
• Entity status tracking - track entity lifecycle with status fields
• Migration framework - automatic schema upgrades
• HTTP transport - single server instance shared across all clients via streamable-http

Installation

uv tool install mcp-memory

Configuration

| Environment variable | Description | Default | |---|---|---| | MCP_MEMORY_DB_PATH | Database file path | ~/.local/share/mcp-memory/memory.db | | MCP_MEMORY_PORT | HTTP server port | 8000 |

MCP client config

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

Tools

All tools require a project parameter to scope data.

create_entities

Create or update entities with observations. Overwrites all existing observations for an entity - use add_observations to append instead. Non-exempt entity types (not user-preferences or pattern) must include at least one relation.

add_observations

Append observations to an existing entity without overwriting. Skips duplicates. Throws if the entity does not exist.

delete_observations

Delete specific observations from an existing entity by exact content match. Returns the count deleted. Throws if the entity does not exist.

search_nodes

FTS5 full-text search with BM25 relevance ranking. Optional entity_type and status filters.

read_graph

Returns the 10 most recent entities and their relations.

create_relations

Create relationships between entities. Duplicates are ignored.

get_entity_with_relations

Get an entity with all its relations and connected entities via graph traversal.

search_related_nodes

Get an entity with directly related entities, optionally filtered by entityType and/or relationType.

set_entity_status

Set or clear the status of an entity. Valid statuses: planned, in-progress, blocked, resolved, archived.

delete_entity

Delete an entity and all associated observations and relations.

delete_relation

Delete a specific relation between two entities.

Development

# Run all checks (lint, type-check, test)
just

# Individual commands
just lint        # ruff check + format
just type-check  # mypy
just test        # pytest