mcp-synaptic

MCP Synaptic is a memory-enhanced MCP server that combines a memory management subsystem with a local retrieval-augmented generation (RAG) database. It offers expiring memories with configurable TTLs, multiple memory types, and optional Redis-backed storage for distributed memory. The RAG component uses a local vector store (ChromaDB) and supports embedding via API-based providers or local embeddings, along with semantic search and document versioning. Real-time updates are provided through Server-Sent Events (SSE) and WebSocket channels, enabling live visibility into memory expiration and document changes. You can interact with the server via a Python API for programmatic control or through the exposed HTTP endpoints and websockets for real-time integration. Typical workflows include storing short-term memories during a session, indexing and updating documents in the RAG store, and querying for semantically similar documents to support context-aware responses. The server implements the MCP protocol, enabling clients to manage memories, query documents, and stream events.

Prerequisites:

• Python 3.11 or higher
• uv (Python package manager) installed (via PyPI) or uvx if you are using the UV toolchain
• Optional: Docker if you want containerized deployment

1. Clone the repository (or install from package)

git clone https://github.com/your-org/mcp-synaptic.git
cd mcp-synaptic

2. Install dependencies

# Using UV (recommended for this project structure)
uv install

# Or install via Python tooling if available in your environment
pip install -r requirements.txt

3. Initialize or install the project (if the project provides a CLI)

uv run mcp-synaptic init

4. Start the server

uv run mcp-synaptic server

The server will start on http://localhost:8000 by default. If you prefer Docker, see the Docker deployment steps below.

Docker deployment (optional):

# Build and run with Docker Compose
docker-compose up --build

# Or build/run a single container
docker build -t mcp-synaptic .
docker run -p 8000:8000 mcp-synaptic

5. Verify the API is reachable

curl http://localhost:8000/health

Notes and tips:

• Environment variables control memory TTLs, memory limits, and RAG configuration. Adjust DEFAULT_MEMORY_TTL_SECONDS, MAX_MEMORY_ENTRIES, MEMORY_CLEANUP_INTERVAL_SECONDS, and RAG settings to fit your workload.
• If you enable Redis (REDIS_ENABLED=true), ensure REDIS_URL points to your Redis instance for distributed memory storage.
• For embeddings, you can switch between API-based (EMBEDDING_PROVIDER=api) and local embeddings (EMBEDDING_PROVIDER=local). When using local embeddings, be prepared for a larger container footprint.
• The API exposes endpoints for memory management (/memory), RAG operations (/rag/documents, /rag/search), and real-time events (/events and /ws). Use SSE or WebSocket clients to subscribe to updates.
• If you run into port conflicts, modify SERVER_PORT in the environment or pass host/port overrides to the server startup command.
• Typical issues include misconfigured embedding base URL or missing API keys for embedding services. Ensure EMBEDDING_API_BASE and EMBEDDING_API_KEY are correctly set when using API-based embeddings.
• For development, you can run uv sync to install dev dependencies and uv run tests to exercise the test suite.