Skip to content

README.md

Latest commit

 

History

History
173 lines (124 loc) · 8.46 KB

README.md

File metadata and controls

173 lines (124 loc) · 8.46 KB
Raw

Memory MCP Server

MCP server for providing context preservation to LLMs

Features

  • Uses PostgreSQL as storage backend
  • Supports vector search (requires pgvector)
  • Uses all-minilm-l6-v2 for embedding vector generation

Key Dependencies

  • rmcp MCP SDK package
  • Tokio Asynchronous runtime
  • Diesel PostgreSQL client
  • Hyper HTTP server
  • burn Model execution engine

Build Instructions

You need to place the model.onnx file of all-minilm-l6-v2 into the ./assets directory, and use the script provided by burn-onnx to upgrade the model to opset version 16.

If output verification is needed, you need to place the pytorch_model.bin of all-minilm-l6-v2 into the ./assets directory, and use the test.py script to create embedding outputs.

Build Modes

  • Default build is CPU-only (faster build time, suitable for CI/CD and Docker):
cargo build --release
  • Enable GPU inference support at compile time:
cargo build --release --features gpu

The runtime --gpu flag only takes effect when the binary is built with --features gpu.

Runtime Configuration

The server supports both CLI arguments and environment variables. The .env file is loaded automatically at startup.

Quick Start

cargo run --release -- \
    --host 0.0.0.0 \
    --port 9180 \
    --max-search-results 20

Enable GPU at runtime (only valid when built with --features gpu):

cargo run --release --features gpu -- --gpu

Run database migrations only (do not start MCP server):

cargo run --release -- --migrate-only --db-url postgres://postgres:password@localhost/memory_mcp_db

CLI Arguments

Argument Type Default Description
--gpu bool flag false Enable GPU inference. Requires compile-time feature gpu.
--host string 0.0.0.0 HTTP server bind host.
--port u16 9180 HTTP server bind port.
--max-search-results i64 20 Maximum number of search results returned by search tools.
--db-url string postgres://postgres:password@localhost/memory_mcp_db PostgreSQL connection string.
--allowed-hosts comma-separated string localhost,127.0.0.1 Allowed hosts for streamable HTTP server.
--allowed-origins comma-separated string empty Allowed origins for streamable HTTP server.
--migrate-only bool flag false Only run database migrations, then exit without starting the server.

Environment Variables

Variable Default Maps to Description
DATABASE_URL postgres://postgres:password@localhost/memory_mcp_db --db-url PostgreSQL connection string.
MAX_SEARCH_RESULTS 20 --max-search-results Max number of returned search results.
ALLOWED_HOSTS localhost,127.0.0.1 --allowed-hosts Comma-separated allowed hosts.
ALLOWED_ORIGINS empty --allowed-origins Comma-separated allowed origins.
RUST_LOG info (fallback in code) tracing filter Log level filter (for example debug, info, warn).

Example .env:

DATABASE_URL=postgres://postgres:password@localhost/memory_mcp_db
MAX_SEARCH_RESULTS=20
ALLOWED_HOSTS=localhost,127.0.0.1
ALLOWED_ORIGINS=
RUST_LOG=info

Note: when both CLI arguments and environment variables are provided, CLI arguments take precedence.

Third-Party Model Notice

This project uses model assets from sentence-transformers/all-MiniLM-L6-v2 on Hugging Face.

The Docker build process uses the repository model asset (assets/model.onnx, managed by Git LFS) during compile time. The model data is embedded into the compiled binary, so runtime distribution does not require shipping model/tokenizer files under assets/.

Linux Binary Distribution Notice

This project publishes Linux x86_64 static binaries via GitHub Actions CI.

GitHub Releases currently contain a single Linux artifact built for x86_64-unknown-linux-musl.

When distributing the Linux release binary (for example via GitHub Releases), distributors should also provide:

  • a copy of LICENSE for this project;
  • third-party attribution details in THIRD_PARTY_NOTICES.md;
  • the model license copy in assets/all-MiniLM-L6-v2-LICENSE.txt.

For this project, Linux release archives do not need to include model files from assets/ because the model is embedded in the binary.

MCP Server Features

Designed based on a unified core table structure to replace dynamic table creation which easily leads to Catalog bloat. The system currently contains two core tables:

  1. documents: Stores metadata of document collections (categories).
  2. memory_items: Stores specific memory vector chunks.

Core Table Structure

documents table structure:

CREATE TABLE documents (
    id bigserial PRIMARY KEY,
    name TEXT NOT NULL UNIQUE,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

memory_items table structure:

CREATE TABLE memory_items (
    id bigserial PRIMARY KEY,
    document_id BIGINT NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
    summary TEXT NOT NULL,
    summary_embedding vector(384),
    content TEXT NOT NULL,
    content_embedding vector(384),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Tools provided to AI Agent

Tool Name Primary Function Arguments Internal Execution Logic
create_document Create a new document collection category name (string) description (string) Registers a new document collection category in the documents table and returns the assigned ID.
list_documents Get a list of current document collections keyword (string, optional) limit (integer, optional) offset (integer, optional) Supports keyword retrieval (hybrid semantic + trigram) with pagination; returns matched documents.
delete_document Completely delete a document collection and related chunks document_id (integer) Deletes records from documents, utilizing CASCADE deletion to clean up chunk data in memory_items simultaneously.
update_document Update document collection name and/or description document_id (integer) name (string, optional) description (string, optional) Updates provided fields by ID; only submitted fields are modified, and related embeddings are regenerated.
insert_memory Insert a new vector memory chunk document_id (integer) summary (string) content (string) Calls burn to convert text into a 384-dimensional vector, inserting it along with the text and foreign key into the memory_items table.
delete_memory Remove a single specific memory chunk memory_id (integer) Precisely deletes the specified memory_items record by primary key. Suitable for erasing outdated or incorrect memories.
search_memory Search memory by summary and content similarity document_id (integer) query_summary (string) query_content (string) min_distance (number, optional, default value: 0.008) limit (integer, optional) Vectorizes both summary and content queries, performs hybrid retrieval on both fields in memory_items within the specified document collection, then fuses and filters results by RRF relevance score threshold (default enabled).
search_memory_summary Search memory by summary similarity document_id (integer) query_text (string) min_distance (number, optional, default value: 0.008) limit (integer, optional) Vectorizes the query text, performs hybrid retrieval based on summary in memory_items within the specified document collection, then filters out low-relevance results by RRF relevance score threshold (default enabled).
search_memory_content Search memory by content similarity document_id (integer) query_text (string) min_distance (number, optional, default value: 0.008) limit (integer, optional) Vectorizes the query text, performs hybrid retrieval based on content in memory_items within the specified document collection, then filters out low-relevance results by RRF relevance score threshold (default enabled).