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

```bash
# 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

```bash
# 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

```bash
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

```json
{
  "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

```json
{
  "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:**
```json
{
  "content": "User prefers technical explanations over simplified ones",
  "role": "system",
  "session_id": "chat-123",
  "tags": ["preference", "important"],
  "user_id": "user-456"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "query": "What are the user's dietary restrictions?",
  "limit": 10,
  "session_id": "chat-123",
  "scope": "agent",
  "min_importance": 0.5
}
```

**Output:**
```json
{
  "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:**
```json
{
  "session_id": "chat-123",
  "max_tokens": 8192,
  "include_stats": true
}
```

**Output:**
```json
{
  "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:**
```json
{
  "text": "The quick brown fox jumps over the lazy dog",
  "model": "BAAI/bge-small-en-v1.5",
  "normalize": true
}
```

**Output:**
```json
{
  "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:**
```json
{
  "text": "food preferences",
  "limit": 10,
  "session_id": "chat-123",
  "min_similarity": 0.7
}
```

**Output:**
```json
{
  "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:**
```json
{
  "session_id": "chat-123",
  "keep_important": true,
  "confirm": true
}
```

**Output:**
```json
{
  "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:**
```json
{
  "query": "What did we decide about the pricing model?",
  "agent_id": "user-456",
  "synthesis_style": "narrative",
  "max_tokens": 1000,
  "top_k": 10
}
```

**Output:**
```json
{
  "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:**
```json
{
  "agent_id": "user-456",
  "enabled": true,
  "max_results": 10,
  "synthesis_style": "bullet",
  "auto_trace": false
}
```

**Output:**
```json
{
  "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:**
```json
{
  "agent_id": "user-456"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "agent_id": "user-456",
  "channel": "C012AB3CD",
  "message": "Sprint planning scheduled for Monday 10am",
  "thread_ts": "1609459200.000100"
}
```

**Output:**
```json
{
  "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.

--