memory-bank-mcp

# Memory Bank MCP Server A production-ready **Model Context Protocol (MCP)** server that provides a powerful, vector-native memory bank for AI agents. Built with the [Protocol-Lattice Go Agent Framework](https://github.com/Protocol-Lattice/go-agent), this server offers persistent, searchable, and shareable memory with multiple database backends. - **Server Name**: `memory-bank-mcp` - **Version**: `0.1.0` ## Features - **Multiple Vector Store Backends**: Persist memories in your preferred database. - **In-Memory**: For quick tests and ephemeral storage. - **PostgreSQL**: Using the `pgvector` extension. - **Qdrant**: A dedicated vector database. - **MongoDB**: Using Atlas Vector Search. - **Rich Memory Management**: - **Short-Term Buffer**: Temporarily store memories for a session before committing them to long-term storage. - **Long-Term Persistence**: Embed and store memories for semantic retrieval across sessions. - **Contextual Retrieval**: Fetch relevant memories based on a query, combining both short-term and long-term results. - **Shared Memory with "Spaces"**: - Create shared memory "spaces" where multiple agents or users can collaborate. - Fine-grained access control (ACLs) with `reader`, `writer`, and `admin` roles. - Time-to-live (TTL) support for grants and spaces. - **Dynamic Embeddings**: Uses `AutoEmbedder` from the Go Agent Framework, allowing you to configure the embedding model via environment variables (e.g., OpenAI, Gemini, local models). ## Configuration Configure the server using environment variables. ### Memory Store Set `MEMORY_STORE` to one of `inmemory`, `postgres`, `qdrant`, or `mongo`. - **PostgreSQL**: ```bash export MEMORY_STORE="postgres" export POSTGRES_DSN="postgres://user:pass@host:port/db?sslmode=disable" ``` - **Qdrant**: ```bash export MEMORY_STORE="qdrant" export QDRANT_URL="http://localhost:6333" export QDRANT_COLLECTION="memories" export QDRANT_API_KEY="..." # Optional ``` - **MongoDB**: ```bash export MEMORY_STORE="mongo" export MONGO_URI="mongodb+srv://..." export MONGO_DATABASE="main" export MONGO_COLLECTION="memories" ``` ### Other Settings - `SHORT_TERM_SIZE`: Max items in the short-term buffer per session. (Default: `20`) - `DEFAULT_SPACE_TTL_SEC`: Default TTL for spaces in seconds. (Default: `86400` / 24 hours) ### Embedding Model The server uses `AutoEmbedder`, which respects `ADK_EMBED_*` environment variables from the Go Agent Framework. For example, to use Gemini: ```bash export ADK_EMBED_PROVIDER="gemini" export ADK_EMBED_MODEL="text-embedding-004" export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" ``` ## Quick Start ```bash go install github.com/Protocol-Lattice/memory-bank-mcp@latest # Run the server (defaults to stdio transport) memory-bank-mcp ``` ## Available MCP Tools The server exposes a comprehensive set of tools for memory manipulation. ### Core Memory - `health.ping`: Check if the server is running. - `memory.embed`: Get the vector embedding for a piece of text. - `memory.add_short`: Add a memory to a session's short-term buffer. - `memory.flush`: Persist a session's short-term buffer to the long-term vector store. - `memory.store_long`: Directly embed and store a memory in the long-term store. - `memory.retrieve_context`: Retrieve relevant memories for a query from a session. ### Spaces (Shared Memory) - `spaces.upsert`: Create or update a shared space with a TTL and ACL. - `spaces.grant`: Grant a role (`reader`, `writer`, `admin`) to a principal for a space. - `spaces.revoke`: Revoke a principal's access to a space. - `spaces.list`: List all spaces a principal has access to. ### Shared Sessions - `shared.join`: Make a principal's session view include a specific space. - `shared.leave`: Remove a space from a principal's session view. - `shared.add_short_to`: Add a short-term memory directly to a shared space. - `shared.retrieve`: Retrieve memories from a principal's merged view (local + joined spaces). ## MCP Configuration: ``` { "servers": { "memory-bank": { "command": "/usr/local/bin/memory-bank-mcp", "args": ["-transport", "http", "-addr", ":8080"] } }, "inputs": [] } ``` ### Diagnostics - `engine.metrics`: Get a snapshot of the memory engine's performance metrics.