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 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
7. zerodb_synthesize_context
Retrieve and LLM-synthesize relevant memories into a coherent context string. Wraps POST /memory/v2/context. (Issue #2631)
Input:
{
"query": "What did we decide about the pricing model?",
"agent_id": "user-456",
"synthesis_style": "narrative",
"max_tokens": 1000,
"top_k": 10
}
Output:
{
"context": "In previous discussions, the team decided to use a usage-based pricing model...",
"synthesis_style": "narrative",
"sources_count": 5,
"confidence": 0.87,
"token_count": 312,
"agent_id": "user-456"
}
Features:
- Three synthesis styles:
narrative, bullet, structured
- Powered by Claude Haiku for fast, coherent summaries
- Graceful fallback if synthesis fails (concatenates top snippets)
- Scoped by
agent_id for per-user memory isolation
8. zerodb_configure_auto_context
Enable auto-context middleware so that relevant memories are automatically prepended to every tool response for a given agent. (Issue #2678)
Input:
{
"agent_id": "user-456",
"enabled": true,
"max_results": 10,
"synthesis_style": "bullet",
"auto_trace": false
}
Output:
{
"success": true,
"agent_id": "user-456",
"config": {
"enabled": true,
"max_results": 10,
"synthesis_style": "bullet",
"auto_trace": false
},
"message": "Auto-context enabled for agent user-456"
}
Features:
- Once enabled, every subsequent tool call for the
agent_id automatically prepends _auto_context to the response
auto_trace: true stores each tool response as a new episodic memory for future recall
- Config persisted via
/remember β survives MCP server restarts
- Skip list: config tools themselves are never auto-contexted
9. zerodb_get_auto_context_config
Retrieve the current auto-context configuration for an agent.
Input:
{
"agent_id": "user-456"
}
Output:
{
"agent_id": "user-456",
"config": {
"enabled": true,
"max_results": 10,
"synthesis_style": "bullet",
"auto_trace": false
}
}
Write-Back Action Tools
Five tools that write back to external services using OAuth tokens stored in ZeroDB sync connections. Connect accounts at /api/v1/public/memory/v2/connections.
Agent workflow: zerodb_recall β zerodb_synthesize_context β take action (send Slack, reply email, create event, etc.)
10. zerodb_slack_send
Send a Slack message using the user's stored OAuth token. (Issue #2645)
Input:
{
"agent_id": "user-456",
"channel": "C012AB3CD",
"message": "Sprint planning scheduled for Monday 10am",
"thread_ts": "1609459200.000100"
}
Output:
{
"ts": "1609459201.000200",
"channel": "C012AB3CD",
"message": "Message sent successfully"
}
Notes: thread_ts is optional β omit to post a new message, include to reply in a thread.