Ainative Zerodb Memory MCP

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.

---

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": ["manager@example.com"] }

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": ["alice@example.com", "bob@example.com"], "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-