Memory Bank

You are using a production-ready Memory Context Protocol (MCP) server that provides a persistent, searchable, and shareable memory bank for AI agents. It supports multiple vector store backends, short- and long-term memory, and collaborative spaces with access control, making it easy to manage contextual memories across sessions and users.

How to use

You connect to the Memory Bank MCP server using MCP clients and perform memory operations across short-term buffers and long-term stores. Use the server to embed text into vectors, store memories, retrieve relevant context for queries, and share memories through spaces with collaborators. Access control lets you grant roles like reader, writer, and admin, and you can configure time-to-live (TTL) for shared spaces and grants.

Typical workflows include: 1) embedding a piece of text to get its vector, 2) adding memories to a short-term buffer for a session, 3) flushing the buffer to persist memories in the long-term store, and 4) querying contextual memories that combine both short-term and long-term results. When working in teams, create shared spaces, grant appropriate roles to principals, and optionally set TTLs to control access longevity.

To start, choose a storage backend that fits your workload and latency requirements. You can run the server locally in stdio mode for development or expose it over HTTP for remote clients. Ensure your embedding model is configured through environment variables so embeddings match your chosen provider (for example Gemini or a local model).

How to install

Prerequisites: you need a Go toolchain installed to build and install the MCP server, plus optional client tools for MCP. Ensure you have network access to pull dependencies.

Install the server and run it in stdio mode (local, with default settings):

go install github.com/Protocol-Lattice/memory-bank-mcp@latest
memory-bank-mcp

If you prefer HTTP transport, you can run the MCP with explicit HTTP transport settings (as shown in the configuration example), which serves the MCP API over HTTP at the specified address.

{
  "servers": {
    "memory-bank": {
      "command": "/usr/local/bin/memory-bank-mcp",
      "args": ["-transport", "http", "-addr", ":8080"]
    }
  },
  "inputs": []
}

Additional configuration and notes

Configure the memory store and embeddings via environment variables. Supported memory backends are in-memory, PostgreSQL with pgvector, Qdrant, and MongoDB. Set the store type and the connection details you need for your environment.

Configuration and environment variables

Store backends and core settings you can configure include the following environment variables:

• MEMORY_STORE: one of inmemory, postgres, qdrant, mongo.

• PostgreSQL specific: POSTGRES_DSN with your connection string.

• Qdrant specific: QDRANT_URL, QDRANT_COLLECTION, QDRANT_API_KEY (optional).

• MongoDB specific: MONGO_URI, MONGO_DATABASE, MONGO_COLLECTION.

• 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 configuration uses the ADK_EMBED_* variables. For example, to use Gemini you would set provider, model, and API keys as shown.

export MEMORY_STORE="postgres"
export POSTGRES_DSN="postgres://user:pass@host:port/db?sslmode=disable"
export ADK_EMBED_PROVIDER="gemini"
export ADK_EMBED_MODEL="text-embedding-004"
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

MCP configuration example

The MCP configuration file can declare the memory-bank server with its runtime command and arguments.

{
	"servers": {
    "memory-bank": {
      "command": "/usr/local/bin/memory-bank-mcp",
      "args": ["-transport", "http", "-addr", ":8080"]
    }
	},
	"inputs": []
}

Tools and endpoints

The server exposes a rich set of tools to manage memory and collaborate in spaces. You can ping the server, embed vectors, add and flush memories, retrieve context, and manage shared spaces and sessions.

Security and access control

Shared memory spaces support fine-grained ACLs with roles such as reader, writer, and admin. You can grant or revoke access to principals and configure TTLs for grants and spaces to control how long access remains available.

Troubleshooting and tips

If you encounter connection issues, verify the backend store is reachable, the embedding provider is configured correctly, and the MCP server is accessible at the specified transport (HTTP or stdio). Check that the embedding model and API keys are valid and that TTL settings align with your collaboration needs.

Available tools

health.ping

Check if the MCP server is running and reachable.

memory.embed

Compute the vector embedding for a given text.

memory.add_short

Add a memory item to a session's short-term buffer.

memory.flush

Persist the session's short-term buffer to the long-term vector store.

memory.store_long

Embed and store a memory directly in the long-term store.

memory.retrieve_context

Retrieve memories relevant to a query from the session context.

spaces.upsert

Create or update a shared memory space with TTL and ACL.

spaces.grant

Grant a role to a principal for a shared space.

spaces.revoke

Revoke a principal's access to a shared space.

spaces.list

List all spaces accessible to a principal.

shared.join

Include a space in a principal's merged view for a session.

shared.leave

Remove a space from a principal's merged 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).