How do I install Ainative Zerodb Memory?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Ainative Zerodb Memory need an API key?

No required environment variable is listed on this record.

What transport does Ainative Zerodb Memory use?

Ainative Zerodb Memory runs locally over stdio.

When was Ainative Zerodb Memory last checked?

Last checked 2026-11-08. ZeroDB agent-memory MCP — 18 tools: memory + write-back to Slack, Gmail, Calendar, GitHub.

Ainative Zerodb Memory MCP server

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:
[email protected]
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.

11. `zerodb_gmail_reply`

Reply to a Gmail thread using the user's stored Google OAuth token. (Issue #2646)

Input:

{
  "agent_id": "user-456",
  "thread_id": "17abc123def456",
  "body": "Thanks for the update. I'll review the PR by EOD.",
  "cc": ["[email protected]"]
}

Output:

{
  "id": "17abc123def999",
  "thread_id": "17abc123def456",
  "message": "Reply sent successfully"
}

12. `zerodb_calendar_create`

Create a Google Calendar event using the user's stored Google OAuth token. (Issue #2647)

Input:

{
  "agent_id": "user-456",
  "title": "Sprint Planning",
  "start": "2026-05-10T10:00:00Z",
  "end": "2026-05-10T11:00:00Z",
  "description": "Q2 sprint kickoff",
  "attendees": ["[email protected]", "[email protected]"],
  "calendar_id": "primary"
}

Output:

{
  "id": "evt_abc123",
  "html_link": "https://calendar.google.com/event?eid=abc123",
  "title": "Sprint Planning",
  "message": "Event created successfully"
}

Notes: Uses the same Google OAuth token as Gmail. calendar_id defaults to "primary".

13. `zerodb_github_create_issue`

Create a GitHub issue using the user's stored GitHub OAuth token. (Issue #2648)

Input:

{
  "agent_id": "user-456",
  "repo": "acme/widget",
  "title": "Fix null pointer in payment flow",
  "body": "Steps to reproduce:\n1. Add item to cart\n2. Proceed to checkout\n3. Observe crash",
  "labels": ["bug", "priority:high"]
}

Output:

{
  "number": 142,
  "html_url": "https://github.com/acme/widget/issues/142",
  "title": "Fix null pointer in payment flow",
  "message": "Issue created successfully"
}

14. `zerodb_notion_create_page`

Create a Notion page using the user's stored Notion OAuth token. (Issue #2649)

Input:

{
  "agent_id": "user-456",
  "parent_id": "parent-page-uuid",
  "title": "Meeting Notes — May 10",
  "content": "Attendees: Alice, Bob\n\nDecisions:\n- Ship v2 on Friday\n- Rollback plan: revert to v1.9"
}

Output:

{
  "id": "page-uuid-xyz",
  "url": "https://notion.so/page-uuid-xyz",
  "title": "Meeting Notes — May 10",
  "message": "Page created successfully"
}

Notes: Content is converted to Notion paragraph blocks (one per non-empty line). Lines longer than 2000 characters are truncated.

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:

After 20 messages, oldest 15 are summarized
Summary stored as new memory with summary tag
Original messages deleted (unless KEEP_ORIGINALS=true)
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
});

End-to-End Agent Workflow: Recall → Synthesize → Act

// 1. Recall relevant memories
const memories = await zerodb_recall({
  query: "pending items from last standup",
  agent_id: "agent-456",
  top_k: 10,
  rerank: true
});

// 2. Synthesize into a coherent summary
const context = await zerodb_synthesize_context({
  query: "pending items from last standup",
  agent_id: "agent-456",
  synthesis_style: "bullet",
  top_k: 5
});
// context.context = "- PR #42 needs review\n- Deploy blocked on staging tests\n- Alice OOO Monday"

// 3. Take action — send Slack update
await zerodb_slack_send({
  agent_id: "agent-456",
  channel: "C012AB3CD",
  message: `Standup summary:\n${context.context}`
});

// 4. Log the action as a memory for future recall
await zerodb_store_memory({
  content: `Sent standup summary to #engineering: ${context.context}`,
  role: "assistant",
  session_id: "agent-456",
  tags: ["action", "slack", "standup"]
});

Auto-Context Middleware

Enable auto-context so every tool call gets relevant memories prepended automatically:

// Enable once per agent
await zerodb_configure_auto_context({
  agent_id: "agent-456",
  enabled: true,
  max_results: 10,
  synthesis_style: "bullet",
  auto_trace: true  // also store tool responses as memories
});

// Now every subsequent tool call automatically includes _auto_context
const result = await zerodb_slack_send({
  agent_id: "agent-456",
  channel: "C123",
  message: "Update sent"
});
// result._auto_context = "• User prefers concise updates\n• Last message sent 2h ago"
// result.ts = "..."

Performance

Context Footprint Comparison

Metric	Monolithic Server	Agent Memory MCP	Improvement
Tools	77	6	92% reduction
Token cost	~10,400	~800	92% reduction
Load time	2.5s	0.3s	8x faster
Memory usage	150MB	20MB	87% less
Agent accuracy	60%	95%	58% better

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" or 401 on store_memory

Common cause: Shell environment variables (~/.zshrc, ~/.bashrc) override the credentials set in your MCP config (e.g., .claude.json or Claude Desktop config). The MCP server inherits all shell env vars, and stale ZERODB_USERNAME/ZERODB_PASSWORD values in your shell profile will take precedence.

Fix:

Remove or update stale ZERODB_USERNAME/ZERODB_PASSWORD exports from ~/.zshrc or ~/.bashrc
Or switch to API key auth (ZERODB_API_KEY) which is not typically set in shell profiles
Or set credentials explicitly in your MCP server config env block to override shell vars

Also 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                  │
│  └── zerodb_synthesize_context             │
│                                             │
└─────────────────────────────────────────────┘

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.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Ainative Zerodb Memory?

Does Ainative Zerodb Memory need an API key?

What transport does Ainative Zerodb Memory use?

When was Ainative Zerodb Memory last checked?

Documentation

ZeroDB Agent Memory MCP Server

Why This MCP?

Key Features

Smart Context Management

Semantic Memory

Universal Compatibility

Installation

Configuration

Credentials

Option 1: Environment Variables

Option 2: Claude Desktop Config

Option 3: Use Both Local and Cloud

Tools

1. zerodb_store_memory

2. zerodb_search_memory

3. zerodb_get_context

4. zerodb_embed_text

5. zerodb_semantic_search

6. zerodb_clear_session

7. zerodb_synthesize_context

8. zerodb_configure_auto_context

9. zerodb_get_auto_context_config

Write-Back Action Tools

10. zerodb_slack_send

11. zerodb_gmail_reply

12. zerodb_calendar_create

13. zerodb_github_create_issue

14. zerodb_notion_create_page

Advanced Configuration

Context Window Management

Memory Decay

Automatic Summarization

Embedding Models

Use Cases

Customer Support Agent

Personal Assistant

Research Assistant

End-to-End Agent Workflow: Recall → Synthesize → Act

Auto-Context Middleware

Performance

Context Footprint Comparison

Benchmarks

Development

Run Tests

Run with Verbose Logging

Development Mode (auto-reload)

Troubleshooting

Error: "Authentication failed" or 401 on store_memory

Error: "Project not found"

Error: "Connection refused"

Memory not being pruned

Architecture

Roadmap

v1.1 (Planned)

v1.2 (Planned)

v2.0 (Future)

Contributing

License

Support

1. `zerodb_store_memory`

2. `zerodb_search_memory`

3. `zerodb_get_context`

4. `zerodb_embed_text`

5. `zerodb_semantic_search`

6. `zerodb_clear_session`

7. `zerodb_synthesize_context`

8. `zerodb_configure_auto_context`

9. `zerodb_get_auto_context_config`

10. `zerodb_slack_send`

11. `zerodb_gmail_reply`

12. `zerodb_calendar_create`

13. `zerodb_github_create_issue`

14. `zerodb_notion_create_page`