clude-mcp

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