Memory MCP

Memory MCP is a production-grade server for managing and persisting memory for single-tenant LibreChat workspaces. It stores raw conversation turns, distills durable memory such as decisions and constraints, supports hybrid retrieval, and provides plan consistency auditing to keep your memory and plans aligned over time.

How to use

You interact with Memory MCP through MCP clients. Create plans to organize work, open threads under those plans, and ingest turns to build up memory. You can extract distilled decisions and constraints from new turns, retrieve relevant context with fast or deep modes, and audit plans to ensure consistency. You can also share and import memory through signed packages to collaborate in a controlled way. The system exposes observability data like JSON logs and Prometheus metrics to help you monitor health and usage.

How to install

Prerequisites: you need a working environment with Docker and Docker Compose installed, along with a supported runtime for building and running the MCP components. You should also have a compatible shell to run commands.

# Step 1: Prepare environment
cp .env.example .env

# Step 2: Start services
make up

# Step 3: Apply database migrations
make migrate

# Step 4: Run tests (optional but recommended)
make test

Additional setup and usage notes

Configure your environment by editing the environment file to include your database URL, API key for your language model, and a shared HMAC secret for secure package sharing.

The MCP endpoint is available under the /mcp path. You can send tool commands with JSON payloads to perform actions like creating plans, threads, ingesting turns, or performing retrieval and audits.

Security and maintenance

Security features include strict validation with Pydantic models, explicit prompts to guard against injection, and HMAC-signed export/import payloads. API keys are not logged.

LibreChat MCP configuration examples

Set up your LibreChat MCP URL as follows to point your client to Memory MCP endpoints.

Example workflow summaries

New Plan Initiation: create a plan, open a thread under that plan, and ingest the first decisions. Continue an existing plan by listing plans, following the relevant thread IDs, and extracting decisions from new turns. Perform a deep audit by retrieving context with deep mode, validating plan text, and checking for superseded references to update decisions.

Available tools

plan.create

Create a new plan with a name and optional metadata to organize memory and work topics.

thread.create

Open a new thread under a specified plan to group related turns and decisions.

turn.ingest

Ingest a turn into a thread with metadata such as role, text, and optional embedding trigger to build memory.

distill.extract

Extract distilled memory such as decisions, constraints, mistakes, assumptions, and questions from turns and write to memory.

retrieve.context

Retrieve relevant context from memory using fast or deep modes with configurable top_k and token budget.

audit.check_consistency

Audit a proposed plan text against observed decisions and constraints to ensure consistency.

shared.export

Export selected memory artifacts using an HMAC-signed payload for controlled sharing.

shared.import

Import a signed memory payload to incorporate external memory into your workspace.