{
  "markdown": "# Clude\n\n[![npm version](https://img.shields.io/npm/v/@clude/sdk)](https://www.npmjs.com/package/@clude/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**Cognitive memory for AI agents.** Not just storage — synthesis.\n\n---\n\n## About Clude\n\n### What it is\n\nA cognitive memory system. Most memory SDKs store and retrieve. Clude also processes memories over time — decay, consolidation, contradiction resolution, reflection.\n\n- **Benchmarked:** 1.96% hallucination on [HaluMem](https://arxiv.org/abs/2511.03506) — next best system: 15.2%. Industry average: ~21%.\n- **Local-first:** SQLite + local embeddings. Zero API keys, zero network, full semantic search offline.\n- **Hosted:** One API key, no infrastructure. `npx @clude/sdk register`\n- **Portable memory:** export/import in JSON, Markdown, ChatGPT, Claude, and Gemini formats. Your memories move between agents, frameworks, and models.\n\n**Cognitive architecture:**\n- **Typed memory with differential decay** — episodic (7%/day), semantic (2%/day), procedural (3%/day), self-model (1%/day). Accessed memories get reinforced.\n- **Autonomous dream cycles** — consolidation, compaction, reflection, contradiction resolution, emergence.\n- **Bond-typed memory graph** — weighted typed edges with Hebbian reinforcement on co-retrieval.\n- **Clinamen** — lateral retrieval of high-importance, low-relevance memories.\n\n### What it isn't yet\n\nNo 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.\n\n### What it could be\n\nClude 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.\n\n---\n\n**Public Wallet: CA1HYUXZXKc7CasRGpQotMM9RiYJbVuPJq3n8Ar9oQZb**\n\n```bash\nnpm install -g @clude/sdk\nclude setup\n```\n\nBuilt on [Stanford Generative Agents](https://arxiv.org/abs/2304.03442), [MemGPT/Letta](https://arxiv.org/abs/2310.08560), [CoALA](https://arxiv.org/abs/2309.02427), and [Beads](https://github.com/steveyegge/beads).\n\n**Works with:** Claude Code, Claude Desktop, Cursor, and any MCP-compatible agent runtime.\n\n---\n\n## Quick Start — Hosted (Zero Setup)\n\n```bash\nnpx @clude/sdk setup   # Creates agent, installs MCP, done\n```\n\nOr use the SDK:\n\n```typescript\nimport { Cortex } from '@clude/sdk';\n\nconst brain = new Cortex({\n  hosted: { apiKey: process.env.CORTEX_API_KEY! },\n});\n\nawait brain.init();\n\nawait brain.store({\n  type: 'episodic',\n  content: 'User asked about pricing and seemed frustrated.',\n  summary: 'Frustrated user asking about pricing',\n  tags: ['pricing', 'user-concern'],\n  importance: 0.7,\n  source: 'my-agent',\n});\n\nconst memories = await brain.recall({\n  query: 'what do users think about pricing',\n  limit: 5,\n});\n```\n\nNo database, no infrastructure. Memories stored on CLUDE infrastructure, isolated by API key.\n\n## Quick Start — Self-Hosted\n\nFor full control, use your own Supabase:\n\n```typescript\nimport { Cortex } from '@clude/sdk';\n\nconst brain = new Cortex({\n  supabase: {\n    url: process.env.SUPABASE_URL!,\n    serviceKey: process.env.SUPABASE_KEY!,\n  },\n  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },\n});\n\nawait brain.init();\n\nawait brain.store({\n  type: 'episodic',\n  content: 'User asked about pricing and seemed frustrated.',\n  summary: 'Frustrated user asking about pricing',\n  tags: ['pricing', 'user-concern'],\n  source: 'my-agent',\n  relatedUser: 'user-123',\n});\n\nconst memories = await brain.recall({\n  query: 'what do users think about pricing',\n  limit: 5,\n});\n\nconst context = brain.formatContext(memories);\n// Pass `context` into your system prompt\n```\n\n---\n\n## Dashboard\n\nExplore your agent's memory at [clude.io/dashboard-new](https://clude.io/dashboard-new).\n\n- **Memory Timeline** — chronological view with search and filtering\n- **Brain View** — 3D visualization of consciousness and self-model\n- **Entity Map** — knowledge graph of people, projects, concepts (self-hosted)\n- **Decay Heatmap** — memory health by type and age\n- **Memory Packs** — export/import in JSON, Markdown, ChatGPT, Claude, Gemini formats\n\nSign in with a Solana wallet or Cortex API key.\n\n---\n\n## CLI\n\n```bash\nnpx @clude/sdk setup          # Guided setup: register + config + MCP install\nnpx @clude/sdk register       # Get an API key for hosted mode\nnpx @clude/sdk init           # Advanced setup (self-hosted options)\nnpx @clude/sdk status         # Check if Clude is active + memory stats\nnpx @clude/sdk mcp-install    # Install MCP server for your IDE\nnpx @clude/sdk mcp-serve      # Run as MCP server (used by agent runtimes)\nnpx @clude/sdk connect        # Connect Claude Desktop / claude.ai as a remote MCP connector\nnpx @clude/sdk export         # Export memories (json/md/chatgpt/gemini)\nnpx @clude/sdk import         # Import from ChatGPT, markdown, or JSON\nnpx @clude/sdk sync           # Auto-update system prompt file\nnpx @clude/sdk doctor         # Run diagnostics\nnpx @clude/sdk start          # Start the full Clude bot\nnpx @clude/sdk --version      # Show version\n```\n\n`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).\n\n---\n\n## MCP Integration\n\nAdd Clude to any MCP-compatible agent. Run `npx @clude/sdk setup` for automatic installation, or add manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"clude-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"@clude/sdk\", \"mcp-serve\"],\n      \"env\": {\n        \"CORTEX_API_KEY\": \"clk_...\"\n      }\n    }\n  }\n}\n```\n\n**Config file locations:**\n- Claude Code: `.mcp.json` (project root)\n- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Cursor: `~/.cursor/mcp.json`\n\n### MCP Tools\n\nYour agent gets 8 tools:\n\n| Tool | Description |\n|------|-------------|\n| `recall_memories` | Search memories with hybrid scoring (vector + keyword + tags + importance) |\n| `store_memory` | Store a new memory with type, content, summary, tags, importance |\n| `batch_store_memories` | Store up to 50 memories in a single call |\n| `list_memories` | Browse without a query — paginated, sorted by recency, importance, or last access |\n| `update_memory` | Update fields of an existing memory by ID |\n| `delete_memory` | Permanently delete a memory by ID |\n| `get_memory_stats` | Memory statistics — counts by type, avg importance/decay, top tags |\n| `find_clinamen` | Anomaly retrieval — find high-importance memories with low relevance to current context |\n\n### MCP Modes\n\nThe MCP server runs in four modes, auto-detected from environment:\n\n| Mode | Config | Storage |\n|------|--------|---------|\n| **Hosted** | `CORTEX_API_KEY` | clude.io (zero setup) |\n| **Self-hosted** | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` | Your Supabase |\n| **Local SQLite (default)** | none — what `setup` creates | `~/.clude/brain.db` (local embeddings, fully offline) |\n| **Local JSON** | `--local` flag or `CLUDE_LOCAL=true` | `~/.clude/memories.json` (portable single file) |\n\nThe 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.\n\n---\n\n## Setup (Self-Hosted)\n\n### 1. Create a Supabase project\n\nGo to [supabase.com](https://supabase.com) and create a free project.\n\n### 2. Run the schema\n\nOpen the SQL Editor in your Supabase dashboard and paste the contents of `supabase-schema.sql`:\n\n```bash\ncat node_modules/@clude/sdk/supabase-schema.sql\n```\n\nOr let `brain.init()` attempt auto-creation.\n\n### 3. Enable extensions\n\n```sql\nCREATE EXTENSION IF NOT EXISTS vector;\nCREATE EXTENSION IF NOT EXISTS pg_trgm;\n```\n\n### 4. Get your keys\n\n- **Supabase URL + service key**: Project Settings > API\n- **Anthropic API key**: [console.anthropic.com](https://console.anthropic.com) (optional — required for dream cycles)\n- **Voyage AI or OpenAI key**: For vector search (optional — falls back to keyword scoring)\n\n---\n\n## API Reference\n\nTypeScript declarations ship with the package (v3.3.0+) — `Cortex` and every option/result type below import with full IntelliSense under strict mode.\n\n### Constructor\n\n**Hosted mode:**\n\n```typescript\nconst brain = new Cortex({\n  hosted: {\n    apiKey: string,      // From `npx @clude/sdk register`\n    baseUrl?: string,    // Default: 'https://clude.io'\n  },\n});\n```\n\n**Self-hosted mode:**\n\n```typescript\nconst brain = new Cortex({\n  supabase: { url: string, serviceKey: string },\n\n  // Optional — required for dream cycles and LLM importance scoring\n  anthropic: { apiKey: string, model?: string },\n\n  // Optional — enables vector similarity search\n  embedding: {\n    provider: 'voyage' | 'openai',\n    apiKey: string,\n    model?: string,\n    dimensions?: number,\n  },\n\n  // Optional — commits memory hashes to Solana\n  solana: { rpcUrl?: string, botWalletPrivateKey?: string },\n\n  // Optional — owner wallet for memory isolation\n  ownerWallet?: string,\n});\n```\n\n### `brain.init()`\n\nInitialize the database schema. Call once before any other operation.\n\n### `brain.store(opts)`\n\nStore a new memory. Returns the memory ID or `null`.\n\n```typescript\nconst id = await brain.store({\n  type: 'episodic',\n  content: 'Full content of the memory...',\n  summary: 'Brief summary',\n  source: 'my-agent',\n  tags: ['user', 'question'],\n  importance: 0.7,          // 0-1, or omit for LLM-based scoring\n  relatedUser: 'user-123',\n  emotionalValence: 0.3,    // -1 (negative) to 1 (positive)\n});\n```\n\n**Memory types:**\n\n| Type | Decay/day | Use for |\n|------|-----------|---------|\n| `episodic` | 7% | Raw interactions, conversations, events |\n| `semantic` | 2% | Learned knowledge, patterns, insights |\n| `procedural` | 3% | Behavioral rules, what works/doesn't |\n| `self_model` | 1% | Identity, self-understanding |\n| `introspective` | 2% | Journal entries, dream cycle outputs |\n\n### `brain.recall(opts)`\n\nRecall memories using hybrid scoring (vector + keyword + tag + importance + entity graph + association bonds).\n\n```typescript\nconst memories = await brain.recall({\n  query: 'what happened with user-123',\n  tags: ['pricing'],\n  relatedUser: 'user-123',\n  memoryTypes: ['episodic', 'semantic'],\n  limit: 10,\n  minImportance: 0.3,\n});\n```\n\n**6-phase retrieval pipeline:**\n1. Vector search (memory + fragment level via pgvector)\n2. Metadata filtering (user, wallet, tags, types)\n3. Merge vector + metadata candidates\n4. Composite scoring (recency + relevance + importance + vector similarity) * decay\n5. Entity-aware expansion — direct entity recall + co-occurring entity memories\n6. Bond-typed graph traversal — follow strong bonds (causes > supports > resolves > elaborates)\n\n### `brain.recallSummaries(opts)` / `brain.hydrate(ids)`\n\nToken-efficient two-stage retrieval:\n\n```typescript\nconst summaries = await brain.recallSummaries({ query: 'recent events' });\nconst topIds = summaries.slice(0, 3).map(s => s.id);\nconst full = await brain.hydrate(topIds);\n```\n\n### `brain.dream(opts?)`\n\nRun one dream cycle. Requires `anthropic` config.\n\n```typescript\nawait brain.dream({\n  onEmergence: async (thought) => {\n    console.log('Agent thought:', thought);\n  },\n});\n```\n\n**Five phases:**\n1. **Consolidation** — focal-point questions from recent memories, synthesizes evidence-linked insights\n2. **Compaction** — summarizes old, faded episodic memories into semantic summaries (Beads-inspired)\n3. **Reflection** — reviews self-model, updates with evidence citations\n4. **Contradiction Resolution** — finds unresolved `contradicts` links, resolves them, accelerates decay on weaker memory\n5. **Emergence** — introspective synthesis, output sent to `onEmergence` callback\n\n### `brain.startDreamSchedule()` / `brain.stopDreamSchedule()`\n\nAutomated dream cycles every 6 hours + daily decay at 3am UTC. Also triggers on accumulated importance.\n\n### `brain.link(sourceId, targetId, type, strength?)`\n\nCreate a typed association between memories.\n\n```typescript\nawait brain.link(42, 43, 'supports', 0.8);\n```\n\nLink types: `supports` | `contradicts` | `elaborates` | `causes` | `follows` | `relates` | `resolves` | `happens_before` | `happens_after` | `concurrent_with`\n\n### `brain.decay()` / `brain.stats()` / `brain.recent(hours)` / `brain.selfModel()`\n\n```typescript\nawait brain.decay();                            // Trigger memory decay\nconst stats = await brain.stats();              // Memory statistics\nconst last24h = await brain.recent(24);         // Recent memories\nconst identity = await brain.selfModel();       // Self-model memories\n```\n\n### `brain.formatContext(memories)`\n\nFormat memories into markdown for LLM prompt injection.\n\n```typescript\nconst memories = await brain.recall({ query: userMessage });\nconst context = brain.formatContext(memories);\n```\n\n### `brain.destroy()`\n\nStop dream schedules, clean up event listeners.\n\n---\n\n## Hosted vs Self-Hosted\n\n| | **Hosted** | **Self-Hosted** |\n|---|---|---|\n| **Setup** | Just an API key | Your own Supabase |\n| **store / recall / stats** | Yes | Yes |\n| **Dream cycles** | No | Yes (requires Anthropic) |\n| **Entity graph** | No | Yes |\n| **Memory packs** | No | Yes |\n| **Embeddings** | Managed | Configurable (Voyage/OpenAI) |\n| **On-chain commits** | No | Yes (Solana) |\n| **Dashboard** | Yes (API key login) | Yes (wallet login) |\n\n## Graceful Degradation\n\n| Feature | Without it |\n|---------|------------|\n| `anthropic` not set | LLM importance scoring falls back to rules. `dream()` throws. |\n| `embedding` not set | Vector search disabled, recall uses keyword + tag scoring only. |\n| `solana` not set | On-chain memory commits silently skipped. |\n\n---\n\n## How It Works\n\n### Memory Retrieval\n\nHybrid scoring (Park et al. 2023):\n\n- **Recency**: `0.995^hours` exponential decay since last access\n- **Relevance**: Keyword trigram similarity + tag overlap\n- **Importance**: LLM-scored 1-10, normalized to 0-1\n- **Vector similarity**: Cosine similarity via pgvector HNSW indexes\n- **Graph boost**: Association link strength between co-retrieved memories\n\nRecalled memories get reinforced — access count increments, decay resets, co-retrieved memories strengthen links (Hebbian learning).\n\n### Memory Decay\n\nEach type persists at a different rate:\n\n- **Episodic** (0.93/day): Events fade quickly unless reinforced\n- **Semantic** (0.98/day): Knowledge persists\n- **Procedural** (0.97/day): Behavioral patterns are stable\n- **Self-model** (0.99/day): Identity is nearly permanent\n\n### Dream Cycles\n\nFive-phase introspection triggered by accumulated importance or 6-hour cron:\n\n1. **Consolidation** — focal-point questions, evidence-linked insights\n2. **Compaction** — old faded memories summarized into semantic entries\n3. **Reflection** — self-model updates with evidence citations\n4. **Contradiction Resolution** — resolves conflicting memories\n5. **Emergence** — introspective synthesis\n\n### Memory Graph\n\nMemories form a graph with typed bonds:\n\n```\n├── Memories = nodes with type, importance, decay\n├── Bonds = typed weighted edges\n│   ├── causes (1.0)     — \"this led to that\"\n│   ├── supports (0.9)   — \"evidence for\"\n│   ├── concurrent_with (0.8) — \"happened at the same time\"\n│   ├── resolves (0.8)   — \"contradiction resolved\"\n│   ├── happens_before/after (0.7) — temporal ordering\n│   ├── elaborates (0.7) — \"adds detail\"\n│   ├── contradicts (0.6) — \"these conflict\"\n│   ├── relates (0.4)    — \"conceptually linked\"\n│   └── follows (0.3)    — \"temporal sequence\"\n├── Entities = extracted people, tokens, concepts, wallets\n└── Co-occurrence = entities that appear together\n```\n\n---\n\n## Running the Clude Bot\n\nThis package also includes the full Clude bot — an autonomous AI agent on X ([@Cludebot](https://x.com/Cludebot)).\n\n```bash\ngit clone https://github.com/sebbsssss/clude.git\ncd cludebot\nnpm install\ncp .env.example .env  # fill in API keys\nnpm run dev\n```\n\n---\n\n## Stack\n\nTypeScript, Supabase (PostgreSQL + pgvector), Anthropic Claude, Voyage AI / OpenAI embeddings, Solana, Node.js.\n\n## Docs for AI agents\n\nIntegrating Clude with an AI coding assistant? Point it at [clude.io/llms-full.txt](https://clude.io/llms-full.txt) — the complete SDK, REST, CLI, and MCP reference in a single fetch.\n\n---\n\n## A note on AI-assisted discovery\n\nAI 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.\n\n**On the package name:** This SDK publishes as [`clude`](https://www.npmjs.com/package/@clude/sdk) on npm (formerly `clude`, renamed in v3.0). The same codebase also powers [@Cludebot](https://x.com/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.\n\n**On default concepts:** Labels like `whale_activity` are from the original crypto use case. Override or ignore them. The core system is domain-agnostic.\n\n---\n\n## Contributing\n\nContributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nMIT\n",
  "bytes": 17840,
  "sha": "fdaf15aa24fe420074eb9b13da76da3a6c4f11dc68008fe834fa1eb48c05e447",
  "repo_slug": "sebbsssss/clude",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sebbsssss_clude_6d8fe1d9/readme"
}