Clude

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/sdk
clude 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 install
npx @clude/sdk register       # Get an API key for hosted mode
npx @clude/sdk init           # Advanced setup (self-hosted options)
npx @clude/sdk status         # Check if Clude is active + memory stats
npx @clude/sdk mcp-install    # Install MCP server for your IDE
npx @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 connector
npx @clude/sdk export         # Export memories (json/md/chatgpt/gemini)
npx @clude/sdk import         # Import from ChatGPT, markdown, or JSON
npx @clude/sdk sync           # Auto-update system prompt file
npx @clude/sdk doctor         # Run diagnostics
npx @clude/sdk start          # Start the full Clude bot
npx @clude/sdk --version      # Show version

setup works headless: with no TTY it never prompts and completes in local-only mode. Set CLUDE_SETUP_EMAIL=you@example.com 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:

Tool	Description
`recall_memories`	Search memories with hybrid scoring (vector + keyword + tags + importance)
`store_memory`	Store a new memory with type, content, summary, tags, importance
`batch_store_memories`	Store up to 50 memories in a single call
`list_memories`	Browse without a query — paginated, sorted by recency, importance, or last access
`update_memory`	Update fields of an existing memory by ID
`delete_memory`	Permanently delete a memory by ID
`get_memory_stats`	Memory statistics — counts by type, avg importance/decay, top tags
`find_clinamen`	Anomaly retrieval — find high-importance memories with low relevance to current context

MCP Modes

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

Mode	Config	Storage
Hosted	`CORTEX_API_KEY`	clude.io (zero setup)
Self-hosted	`SUPABASE_URL` + `SUPABASE_SERVICE_KEY`	Your Supabase
Local SQLite (default)	none — what `setup` creates	`~/.clude/brain.db` (local embeddings, fully offline)
Local JSON	`--local` flag or `CLUDE_LOCAL=true`	`~/.clude/memories.json` (portable single file)

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:

Type	Decay/day	Use for
`episodic`	7%	Raw interactions, conversations, events
`semantic`	2%	Learned knowledge, patterns, insights
`procedural`	3%	Behavioral rules, what works/doesn't
`self_model`	1%	Identity, self-understanding
`introspective`	2%	Journal entries, dream cycle outputs

`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:

Vector search (memory + fragment level via pgvector)
Metadata filtering (user, wallet, tags, types)
Merge vector + metadata candidates
Composite scoring (recency + relevance + importance + vector similarity) * decay
Entity-aware expansion — direct entity recall + co-occurring entity memories
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:

Consolidation — focal-point questions from recent memories, synthesizes evidence-linked insights
Compaction — summarizes old, faded episodic memories into semantic summaries (Beads-inspired)
Reflection — reviews self-model, updates with evidence citations
Contradiction Resolution — finds unresolved contradicts links, resolves them, accelerates decay on weaker memory
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);

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

await brain.decay();                            // Trigger memory decay
const stats = await brain.stats();              // Memory statistics
const last24h = await brain.recent(24);         // Recent memories
const 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

	Hosted	Self-Hosted
Setup	Just an API key	Your own Supabase
store / recall / stats	Yes	Yes
Dream cycles	No	Yes (requires Anthropic)
Entity graph	No	Yes
Memory packs	No	Yes
Embeddings	Managed	Configurable (Voyage/OpenAI)
On-chain commits	No	Yes (Solana)
Dashboard	Yes (API key login)	Yes (wallet login)

Graceful Degradation

Feature	Without it
`anthropic` not set	LLM importance scoring falls back to rules. `dream()` throws.
`embedding` not set	Vector search disabled, recall uses keyword + tag scoring only.
`solana` not set	On-chain memory commits silently skipped.

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:

Consolidation — focal-point questions, evidence-linked insights
Compaction — old faded memories summarized into semantic entries
Reflection — self-model updates with evidence citations
Contradiction Resolution — resolves conflicting memories
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.git
cd cludebot
npm install
cp .env.example .env  # fill in API keys
npm 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

Name		Name	Last commit message	Last commit date
.github		.github
.paperclip/logs		.paperclip/logs
.usage-report-cache		.usage-report-cache
apps		apps
benchmarks/longmemeval-s		benchmarks/longmemeval-s
contracts/base		contracts/base
docs		docs
infra/gcp		infra/gcp
misc		misc
packages		packages
programs/memory-registry		programs/memory-registry
scripts		scripts
video		video
.DS_Store		.DS_Store
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.redeploy		.redeploy
AGENTS.md		AGENTS.md
Anchor.toml		Anchor.toml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.mcp		Dockerfile.mcp
LICENSE		LICENSE
README.md		README.md
README.npm.md		README.npm.md
SKILL.md		SKILL.md
clude-memories.json		clude-memories.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
railway.toml		railway.toml
server.json		server.json
test-memory-pack.json		test-memory-pack.json
turbo.json		turbo.json

Latest commit

History

Folders and files

Repository files navigation

Clude

About Clude

What it is

What it isn't yet

What it could be

Quick Start — Hosted (Zero Setup)

Quick Start — Self-Hosted

Dashboard

CLI

MCP Integration

MCP Tools

MCP Modes

Setup (Self-Hosted)

1. Create a Supabase project

2. Run the schema

3. Enable extensions

4. Get your keys

API Reference

Constructor

brain.init()

brain.store(opts)

brain.recall(opts)

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

brain.dream(opts?)

brain.startDreamSchedule() / brain.stopDreamSchedule()

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

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

brain.formatContext(memories)

brain.destroy()

Hosted vs Self-Hosted

Graceful Degradation

How It Works

Memory Retrieval

Memory Decay

Dream Cycles

Memory Graph

Running the Clude Bot

Stack

Docs for AI agents

A note on AI-assisted discovery

Contributing

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`brain.init()`

`brain.store(opts)`

`brain.recall(opts)`

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

`brain.dream(opts?)`

`brain.startDreamSchedule()` / `brain.stopDreamSchedule()`

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

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

`brain.formatContext(memories)`

`brain.destroy()`