ZeroDB Agent Memory MCP Server

Persistent Memory for AI Agents

Optimized MCP server providing 6 focused tools for agent memory management with advanced context window optimization, semantic search, and cross-session memory.

Why This MCP?

Before: Monolithic server with 77 tools consuming 10,400+ tokens After: Focused server with 6 tools consuming ~800 tokens Result: 92% 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

Option 1: Environment Variables

export ZERODB_API_URL="http://localhost:8000"  # or cloud URL
export ZERODB_USERNAME="your-email@example.com"
export ZERODB_PASSWORD="your-password"
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 tags for categorization
• Links to user for cross-session memory

2. zerodb_search_memory

Search memory semantically using natural language.

Input:

{
  "query": "What are the user's dietary restrictions?",
  "limit": 10,
  "session_id": "chat-123",
  "scope": "agent",
  "min_importance": 0.5
}

Output:

{
  "results": [
    {
      "content": "User is allergic to peanuts",
      "role": "user",
      "importance": 0.95,
      "timestamp": "2026-02-28T10:30:00Z",
      "tags": ["health", "critical"],
      "similarity": 0.89,
      "session_id": "chat-123"
    }
  ],
  "count": 1,
  "scope": "agent"
}

Features:

• Semantic search (meaning, not keywords)
• Cross-session search with scope: "agent"
• Filter by importance, tags, user
• Returns similarity scores

3. zerodb_get_context

Get full conversation context with smart pruning.

Input:

{
  "session_id": "chat-123",
  "max_tokens": 8192,
  "include_stats": true
}

Output:

{
  "memories": [
    {
      "content": "Hello, how can I help?",
      "role": "assistant",
      "importance": 0.6,
      "timestamp": "2026-02-28T10:00:00Z",
      "tags": []
    }
  ],
  "total_tokens": 2048,
  "stats": {
    "pruned": true,
    "original_count": 50,
    "returned_count": 25,
    "token_limit": 8192
  }
}

Features:

• Auto-prunes to fit token limit
• Keeps important and recent memories
• Applies memory decay if enabled
• Returns pruning statistics

4. zerodb_embed_text

Generate vector embeddings for text.

Input:

{
  "text": "The quick brown fox jumps over the lazy dog",
  "model": "BAAI/bge-small-en-v1.5",
  "normalize": true
}

Output:

{
  "embedding": [0.123, -0.456, 0.789, ...],
  "model": "BAAI/bge-small-en-v1.5",
  "dimensions": 384,
  "normalized": true
}

Features:

• Three model sizes (384d, 768d, 1024d)
• Normalized vectors
• Fast local embedding (if using ZeroLocal)

5. zerodb_semantic_search

Search by semantic similarity without text query.

Input:

{
  "text": "food preferences",
  "limit": 10,
  "session_id": "chat-123",
  "min_similarity": 0.7
}

Output:

{
  "results": [
    {
      "content": "User prefers vegetarian meals",
      "similarity": 0.85,
      "metadata": {
        "role": "user",
        "tags": ["preference"]
      }
    }
  ],
  "count": 1,
  "search_vector_dims": 384
}

Features:

• Direct vector similarity search
• Can provide text or pre-computed vector
• Filter by similarity threshold
• Session-scoped or global search

6. zerodb_clear_session

Clear all memories for a session.

Input:

{
  "session_id": "chat-123",
  "keep_important": true,
  "confirm": true
}

Output:

{
  "success": true,
  "deleted_count": 45,
  "kept_count": 5,
  "message": "Session cleared, important memories preserved"
}

Features:

• Requires confirmation
• Optional preservation of important memories
• Returns deletion statistics

Advanced Configuration

Context Window Management

# Set maximum tokens (default: 8192)
CONTEXT_WINDOW=16384

# Choose pruning strategy (default: hybrid)
# - relevance: Keep highest-scored memories
# - recency: Keep most recent memories
# - hybrid: Combine both (70% relevance, 30% recency)
PRUNE_STRATEGY=hybrid

# Always keep N recent messages (default: 5)
KEEP_RECENT=5

# Keep memories tagged as important (default: true)
KEEP_IMPORTANT=true

Memory Decay

Enable natural memory decay over time:

# Enable decay (default: false)
DECAY_ENABLED=true

# Half-life in days (default: 30)
# After 30 days, importance score is halved
DECAY_HALFLIFE=30

# Protect tags from decay
PRESERVE_TAGS=important,permanent,critical

Example:

• Day 0: importance = 0.8
• Day 30: importance = 0.4
• Day 60: importance = 0.2
• Memories with important tag: never decay

Automatic Summarization

Compress old conversations automatically:

# Enable summarization (default: true)
SUMMARIZE_ENABLED=true

# Summarize after N messages (default: 20)
SUMMARIZE_AFTER=20

# Model for summarization
SUMMARY_MODEL=claude-3-haiku-20240307

# Keep original messages (default: false)
KEEP_ORIGINALS=false

Behavior:

1. After 20 messages, oldest 15 are summarized
2. Summary stored as new memory with summary tag
3. Original messages deleted (unless KEEP_ORIGINALS=true)
4. Recent 5 messages always kept

Embedding Models

Choose embedding model based on needs:

# Small (384 dimensions) - Fast, efficient
EMBEDDING_MODEL=BAAI/bge-small-en-v1.5

# Base (768 dimensions) - Balanced
EMBEDDING_MODEL=BAAI/bge-base-en-v1.5

# Large (1024 dimensions) - Most accurate
EMBEDDING_MODEL=BAAI/bge-large-en-v1.5

Trade-offs:

• Small: 3x faster, 70% accuracy
• Base: 2x faster, 85% accuracy
• Large: 1x baseline, 95% accuracy

Use Cases

Customer Support Agent

// Store user preferences
await zerodb_store_memory({
  content: "User prefers email support over phone",
  role: "user",
  session_id: "support-session-123",
  tags: ["preference", "communication"],
  user_id: "customer-456"
});

// Later, search across all sessions for this user
const prefs = await zerodb_search_memory({
  query: "communication preferences",
  scope: "agent",
  user_id: "customer-456"
});

Personal Assistant

// Store important facts
await zerodb_store_memory({
  content: "User's birthday is March 15th",
  role: "system",
  session_id: "assistant-123",
  tags: ["important", "permanent", "personal"],
  metadata: { category: "birthday" }
});

// Retrieve context before responding
const context = await zerodb_get_context({
  session_id: "assistant-123",
  max_tokens: 4096
});

Research Assistant

// Store findings
await zerodb_store_memory({
  content: "Study shows 85% efficacy in clinical trials",
  role: "assistant",
  session_id: "research-789",
  tags: ["research", "statistics"],
  metadata: { source: "Nature 2026", confidence: 0.9 }
});

// Search semantically
const related = await zerodb_semantic_search({
  text: "clinical trial results",
  limit: 5,
  min_similarity: 0.7
});

Performance

Context Footprint Comparison

Benchmarks

ZeroLocal (localhost:8000):

• Store memory: ~5ms
• Search memory: ~15ms
• Get context: ~20ms
• Embed text: ~10ms

ZeroDB Cloud (api.ainative.studio):

• Store memory: ~50ms
• Search memory: ~75ms
• Get context: ~100ms
• Embed text: ~60ms

Development

Run Tests

npm test

Run with Verbose Logging

DEBUG=* npm start

Development Mode (auto-reload)

npm run dev

Troubleshooting

Error: "Authentication failed"

Check:

• ZERODB_USERNAME and ZERODB_PASSWORD are correct
• Account exists in ZeroDB
• Password hasn't changed

Error: "Project not found"

Check:

• ZERODB_PROJECT_ID is correct
• Project exists in your account
• You have access permissions

Error: "Connection refused"

If using ZeroLocal:

# Check if ZeroLocal is running
curl http://localhost:8000/health

# Start ZeroLocal
cd /path/to/zerodb-local
zerodb local up

If using Cloud:

# Check internet connection
ping api.ainative.studio

# Verify API is online
curl https://api.ainative.studio/health

Memory not being pruned

Check configuration:

# Ensure context window is set
echo $CONTEXT_WINDOW

# Verify prune strategy
echo $PRUNE_STRATEGY

# Check if keep_recent is too high
echo $KEEP_RECENT

Architecture

┌─────────────────────────────────────────────┐
│         Agent Memory MCP Server             │
├─────────────────────────────────────────────┤
│                                             │
│  Main (index.js)                            │
│  └── MCP Server initialization              │
│                                             │
│  Client (zerodb-client.js)                  │
│  ├── Auto-detection (local vs cloud)       │
│  ├── Authentication & token refresh         │
│  └── API request handling                   │
│                                             │
│  Memory Manager (memory-manager.js)         │
│  ├── Context window management             │
│  ├── Memory pruning (relevance/recency)    │
│  ├── Importance scoring                     │
│  ├── Memory decay                           │
│  └── Automatic summarization                │
│                                             │
│  Tools (memory-tools.js)                    │
│  ├── zerodb_store_memory                   │
│  ├── zerodb_search_memory                  │
│  ├── zerodb_get_context                    │
│  ├── zerodb_embed_text                     │
│  ├── zerodb_semantic_search                │
│  └── zerodb_clear_session                  │
│                                             │
└─────────────────────────────────────────────┘

Roadmap

v1.1 (Planned)

• LLM-based automatic summarization
• Memory clustering and organization
• Export/import memory archives
• Memory analytics dashboard

v1.2 (Planned)

• Multi-agent memory sharing
• Memory permissions and access control
• Federated memory across instances
• Memory replication and backup

v2.0 (Future)

• Graph-based memory relationships
• Temporal memory queries
• Memory compression algorithms
• Real-time memory streaming

Contributing

Contributions welcome! Please read our contributing guidelines first.

License

MIT License - see LICENSE file for details

Support

• Documentation: https://www.ainative.studio/docs
• Issues: https://github.com/ainative/zerodb-memory-mcp/issues
• Discord: https://discord.gg/ainative

Built with by AINative Studio

Making AI agents smarter, one memory at a time.