mcp-memory-service

Performs sub-5ms vector similarity search over stored memories using ONNX-based local embeddings without external API calls. Implements a hybrid retrieval pipeline that combines dense vector search (via sqlite-vec) with optional ONNX-based re-ranking to surface contextually relevant memories from long-term storage. The system maintains embedding indices in SQLite or Cloudflare Vectorize, enabling instant semantic matching without cloud latency or token costs.

Maintains a typed, directed knowledge graph where memories are nodes and relationships (causes, fixes, contradicts, references, etc.) are edges with semantic meaning. The system stores relationships in a relational schema (likely using SQLAlchemy ORM based on architecture patterns) and supports graph traversal queries to infer indirect associations and build richer context. Relationships are typed to enable domain-aware reasoning (e.g., distinguishing causal links from contradictions).

Provides command-line utilities for backing up memory to files, restoring from backups, and synchronizing memory between different storage backends or instances. Supports incremental backups to minimize storage overhead and includes validation checks to ensure data integrity during restore operations. Synchronization utilities enable replication of memory across multiple deployments (e.g., local to cloud, or between team members).

Encodes and decodes memory metadata (entity types, relationships, quality scores, access patterns) into a compact binary format for efficient storage and transmission. The system tracks quality metrics (access frequency, recency, consolidation status, confidence scores) and provides analytics to identify memory health issues (stale facts, low-confidence memories, orphaned relationships). Analytics can be queried to generate reports on memory quality and usage patterns.

Provides Docker containerization for easy deployment of the memory service in containerized environments (Kubernetes, Docker Compose, etc.) and system service installation scripts for running the service as a background daemon on Linux/macOS. Docker images include all dependencies (Python, ONNX, SQLite) and expose the REST API and MCP server ports. System service installation enables automatic startup on system boot and process supervision.

Implements a background consolidation system inspired by biological memory consolidation that automatically clusters similar memories, compresses redundant information, and applies time-decay to less-relevant facts. The system runs asynchronously (likely via background tasks or scheduled jobs) to analyze memory access patterns, identify semantic clusters, and merge or archive memories to manage context window limits. Decay functions reduce the relevance scores of older memories, simulating natural forgetting while preserving important facts.

Exposes memory capabilities as a Model Context Protocol (MCP) server compatible with Claude Desktop, IDEs, and other MCP clients. Implements both native MCP (stdio-based) and Remote MCP via Streamable HTTP with mDNS discovery, enabling agents to access memory through standardized tool calls. The HTTP bridge allows remote clients to communicate with the MCP server over the network with OAuth 2.1 authentication, supporting multi-client scenarios without requiring local installation.

Provides a FastAPI-based REST API for memory operations (store, retrieve, update, delete) with OAuth 2.1 PKCE and Dynamic Client Registration (DCR) for secure team collaboration. The API supports both local (development) and remote (production) deployments, with token-based authentication and optional role-based access control. Implements standard REST conventions with JSON payloads and HTTP status codes, making it compatible with any HTTP client (Python, JavaScript, Go, etc.).

Processes unstructured documents (text, markdown, PDFs) by chunking them into semantic units, extracting metadata (entity types, tags, timestamps), and storing them as memories with embeddings. The pipeline uses configurable chunking strategies (sliding window, sentence-based, or semantic) to preserve context while respecting embedding model limits. Metadata extraction likely uses regex patterns or LLM-based extraction to identify entities, relationships, and tags from document content.

Integrates with Claude's conversation hooks (session start/end) to automatically retrieve relevant memories at the beginning of a conversation and consolidate new memories at the end. The system intercepts Claude API calls to inject context from the memory service and capture new facts from conversation transcripts. This enables Claude to maintain continuity across separate conversations without explicit memory management by the user.

Implements a local ONNX-based re-ranker that scores and ranks search results based on relevance and quality metrics without external API calls. The system computes quality scores based on metadata (access frequency, recency, consolidation status) and uses an ONNX model to re-rank semantic search results. Async scoring allows quality computation to run in the background without blocking retrieval operations.

Abstracts storage operations behind a unified interface that supports both local SQLite (with vec extension) and remote Cloudflare Workers (D1 database, Vectorize embeddings, R2 object storage). The system automatically selects the appropriate backend based on configuration and provides transparent fallback/synchronization between backends. Hybrid mode enables local caching with remote persistence, reducing latency while maintaining durability.

Provides a single-page application (SPA) dashboard for visualizing memory contents, searching memories, managing relationships, and monitoring consolidation status. The dashboard connects to the REST API to display memory objects, knowledge graph relationships, and quality metrics in an interactive interface. Supports filtering, tagging, and manual memory editing for administrative tasks.