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
Focused server with 14 tools consuming ~1,400 tokens
in context footprint, faster agent decisions, better accuracy
ZeroDB agent-memory MCP — 18 tools: memory + write-back to Slack, Gmail, Calendar, GitHub.
2026-11-14
Yıldızlar
—
Araçlar
—
Çalışma süresi
—
After:
Result:
87% reduction
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
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.
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)
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.
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
});
// 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
Henüz araç listesi yok. Uzak sunucular ilk sağlık kontrolünden sonra bir liste alır.
SSS
Sorular
Ainative Zerodb Memory nasıl kurulur?
Bu sayfadan Cursor, Claude Desktop, Claude Code veya VS Code için stdio yapılandırmasını kopyalayın. PlugMCP proxy'sini değil, yayıncının kurulumunu kullanır.
Ainative Zerodb Memory için API anahtarı gerekiyor mu?
Bu kayıtta gerekli bir ortam değişkeni listelenmiyor.
Ainative Zerodb Memory hangi aktarımı kullanıyor?
Ainative Zerodb Memory yerel olarak stdio üzerinden çalışır.
Ainative Zerodb Memory en son ne zaman kontrol edildi?
Son kontrol: 2026-11-14. ZeroDB agent-memory MCP — 18 tools: memory + write-back to Slack, Gmail, Calendar, GitHub.