# Memory MCP

> name: memory-mcp

- Skill: `clawdbot520/memory-mcp` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add clawdbot520/memory-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/clawdbot520/memory-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: clawdbot520 (https://skillmd.com/u/clawdbot520)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/clawdbot520/memory-mcp

---

name: memory-mcp
description: >
  MCP Server that exposes LanceDB Pro as shared memory tools for Claude Code.
  Provides remember/recall/list_facts/check_duplicate/forget — enabling instant
  read/write access to a shared knowledge base across multiple AI agents
  (Claude Code, OpenClaw, Antigravity) without waiting for distillation cycles.
  Use when you want any agent to instantly query or store memories mid-conversation.
---

# Memory MCP Server

Share long-term memory across AI agents via a MCP server backed by LanceDB Pro.

## What This Does

Wraps LanceDB Pro as 5 MCP tools so Claude Code (and other agents) can:
- **Instantly write** a memory without waiting for the Stop hook + distillation cycle
- **Instantly query** memories written by any agent (OpenClaw, Antigravity, Claude Code)
- **Deduplicate** before writing to prevent knowledge base pollution

## Architecture

```
Claude Code  ──┐
OpenClaw     ──┼──→  memory-mcp/server.py (MCP stdio)
Antigravity  ──┘              │
                              ▼
                   LanceDB Pro (local vector DB)
              ~/.openclaw/memory/lancedb-pro/
                              │
                    Jina AI Embeddings API
                (jina-embeddings-v5-text-small, 1024-dim)
```

## Prerequisites

1. **[memory-lancedb-pro](https://github.com/win4r/memory-lancedb-pro)** plugin installed in OpenClaw
   (provides the LanceDB Pro database and `memories` table)
2. **Python 3** with `lancedb` package: `pip3 install lancedb`
3. **JINA_API_KEY** — get a free key at [jina.ai](https://jina.ai)
4. **curl** available on PATH

## Installation

### 1. Copy server

```bash
cp server.py ~/.openclaw/skills/memory-mcp/server.py
chmod +x ~/.openclaw/skills/memory-mcp/server.py
```

### 2. Set environment variable

Add to your shell profile (`~/.zshrc` or `~/.bashrc`):

```bash
export JINA_API_KEY="your_jina_api_key_here"
```

Also add to your LaunchAgent plist if running as a background service:

```xml
<key>EnvironmentVariables</key>
<dict>
  <key>JINA_API_KEY</key>
  <string>your_jina_api_key_here</string>
</dict>
```

### 3. Register in Claude Code

Add to `~/.claude/claude.json`:

```json
{
  "mcpServers": {
    "memory-mcp": {
      "command": "python3",
      "args": ["/Users/YOUR_USERNAME/.openclaw/skills/memory-mcp/server.py"],
      "env": {
        "JINA_API_KEY": "your_jina_api_key_here"
      }
    }
  }
}
```

> Restart Claude Code after editing `claude.json`.

## Tools

### `remember(content, tags?, agent?, importance?)`

Write a memory to LanceDB. Automatically generates embedding via Jina AI.

```
content    — the memory text (required)
tags       — list of category tags, e.g. ["fact", "decision"]
agent      — scope identifier, e.g. "agent:claude-code" (required for correct display)
importance — 0.0–1.0, default 0.7
```

### `recall(query, top_k?, agent_filter?)`

Keyword search across all memories.

```
query        — search string (required)
top_k        — max results, default 5
agent_filter — restrict to a specific scope, e.g. "agent:antigravity"
```

### `list_facts(agent?, tag?)`

Exact-match filter list (not semantic search).

```
agent — filter by scope
tag   — filter by category tag
```

### `check_duplicate(content, threshold?)`

Check if a similar memory already exists before writing.

```
content   — text to check (required)
threshold — word-overlap ratio, default 0.90
```

Returns `{ "is_duplicate": bool, "similar": [...] }`. Duplicate detection warns but does not block — caller decides whether to proceed.

### `forget(memory_id)`

Delete a memory by ID.

## Scope Naming Convention

Use `agent:<id>` prefix for all agent-specific scopes:

| Scope | Agent |
|-------|-------|
| `agent:claude-code` | Claude Code |
| `agent:antigravity` | Antigravity |
| `agent:main` | OpenClaw main agent |
| `global` | Shared / distilled knowledge |

> **Important:** Scopes without `agent:` prefix (e.g. bare `"claude-code"`) will not appear in Agent Monitor's sidebar.

## Known Pitfalls

### ❌ Timestamp must be milliseconds

The `timestamp` field must be in **milliseconds** (Unix epoch × 1000), consistent with OpenClaw's format. Using `time.time()` (seconds) causes new memories to sort below all existing ones in Agent Monitor.

This server uses `time.time() * 1000` — do not change it.

### ❌ Never use zero vectors

Always call the Jina API for real embeddings. Zero vectors (`[0.0] * 1024`) make the memory invisible to vector search.

### ❌ Python urllib returns 403 from Jina

Use `curl` subprocess instead of `urllib`/`requests` for Jina API calls. This server does that by default.

## Complement to `claude-code-memory`

This skill works alongside (not instead of) the [claude-code-memory](../claude-code-memory/) skill:

| | claude-code-memory | memory-mcp |
|--|-------------------|------------|
| **When** | End of session (Stop hook) + hourly cron | Any time, mid-conversation |
| **Direction** | Session JSONL → distiller → LanceDB | Direct read/write |
| **Use case** | Background distillation | Instant agent-to-agent sharing |

## License

Apache 2.0