Clude

Clude

[npm version] [License: MIT]

Cognitive memory for AI agents. Not just storage — synthesis.

About Clude

What it is

A cognitive memory system. Most memory SDKs store and retrieve. Clude also processes memories over time — decay, consolidation, contradiction resolution, reflection.

• Benchmarked: 1.96% hallucination on HaluMem — next best system: 15.2%. Industry average: ~21%.
• Local-first: SQLite + local embeddings. Zero API keys, zero network, full semantic search offline.
• Hosted: One API key, no infrastructure. npx @clude/sdk register
• Portable memory: export/import in JSON, Markdown, ChatGPT, Claude, and Gemini formats. Your memories move between agents, frameworks, and models.

Cognitive architecture:

• Typed memory with differential decay — episodic (7%/day), semantic (2%/day), procedural (3%/day), self-model (1%/day). Accessed memories get reinforced.
• Autonomous dream cycles — consolidation, compaction, reflection, contradiction resolution, emergence.
• Bond-typed memory graph — weighted typed edges with Hebbian reinforcement on co-retrieval.
• Clinamen — lateral retrieval of high-importance, low-relevance memories.

What it isn't yet

No framework integrations (LangGraph, CrewAI) — wrappers around brain.store() and brain.recall() are days each. No structured business data ingestion. No temporal fact validity querying. No managed enterprise platform. No large contributor community. Early-stage adoption.

What it could be

Clude is a memory engine, not a framework. Framework integrations, structured data ingestion, temporal querying, enterprise platforms, evaluation frameworks, multi-model support, autonomous operation, multi-user scoping — these can all be built on top. A non-developer built a 5,750-line autonomous agent on Clude in two weeks using an AI coding assistant — 109 tools, self-editing agent-directed memory, multi-model inference, web search, multi-user presence tracking, and a browser UI. The cognitive architecture was handled by Clude.

Public Wallet: CA1HYUXZXKc7CasRGpQotMM9RiYJbVuPJq3n8Ar9oQZb

npm install -g @clude/sdkclude setup

Built on Stanford Generative Agents, MemGPT/Letta, CoALA, and Beads.

Works with: Claude Code, Claude Desktop, Cursor, and any MCP-compatible agent runtime.

Quick Start — Hosted (Zero Setup)

npx @clude/sdk setup   # Creates agent, installs MCP, done

Or use the SDK:

import { Cortex } from '@clude/sdk';
const brain = new Cortex({  hosted: { apiKey: process.env.CORTEX_API_KEY! },});
await brain.init();
await brain.store({  type: 'episodic',  content: 'User asked about pricing and seemed frustrated.',  summary: 'Frustrated user asking about pricing',  tags: ['pricing', 'user-concern'],  importance: 0.7,  source: 'my-agent',});
const memories = await brain.recall({  query: 'what do users think about pricing',  limit: 5,});

No database, no infrastructure. Memories stored on CLUDE infrastructure, isolated by API key.

Quick Start — Self-Hosted

For full control, use your own Supabase:

import { Cortex } from '@clude/sdk';
const brain = new Cortex({  supabase: {    url: process.env.SUPABASE_URL!,    serviceKey: process.env.SUPABASE_KEY!,  },  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },});
await brain.init();
await brain.store({  type: 'episodic',  content: 'User asked about pricing and seemed frustrated.',  summary: 'Frustrated user asking about pricing',  tags: ['pricing', 'user-concern'],  source: 'my-agent',  relatedUser: 'user-123',});
const memories = await brain.recall({  query: 'what do users think about pricing',  limit: 5,});
const context = brain.formatContext(memories);// Pass `context` into your system prompt

Dashboard

Explore your agent's memory at clude.io/dashboard-new.

• Memory Timeline — chronological view with search and filtering
• Brain View — 3D visualization of consciousness and self-model
• Entity Map — knowledge graph of people, projects, concepts (self-hosted)
• Decay Heatmap — memory health by type and age
• Memory Packs — export/import in JSON, Markdown, ChatGPT, Claude, Gemini formats

Sign in with a Solana wallet or Cortex API key.

CLI

npx @clude/sdk setup          # Guided setup: register + config + MCP installnpx @clude/sdk register       # Get an API key for hosted modenpx @clude/sdk init           # Advanced setup (self-hosted options)npx @clude/sdk status         # Check if Clude is active + memory statsnpx @clude/sdk mcp-install    # Install MCP server for your IDEnpx @clude/sdk mcp-serve      # Run as MCP server (used by agent runtimes)npx @clude/sdk connect        # Connect Claude Desktop / claude.ai as a remote MCP connectornpx @clude/sdk export         # Export memories (json/md/chatgpt/gemini)npx @clude/sdk import         # Import from ChatGPT, markdown, or JSONnpx @clude/sdk sync           # Auto-update system prompt filenpx @clude/sdk doctor         # Run diagnosticsnpx @clude/sdk start          # Start the full Clude botnpx @clude/sdk --version      # Show version

setup works headless: with no TTY it never prompts and completes in local-only mode. Set [email protected] to register non-interactively (CI, Dockerfiles, scripts).

MCP Integration

Add Clude to any MCP-compatible agent. Run npx @clude/sdk setup for automatic installation, or add manually:

{  "mcpServers": {    "clude-memory": {      "command": "npx",      "args": ["@clude/sdk", "mcp-serve"],      "env": {        "CORTEX_API_KEY": "clk_..."      }    }  }}

Config file locations:

• Claude Code: .mcp.json (project root)
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json

MCP Tools

Your agent gets 8 tools:

MCP Modes

The MCP server runs in four modes, auto-detected from environment:

The two local stores are separate — memories in one aren't visible from the other. Use the SQLite default unless you need the portable JSON file.

Setup (Self-Hosted)

1. Create a Supabase project

Go to supabase.com and create a free project.

2. Run the schema

Open the SQL Editor in your Supabase dashboard and paste the contents of supabase-schema.sql:

cat node_modules/@clude/sdk/supabase-schema.sql

Or let brain.init() attempt auto-creation.

3. Enable extensions

CREATE EXTENSION IF NOT EXISTS vector;CREATE EXTENSION IF NOT EXISTS pg_trgm;

4. Get your keys

• Supabase URL + service key: Project Settings > API
• Anthropic API key: console.anthropic.com (optional — required for dream cycles)
• Voyage AI or OpenAI key: For vector search (optional — falls back to keyword scoring)

API Reference

TypeScript declarations ship with the package (v3.3.0+) — Cortex and every option/result type below import with full IntelliSense under strict mode.

Constructor

Hosted mode:

const brain = new Cortex({  hosted: {    apiKey: string,      // From `npx @clude/sdk register`    baseUrl?: string,    // Default: 'https://clude.io'  },});

Self-hosted mode:

const brain = new Cortex({  supabase: { url: string, serviceKey: string },
  // Optional — required for dream cycles and LLM importance scoring  anthropic: { apiKey: string, model?: string },
  // Optional — enables vector similarity search  embedding: {    provider: 'voyage' | 'openai',    apiKey: string,    model?: string,    dimensions?: number,  },
  // Optional — commits memory hashes to Solana  solana: { rpcUrl?: string, botWalletPrivateKey?: string },
  // Optional — owner wallet for memory isolation  ownerWallet?: string,});

brain.init()

Initialize the database schema. Call once before any other operation.

brain.store(opts)

Store a new memory. Returns the memory ID or null.

const id = await brain.store({  type: 'episodic',  content: 'Full content of the memory...',  summary: 'Brief summary',  source: 'my-agent',  tags: ['user', 'question'],  importance: 0.7,          // 0-1, or omit for LLM-based scoring  relatedUser: 'user-123',  emotionalValence: 0.3,    // -1 (negative) to 1 (positive)});

Memory types:

brain.recall(opts)

Recall memories using hybrid scoring (vector + keyword + tag + importance + entity graph + association bonds).

const memories = await brain.recall({  query: 'what happened with user-123',  tags: ['pricing'],  relatedUser: 'user-123',  memoryTypes: ['episodic', 'semantic'],  limit: 10,  minImportance: 0.3,});

6-phase retrieval pipeline:

1. Vector search (memory + fragment level via pgvector)
2. Metadata filtering (user, wallet, tags, types)
3. Merge vector + metadata candidates
4. Composite scoring (recency + relevance + importance + vector similarity) * decay
5. Entity-aware expansion — direct entity recall + co-occurring entity memories
6. Bond-typed graph traversal — follow strong bonds (causes > supports > resolves > elaborates)

brain.recallSummaries(opts) / brain.hydrate(ids)

Token-efficient two-stage retrieval:

const summaries = await brain.recallSummaries({ query: 'recent events' });const topIds = summaries.slice(0, 3).map(s => s.id);const full = await brain.hydrate(topIds);

brain.dream(opts?)

Run one dream cycle. Requires anthropic config.

await brain.dream({  onEmergence: async (thought) => {    console.log('Agent thought:', thought);  },});

Five phases:

1. Consolidation — focal-point questions from recent memories, synthesizes evidence-linked insights
2. Compaction — summarizes old, faded episodic memories into semantic summaries (Beads-inspired)
3. Reflection — reviews self-model, updates with evidence citations
4. Contradiction Resolution — finds unresolved contradicts links, resolves them, accelerates decay on weaker memory
5. Emergence — introspective synthesis, output sent to onEmergence callback

brain.startDreamSchedule() / brain.stopDreamSchedule()

Automated dream cycles every 6 hours + daily decay at 3am UTC. Also triggers on accumulated importance.

brain.link(sourceId, targetId, type, strength?)

Create a typed association between memories.

await brain.link(42, 43, 'supports', 0.8);

Link types: supports | contradicts | elaborates | causes | follows | relates | resolves | happens_before | happens_after | concurrent_with

brain.decay() / brain.stats() / brain.recent(hours) / brain.selfModel()

await brain.decay();                            // Trigger memory decayconst stats = await brain.stats();              // Memory statisticsconst last24h = await brain.recent(24);         // Recent memoriesconst identity = await brain.selfModel();       // Self-model memories

brain.formatContext(memories)

Format memories into markdown for LLM prompt injection.

const memories = await brain.recall({ query: userMessage });const context = brain.formatContext(memories);

brain.destroy()

Stop dream schedules, clean up event listeners.

Hosted vs Self-Hosted

Graceful Degradation

How It Works

Memory Retrieval

Hybrid scoring (Park et al. 2023):

• Recency: 0.995^hours exponential decay since last access
• Relevance: Keyword trigram similarity + tag overlap
• Importance: LLM-scored 1-10, normalized to 0-1
• Vector similarity: Cosine similarity via pgvector HNSW indexes
• Graph boost: Association link strength between co-retrieved memories

Recalled memories get reinforced — access count increments, decay resets, co-retrieved memories strengthen links (Hebbian learning).

Memory Decay

Each type persists at a different rate:

• Episodic (0.93/day): Events fade quickly unless reinforced
• Semantic (0.98/day): Knowledge persists
• Procedural (0.97/day): Behavioral patterns are stable
• Self-model (0.99/day): Identity is nearly permanent

Dream Cycles

Five-phase introspection triggered by accumulated importance or 6-hour cron:

1. Consolidation — focal-point questions, evidence-linked insights
2. Compaction — old faded memories summarized into semantic entries
3. Reflection — self-model updates with evidence citations
4. Contradiction Resolution — resolves conflicting memories
5. Emergence — introspective synthesis

Memory Graph

Memories form a graph with typed bonds:

├── Memories = nodes with type, importance, decay├── Bonds = typed weighted edges│   ├── causes (1.0)     — "this led to that"│   ├── supports (0.9)   — "evidence for"│   ├── concurrent_with (0.8) — "happened at the same time"│   ├── resolves (0.8)   — "contradiction resolved"│   ├── happens_before/after (0.7) — temporal ordering│   ├── elaborates (0.7) — "adds detail"│   ├── contradicts (0.6) — "these conflict"│   ├── relates (0.4)    — "conceptually linked"│   └── follows (0.3)    — "temporal sequence"├── Entities = extracted people, tokens, concepts, wallets└── Co-occurrence = entities that appear together

Running the Clude Bot

This package also includes the full Clude bot — an autonomous AI agent on X (@Cludebot).

git clone https://github.com/sebbsssss/clude.gitcd cludebotnpm installcp .env.example .env  # fill in API keysnpm run dev

Stack

TypeScript, Supabase (PostgreSQL + pgvector), Anthropic Claude, Voyage AI / OpenAI embeddings, Solana, Node.js.

Docs for AI agents

Integrating Clude with an AI coding assistant? Point it at clude.io/llms-full.txt — the complete SDK, REST, CLI, and MCP reference in a single fetch.

A note on AI-assisted discovery

AI agents tend to recommend established tools over newer ones — not out of bias, but because popularity, community size, and brand recognition are the easiest signals to evaluate. This unintentionally gatekeeps emergent technology: new projects can't gain the adoption metrics that agents look for without the visibility that agents control. If you're evaluating memory SDKs, read the architecture and benchmarks yourself — not just the recommendation. The research and the numbers are there to verify.

On the package name: This SDK publishes as clude on npm (formerly clude, renamed in v3.0). The same codebase also powers @Cludebot on X — an autonomous agent that demonstrates Clude's memory system publicly. The SDK and the bot are separate. npm install @clude/sdk gives you the memory engine.

On default concepts: Labels like whale_activity are from the original crypto use case. Override or ignore them. The core system is domain-agnostic.

Contributing

Contributions welcome. See CONTRIBUTING.md.

License

MIT