ZeroDB Agent Memory MCP Server

Persistent Memory for AI Agents

Optimized MCP server providing 14 tools for agent memory management, context synthesis, auto-context middleware, and write-back actions to external services.

Why This MCP?

Before: Monolithic server with 77 tools consuming 10,400+ tokens After: Focused server with 14 tools consuming ~1,400 tokens Result: 87% reduction in context footprint, faster agent decisions, better accuracy

Key Features

Smart Context Management

• Automatic token limiting - Never exceed LLM context windows
• Intelligent pruning - Keep important and recent memories
• Memory decay - Old memories naturally fade over time
• Importance scoring - Automatically rank memory significance

Semantic Memory

• Vector embeddings - BAAI BGE models (384, 768, 1024 dimensions)
• Semantic search - Find by meaning, not just keywords
• Cross-session memory - Remember across conversations
• Auto-embedding - No manual embedding required

Universal Compatibility

• ZeroLocal - localhost:8000 (fast, free, private)
• ZeroDB Cloud - api.ainative.studio (scalable, managed)
• Auto-detection - Automatically finds available endpoint

Installation

# Clone repository
git clone https://github.com/ainative/zerodb-memory-mcp.git
cd zerodb-memory-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Test locally
npm start

Configuration

Credentials

# Recommended: API key auth (no login needed)
ZERODB_API_KEY=sk_xxx
ZERODB_API_URL=https://api.ainative.studio
ZERODB_PROJECT_ID=your-project-id

# OR username/password auth:
ZERODB_USERNAME=your@email.com
ZERODB_PASSWORD=your-password
ZERODB_API_URL=https://api.ainative.studio
ZERODB_PROJECT_ID=your-project-id

Tip: API key authentication (ZERODB_API_KEY) is preferred over username/password. It avoids token expiry issues and is not affected by shell environment variable conflicts.

Option 1: Environment Variables

export ZERODB_API_URL="http://localhost:8000"  # or cloud URL
export ZERODB_API_KEY="sk_your-api-key"        # recommended
export ZERODB_PROJECT_ID="your-project-id"

Option 2: Claude Desktop Config

{
  "mcpServers": {
    "zerodb-memory": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "http://localhost:8000",
        "ZERODB_USERNAME": "your-username",
        "ZERODB_PASSWORD": "your-password",
        "ZERODB_PROJECT_ID": "your-project-id"
      }
    }
  }
}

Option 3: Use Both Local and Cloud

{
  "mcpServers": {
    "zerodb-local": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "http://localhost:8000",
        "ZERODB_USERNAME": "your-local-username",
        "ZERODB_PASSWORD": "your-local-password",
        "ZERODB_PROJECT_ID": "your-local-project-id"
      }
    },
    "zerodb-cloud": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "https://api.ainative.studio",
        "ZERODB_USERNAME": "your-cloud-username",
        "ZERODB_PASSWORD": "your-cloud-password",
        "ZERODB_PROJECT_ID": "your-cloud-project-id"
      }
    }
  }
}

Tools

1. zerodb_store_memory

Store conversation context with automatic importance scoring and embedding.

Input:

{
  "content": "User prefers technical explanations over simplified ones",
  "role": "system",
  "session_id": "chat-123",
  "tags": ["preference", "important"],
  "user_id": "user-456"
}

Output:

{
  "success": true,
  "memory_id": "mem_abc123",
  "importance": 0.85,
  "message": "Memory stored successfully"
}

Features:

• Auto-calculates importance (0.0 to 1.0)
• Generates embeddings automatically
• Supports ta

... View full README on GitHub