Membase MCP Server for Distributed Agent Memory

Overview

Membase MCP Server is a lightweight Model Context Protocol (MCP) server that uses Membase as its backing store to manage agent memory across distributed nodes. It provides a consistent, low-latency interface for storing, retrieving, and querying contextual memory that agents (chatbots, assistants, or services) can share and access. By delegating storage concerns to Membase, the server benefits from cluster replication, sharding, and fast key/value access while exposing an MCP-compatible API for application-level usage.

This server is useful when you need a scalable memory layer for multi-agent systems or retrieval-augmented workflows. Instead of each agent keeping local ephemeral state or implementing ad-hoc storage synchronization, the MCP server centralizes memory persistence with predictable performance and TTL semantics, making it straightforward to implement long-term memory, session continuity, and cross-node context retrieval.

Features

• MCP-compatible REST endpoints for storing and retrieving agent memory
• Backed by Membase for scalable, replicated storage
• Namespaces/buckets support to isolate agent data
• Configurable TTL for time-limited memories
• Query-by-metadata and simple text search via indexed fields
• Low-latency get/put operations designed for real-time agents
• Docker-friendly with environment-driven configuration
• Simple authentication and ACL hooks (pluggable)

Installation / Configuration

Prerequisites:

• A running Membase (Couchbase/Membase) cluster accessible to the MCP server
• Go runtime (for building from source) or Docker

Clone and build the server:

git clone https://github.com/unibaseio/membase-mcp.git
cd membase-mcp
go build -o membase-mcp ./cmd/server

Run locally (example):

export MCB_HOSTS="127.0.0.1:8091"
export MCB_BUCKET="agent-memory"
export MCB_USERNAME="admin"
export MCB_PASSWORD="password"
export MCP_BIND="0.0.0.0:8080"

./membase-mcp

Docker (example):

# docker-compose.yml
version: "3.8"
services:
  membase:
    image: couchbase:community
    ports:
      - "8091:8091"
      - "11210:11210"
    environment:
      - COUCHBASE_ADMINISTRATOR_USERNAME=admin
      - COUCHBASE_ADMINISTRATOR_PASSWORD=password

  mcp:
    image: unibaseio/membase-mcp:latest
    depends_on:
      - membase
    environment:
      - MCB_HOSTS=membase:8091
      - MCB_BUCKET=agent-memory
      - MCB_USERNAME=admin
      - MCB_PASSWORD=password
      - MCP_BIND=0.0.0.0:8080
    ports:
      - "8080:8080"

Configuration options (env vars):

On first run the server will create required bucket scopes/collections or instruct you to create them manually depending on cluster permissions.

Available Resources

The server exposes a small set of HTTP endpoints following MCP semantics. Typical endpoints include:

• POST /mcp/v1/memory — upsert memory item
• GET /mcp/v1/memory/{id} — retrieve memory by id
• POST /mcp/v1/query — run a metadata or text query
• DELETE /mcp/v1/memory/{id} — delete a memory item

Typical memory document schema:

{
  "id": "uuid",
  "agent_id": "assistant-1",
  "text": "User asked about order status",
  "metadata": {"intent":"order_status","order_id":"1234"},
  "created_at": "2025-12-01T12:34:56Z",
  "ttl": 2592000
}

Authentication is pluggable; the server supports an optional API key via MCP_AUTH_KEY or can be integrated with existing auth middleware.

Use Cases

• Session continuity for chat agents: store conversational turns keyed by session or user id so any node can reconstruct recent context when handling a request. Example: store each user message and agent reply with metadata tags (topic, sentiment), then query the last N messages before generating a response.

• Retrieval-augmented generation (RAG): persist facts, documents, or extracted memory vectors in Membase and query by metadata or text to assemble prompts for LLMs. Example: tag product descriptions with product_id and query relevant facts when a user asks about that product.

• Cross-node shared memory in multi-agent systems: multiple microservices or agent instances access the same memory store to coordinate state. Example: a task agent writes task progress and other agents can query that progress without direct coupling.

• Time-limited reminders and ephemeral memory: use TTL to automatically expire memories like one-time notifications or temporary context. Example: set TTL=3600 for short-lived session hints.

Examples

Store a memory (curl):

curl -X POST http://localhost:8080/mcp/v1/memory \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_AUTH_KEY" \
  -d '{
    "id":"m-001",
    "agent_id":"assistant-1",
    "text":"User is allergic to peanuts.",
    "metadata":{"topic":"allergies"},
    "ttl":0
  }'

Query recent memories for an agent:

curl -X POST http://localhost:8080/mcp/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id":"assistant-1",
    "limit": 10,
    "sort":"created_at:desc"
  }'

Troubleshooting & Tips

• Ensure Membase bucket exists and the user has permissions to create indexes or collections if the server requires them.
• Monitor Couchbase/Membase indexes for query performance; create appropriate secondary indexes on metadata fields you query often.
• Use TTL to limit storage growth and comply with data retention policies.

For the latest code, issues, and contributions, see the GitHub repository: https://github.com/unibaseio/membase-mcp