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.
- 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.
- Node.js ≥ 22
- A Supabase project (free tier works)
- An Anthropic API key for importance scoring and the dream cycle
git clone https://github.com/Israeltheminer/clude-mcp.git
cd clude-mcp
npm install
npm run buildCopy .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 memoryRun the clude-bot schema in your Supabase SQL editor to create the required tables and pgvector HNSW indexes.
The server communicates over stdio. Each tool needs a config entry pointing to the built binary.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"clude": {
"command": "node",
"args": ["/absolute/path/to/clude-mcp/dist/index.js"]
}
}
}// ~/.claude.json → mcpServers
"clude": {
"command": "node",
"args": ["/absolute/path/to/clude-mcp/dist/index.js"],
"type": "stdio"
}// ~/.cursor/mcp.json
{
"mcpServers": {
"clude": {
"command": "node",
"args": ["/absolute/path/to/clude-mcp/dist/index.js"]
}
}
}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
cludetools.
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| 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. |
| 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. |
| 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
| 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). |
| 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). |
| 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. |
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 |
| 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 |
| 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 |
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 |
# 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."# 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_memoriessrc/
├── 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
npm run dev # watch mode (tsx)
npm run lint # type-check only (tsc --noEmit)
npm run build # compile to dist/MIT