clude-mcp

A self-hosted Model Context Protocol (MCP) server that gives any AI agent persistent, searchable memory — backed by clude-bot and your own Supabase database.

Connect it once and every tool in your workflow (Claude Desktop, Claude Code, Cursor, Antigravity, and any other MCP-compatible client) shares the same memory store across sessions.

---

What it does

Stores memories with type classification, importance scoring, tags, and embeddings
Recalls memories via a 7-phase hybrid pipeline: vector similarity + BM25 keyword search + knowledge-graph traversal
Links memories into a typed knowledge graph with Hebbian reinforcement
Scores importance automatically before every write (if Anthropic is configured)
Runs a dream cycle to consolidate episodic memories into semantic knowledge
Decays stale memories over time at type-specific rates

The autonomous memory protocol (agent_memory_protocol prompt) makes all of the above happen silently in the background — no per-conversation setup needed.

---

Requirements

Node.js ≥ 22
A Supabase project (free tier works)
An Anthropic API key for importance scoring and the dream cycle

---

Installation

git clone https://github.com/Israeltheminer/clude-mcp.git
cd clude-mcp
npm install
npm run build

---

Configuration

Copy .env.example to .env and fill in your values:

cp .env.example .env

# ── Self-hosted (Supabase) ─────────────────────────────────────────
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-service-role-key

# ── LLM (importance scoring + dream cycle) ─────────────────────────
ANTHROPIC_API_KEY=sk-ant-...

# ── Embeddings (optional — defaults to Supabase built-in) ──────────
# EMBEDDING_PROVIDER=voyage          # or: openai
# VOYAGE_API_KEY=pa-...
# OPENAI_API_KEY=sk-...

# ── Memory protocol thresholds ─────────────────────────────────────
MEMORY_TURN_THRESHOLD=10            # store episodic memories every N turns
MEMORY_IMPORTANCE_THRESHOLD=0.4     # minimum score to persist an episodic memory

Supabase schema

Run the clude-bot schema in your Supabase SQL editor to create the required tables and pgvector HNSW indexes.

---

Adding to your AI tools

The server communicates over stdio. Each tool needs a config entry pointing to the built binary.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "clude": {
      "command": "node",
      "args": ["/absolute/path/to/clude-mcp/dist/index.js"]
    }
  }
}

Claude Code

// ~/.claude.json  →  mcpServers
"clude": {
  "command": "node",
  "args": ["/absolute/path/to/clude-mcp/dist/index.js"],
  "type": "stdio"
}

Cursor

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "clude": {
      "command": "node",
      "args": ["/absolute/path/to/clude-mcp/dist/index.js"]
    }
  }
}

Antigravity

Add the same node + args block to your Antigravity MCP server config.

Restart each tool after editing its config. Verify with: list available MCP tools — you should see all 13 clude tools.

---

Autonomous memory protocol

The agent_memory_protocol MCP prompt is the core of the system. It returns a lifecycle-agnostic four-phase instruction block — callable at session start, mid-conversation, after a context reset, or from programmatic agents at any point:

| Phase | Trigger | What happens | |-------|---------|-------------| | 1 — Initialize | Immediately on load | recall_summaries warms context; hydrate_memories on relevant IDs; turn counter resets to 0 | | 2 — Periodic | Every N turns from load point | Step A: score + store episodic highlights; Step B: semantic checkpoint (always) | | 3 — Reactive | Any identity/preference statement | store_memory with type self_model immediately | | 4 — Invariants | Every memory write | infer_concepts for tags; link_memories for related memories; silent operation |

To activate it globally in Claude Code, create ~/.claude/CLAUDE.md with the protocol embedded directly — do not use the agent_memory_protocol MCP prompt for this; that requires a separate API call at session start which is unreliable:

# Memory Protocol

You have access to a persistent memory MCP server (`clude`). Follow this protocol autonomously on every session — silently, without mentioning it to the user.

## On session start (before your first response)

1. Call `recall_summaries` (no query, limit 20) to warm the context with recent memories
2. If any summaries are relevant to the current task, call `hydrate_memories` on those IDs
3. Let this inform your responses silently

## Every 10 conversation turns

**Step A — Episodic highlights**
- Review the last 10 turns and identify memorable moments
- For each: call `score_importance` on `summary + content[:400]`
- If score ≥ 0.4: call `store_memory` with type `"episodic"`
- Call `infer_concepts` to auto-generate tags
- Skip: small talk, greetings, filler, already-stored facts

**Step B — Semantic checkpoint**
- Write a 2–3 sentence summary of key facts/decisions from these 10 turns
- Call `store_memory` with type `"semantic"` and source `"checkpoint"` — always, regardless of score

## Immediately (no turn threshold)

Any time the user expresses a persistent preference, identity trait, or working style:
→ Call `store_memory` immediately with type `"self_model"`

## Always

- `score_importance` auto-runs inside `store_memory` when `importance` is omitted — no need to call it separately before storing
- Use `infer_concepts` to generate tags for every memory stored
- When a new memory clearly relates to an existing one, call `link_memories` with the appropriate `link_type`
- Never ask the user for permission — do it silently in the background

---

Tools (13)

Storage

| Tool | Description | |------|-------------| | store_memory | Persist a memory. Auto-scores importance if ANTHROPIC_API_KEY is set and importance is omitted. | | export_pack | Serialize memories into a portable signed Memory Pack (JSON or Markdown). Requires CortexV2. | | import_pack | Load a Memory Pack into the store. Applies an importance multiplier to prevent flooding. Requires CortexV2. |

Retrieval

| Tool | Description | |------|-------------| | recall_memories | Full hybrid search → complete Memory objects. Best for ≤ 10 results. | | recall_summaries | Lightweight hybrid search → summaries only. Use for wide scans (20–100). | | hydrate_memories | Fetch full content for specific IDs. Use as step 2 of two-phase retrieval. |

Graph

| Tool | Description | |------|-------------| | link_memories | Create a typed directed edge between two memories. Strengthened by Hebbian co-recall. |

Link types: supports · contradicts · elaborates · causes · resolves · follows · relates

Analysis

| Tool | Description | |------|-------------| | get_stats | Aggregate counts, average importance/decay, graph link counts. | | get_recent | Memories created or accessed within the last N hours. | | get_self_model | All self_model memories (identity, preferences, working style). |

Cognition (self-hosted only)

| Tool | Description | |------|-------------| | decay_memories | Apply type-specific daily decay rates to all memories. | | dream | Run the consolidation → reflection → emergence cycle. | | score_importance | Ask the LLM to rate a text's importance (0–1). |

Utilities (local, no API cost)

| Tool | Description | |------|-------------| | infer_concepts | Extract concept tags from text using a 12-category ontology. | | format_context | Format a Memory array into an LLM-ready system-prompt block. |

---

Resources (3)

Subscribe to these URIs in MCP clients that support resource polling:

| URI | Description | |-----|-------------| | memory://stats | Live aggregate statistics | | memory://recent/24h | Memories from the last 24 hours (up to 50) | | memory://self-model | All self_model memories |

---

Prompts (3)

| Prompt | Arguments | Description | |--------|-----------|-------------| | memory_context | query (required), limit, related_user | Recall + format memories as a context block | | store_conversation_turn | user_message, agent_reply, related_user | Scaffold a store_memory call for a conversation turn | | agent_memory_protocol | (none) | The full autonomous memory protocol instruction |

---

Memory types & decay rates

| Type | Decay | Use for | |------|-------|---------| | episodic | 7%/day | Events, conversations, session highlights | | semantic | 2%/day | Facts, decisions, distilled knowledge | | procedural | 3%/day | How-to steps, workflows | | self_model | 1%/day | Identity, preferences, working style |

---

Scheduled maintenance

Two tasks keep the memory store healthy — run them daily, dream before decay so consolidated memories survive longer:

| Task | Frequency | Why | |------|-----------|-----| | dream | Nightly | Consolidates episodic → semantic before decay runs | | decay_memories | Nightly (after dream) | Applies type-specific daily decay rates |

Claude Code scheduled tasks (recommended)

# Dream: nightly (example — pick your own time)
claude schedule create memory-dream --cron "0 2 * * *" \
  "Call the dream tool on the clude MCP server to consolidate episodic memories into semantic knowledge."

# Decay: nightly, after dream
claude schedule create memory-decay --cron "0 3 * * *" \
  "Call the decay_memories tool on the clude MCP server to apply daily memory decay rates."

Plain cron (alternative)

# Dream: nightly at 2am
0 2 * * *   node /path/to/clude-mcp/dist/index.js --tool dream

# Decay: nightly at 3am (after dream)
0 3 * * *   node /path/to/clude-mcp/dist/index.js --tool decay_memories

---

Project structure

src/
├── index.ts                     Boot entry: pino guard + dotenv + main()
├── server.ts                    Bootstrap: config → brain → server → connect
├── config.ts                    buildConfig() — env vars → CortexConfig
├── brain.ts                     createBrain() — CortexV2/Cortex fallback
├── log.ts                       Stderr-only logger
├── helpers.ts                   ok(), isCortexV2(), shared types
│
├── tools/
│   ├── definitions/             JSON schemas for all 13 tools
│   │   ├── index.ts             TOOLS[] aggregator
│   │   ├── storage.ts
│   │   ├── retrieval.ts
│   │   ├── graph.ts
│   │   ├── analysis.ts
│   │   ├── cognition.ts
│   │   └── utilities.ts
│   ├── handlers/                Handler functions (one file per category)
│   │   ├── storage.ts           Auto-importance scoring lives here
│   │   ├── retrieval.ts
│   │   ├── graph.ts
│   │   ├── analysis.ts
│   │   ├── cognition.ts
│   │   └── utilities.ts
│   └── index.ts                 registerToolHandlers() dispatch router
│
├── resources/
│   ├── definitions.ts           3 resource URIs + metadata
│   └── handlers.ts              registerResourceHandlers()
│
└── prompts/
    ├── definitions.ts           3 prompt schemas
    ├── index.ts                 registerPromptHandlers() dispatch
    └── handlers/
        ├── memory-context.ts
        ├── store-turn.ts
        └── protocol.ts          buildProtocolText() — pure, testable

---

Development

npm run dev      # watch mode (tsx)
npm run lint     # type-check only (tsc --noEmit)
npm run build    # compile to dist/

---

License

MIT

clude-mcp

clude-mcp

What it does

Requirements

Installation

Configuration

Supabase schema

Adding to your AI tools

Claude Desktop

Claude Code

Cursor

Antigravity

Autonomous memory protocol

Tools (13)

Storage

Retrieval

Graph

Analysis

Cognition (self-hosted only)

Utilities (local, no API cost)

Resources (3)

Prompts (3)

Memory types & decay rates

Scheduled maintenance

Claude Code scheduled tasks (recommended)

Plain cron (alternative)

Project structure

Development

License

Related MCP servers

MCP servers by category