@clude/sdk 3.3.0 → 3.4.0

package/README.md

@@ -1,59 +1,30 @@
 # Clude
 
 [![npm version](https://img.shields.io/npm/v/@clude/sdk)](https://www.npmjs.com/package/@clude/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sebbsssss/clude/blob/main/LICENSE)
 
 **Cognitive memory for AI agents.** Not just storage — synthesis.
 
----
+Clude gives any agent persistent, typed memory with hybrid retrieval (vector + keyword + tags + importance), differential decay, a bond-typed memory graph, and autonomous consolidation. TypeScript declarations included.
 
-## 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](https://arxiv.org/abs/2511.03506) — 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.
+- **Hosted:** one API key, no infrastructure — `npx @clude/sdk register`
+- **Benchmarked:** 85.0% on [LongMemEval-S](https://arxiv.org/abs/2410.10813), reproducible — the harness, per-question outputs, and judge model ship [in the repo](https://github.com/sebbsssss/clude/tree/main/benchmarks/longmemeval-s). 1.96% hallucination on [HaluMem](https://arxiv.org/abs/2511.03506).
+- **Portable:** export/import memories as JSON, Markdown, ChatGPT, Claude, or Gemini packs.
 
-### What it could be
+Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible runtime.
 
-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.
+Need a small footprint? `npm install @clude/sdk --omit=optional` skips the local embedding runtime (~85% smaller install); local mode then uses keyword search and `clude status` tells you so.
 
----
-
-**Public Wallet: CA1HYUXZXKc7CasRGpQotMM9RiYJbVuPJq3n8Ar9oQZb**
+## Quick start
 
 ```bash
-npm install -g @clude/sdk
-clude setup
+npx @clude/sdk setup   # register + config + MCP install, ~30 seconds
 ```
 
-Built 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).
-
-**Works with:** Claude Code, Claude Desktop, Cursor, and any MCP-compatible agent runtime.
-
----
-
-## Quick Start — Hosted (Zero Setup)
-
-```bash
-npx @clude/sdk setup   # Creates agent, installs MCP, done
-```
+Works headless too: with no TTY it completes in local-only mode (set `CLUDE_SETUP_EMAIL` to register in CI).
 
-Or use the SDK:
+Or use the SDK directly:
 
 ```typescript
 import { Cortex } from '@clude/sdk';
@@ -73,86 +44,22 @@ await brain.store({
   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:
-
-```typescript
-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
+const memories = await brain.recall({ query: 'what do users think about pricing', limit: 5 });
+const context = brain.formatContext(memories);  // markdown, ready for your system prompt
 ```
 
----
-
-## Dashboard
-
-Explore your agent's memory at [clude.io/dashboard-new](https://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
+## Storage modes
 
-```bash
-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 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 start          # Start the full Clude bot
-npx @clude/sdk --version      # Show version
-```
-
----
+| Mode | Config | Storage |
+|---|---|---|
+| **Hosted** | `CORTEX_API_KEY` | clude.io, isolated per API key |
+| **Self-hosted** | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` | your Supabase (PostgreSQL + pgvector) |
+| **Local (default)** | none | `~/.clude/brain.db` — SQLite + local embeddings, fully offline |
+| **Local (JSON)** | `CLUDE_LOCAL=true` or `--local` | `~/.clude/memories.json`, portable single file |
 
-## MCP Integration
+Self-hosted unlocks the full cognitive layer: dream cycles (consolidation, reflection, contradiction resolution), the entity graph, and memory packs.
 
-Add Clude to any MCP-compatible agent. Run `npx @clude/sdk setup` for automatic installation, or add manually:
+## MCP integration
 
 ```json
 {
@@ -160,354 +67,50 @@ Add Clude to any MCP-compatible agent. Run `npx @clude/sdk setup` for automatic
     "clude-memory": {
       "command": "npx",
       "args": ["@clude/sdk", "mcp-serve"],
-      "env": {
-        "CORTEX_API_KEY": "clk_..."
-      }
+      "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 4 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 |
-| `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 three modes, auto-detected from environment:
+Or `npx @clude/sdk setup` to install automatically. Your agent gets 8 tools: `recall_memories`, `store_memory`, `batch_store_memories`, `list_memories`, `update_memory`, `delete_memory`, `get_memory_stats`, `find_clinamen` (anomaly retrieval). A remote Streamable-HTTP connector is also available at `https://clude.io/api/mcp` (`npx @clude/sdk connect`).
 
-| Mode | Config | Storage |
-|------|--------|---------|
-| **Hosted** | `CORTEX_API_KEY` | clude.io (zero setup) |
-| **Self-hosted** | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` | Your Supabase |
-| **Local** | `--local` flag or `CLUDE_LOCAL=true` | `~/.clude/memories.json` |
-
----
-
-## Setup (Self-Hosted)
-
-### 1. Create a Supabase project
-
-Go to [supabase.com](https://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`:
+## CLI
 
 ```bash
-cat node_modules/clude/supabase-schema.sql
-```
-
-Or let `brain.init()` attempt auto-creation.
-
-### 3. Enable extensions
-
-```sql
-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](https://console.anthropic.com) (optional — required for dream cycles)
-- **Voyage AI or OpenAI key**: For vector search (optional — falls back to keyword scoring)
-
----
-
-## API Reference
-
-### Constructor
-
-**Hosted mode:**
-
-```typescript
-const brain = new Cortex({
-  hosted: {
-    apiKey: string,      // From `npx @clude/sdk register`
-    baseUrl?: string,    // Default: 'https://clude.io'
-  },
-});
-```
-
-**Self-hosted mode:**
-
-```typescript
-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,
-});
+npx @clude/sdk setup          # Guided setup: register + config + MCP install
+npx @clude/sdk status         # Mode, storage, MCP detection, memory stats
+npx @clude/sdk register       # Get a hosted API key
+npx @clude/sdk mcp-install    # Install MCP config for your IDE
+npx @clude/sdk mcp-serve      # Run as a stdio MCP server
+npx @clude/sdk connect        # Connect Claude Desktop / claude.ai via remote MCP
+npx @clude/sdk export         # Export memories (json/md/chatgpt/gemini/memorypack)
+npx @clude/sdk import         # Import from ChatGPT export, markdown, JSON
+npx @clude/sdk doctor         # Diagnostics
 ```
 
-### `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`.
-
-```typescript
-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 model
 
-**Memory types:**
+Five typed stores with differential decay — accessed memories are reinforced, unaccessed ones fade:
 
 | 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).
-
-```typescript
-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:
-
-```typescript
-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.
-
-```typescript
-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.
-
-```typescript
-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()`
-
-```typescript
-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.
-
-```typescript
-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:
-
-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](https://x.com/Cludebot)).
-
-```bash
-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.
-
-## Examples
-
-See [`examples/`](./examples) for runnable scripts:
-
-- **[hosted-mode.ts](./examples/hosted-mode.ts)** — Zero-setup with API key
-- **[basic-memory.ts](./examples/basic-memory.ts)** — Store and recall with Supabase
-- **[chat-agent.ts](./examples/chat-agent.ts)** — Interactive chat agent with memory
-- **[progressive-disclosure.ts](./examples/progressive-disclosure.ts)** — Token-efficient retrieval
-
----
-
-## 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`](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.
+| `episodic` | 7% | events, conversations |
+| `semantic` | 2% | facts, knowledge, insights |
+| `procedural` | 3% | workflows, what works |
+| `self_model` | 1% | identity, preferences |
+| `introspective` | 2% | reflections, journals |
 
-**On default concepts:** Labels like `whale_activity` are from the original crypto use case. Override or ignore them. The core system is domain-agnostic.
+Retrieval is hybrid-scored (recency + relevance + importance + vector similarity, weighted by decay) with entity-aware expansion and bond-typed graph traversal. Co-retrieved memories strengthen their links (Hebbian reinforcement).
 
----
+## Docs
 
-## Contributing
+- **Complete integration reference (one fetch, agent-friendly):** [clude.io/llms-full.txt](https://clude.io/llms-full.txt)
+- Docs: [clude.io/docs](https://clude.io/docs) · Dashboard: [clude.io/dashboard](https://clude.io/dashboard)
+- REST API: `POST https://clude.io/api/cortex/register` → then `/store`, `/recall`, `/stats`, ... with `Authorization: Bearer <key>`
+- Source, issues, benchmarks: [github.com/sebbsssss/clude](https://github.com/sebbsssss/clude)
 
-Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+Built on research from [Stanford Generative Agents](https://arxiv.org/abs/2304.03442), [MemGPT/Letta](https://arxiv.org/abs/2310.08560), and [CoALA](https://arxiv.org/abs/2309.02427). The same engine powers [@Cludebot](https://x.com/Cludebot), an autonomous agent running publicly 24/7 — a live demonstration of the memory system.
 
 ## License
 

package/README.npm.md

@@ -0,0 +1,117 @@
+# Clude
+
+[![npm version](https://img.shields.io/npm/v/@clude/sdk)](https://www.npmjs.com/package/@clude/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sebbsssss/clude/blob/main/LICENSE)
+
+**Cognitive memory for AI agents.** Not just storage — synthesis.
+
+Clude gives any agent persistent, typed memory with hybrid retrieval (vector + keyword + tags + importance), differential decay, a bond-typed memory graph, and autonomous consolidation. TypeScript declarations included.
+
+- **Local-first:** SQLite + local embeddings. Zero API keys, zero network, full semantic search offline.
+- **Hosted:** one API key, no infrastructure — `npx @clude/sdk register`
+- **Benchmarked:** 85.0% on [LongMemEval-S](https://arxiv.org/abs/2410.10813), reproducible — the harness, per-question outputs, and judge model ship [in the repo](https://github.com/sebbsssss/clude/tree/main/benchmarks/longmemeval-s). 1.96% hallucination on [HaluMem](https://arxiv.org/abs/2511.03506).
+- **Portable:** export/import memories as JSON, Markdown, ChatGPT, Claude, or Gemini packs.
+
+Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible runtime.
+
+Need a small footprint? `npm install @clude/sdk --omit=optional` skips the local embedding runtime (~85% smaller install); local mode then uses keyword search and `clude status` tells you so.
+
+## Quick start
+
+```bash
+npx @clude/sdk setup   # register + config + MCP install, ~30 seconds
+```
+
+Works headless too: with no TTY it completes in local-only mode (set `CLUDE_SETUP_EMAIL` to register in CI).
+
+Or use the SDK directly:
+
+```typescript
+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 });
+const context = brain.formatContext(memories);  // markdown, ready for your system prompt
+```
+
+## Storage modes
+
+| Mode | Config | Storage |
+|---|---|---|
+| **Hosted** | `CORTEX_API_KEY` | clude.io, isolated per API key |
+| **Self-hosted** | `SUPABASE_URL` + `SUPABASE_SERVICE_KEY` | your Supabase (PostgreSQL + pgvector) |
+| **Local (default)** | none | `~/.clude/brain.db` — SQLite + local embeddings, fully offline |
+| **Local (JSON)** | `CLUDE_LOCAL=true` or `--local` | `~/.clude/memories.json`, portable single file |
+
+Self-hosted unlocks the full cognitive layer: dream cycles (consolidation, reflection, contradiction resolution), the entity graph, and memory packs.
+
+## MCP integration
+
+```json
+{
+  "mcpServers": {
+    "clude-memory": {
+      "command": "npx",
+      "args": ["@clude/sdk", "mcp-serve"],
+      "env": { "CORTEX_API_KEY": "clk_..." }
+    }
+  }
+}
+```
+
+Or `npx @clude/sdk setup` to install automatically. Your agent gets 8 tools: `recall_memories`, `store_memory`, `batch_store_memories`, `list_memories`, `update_memory`, `delete_memory`, `get_memory_stats`, `find_clinamen` (anomaly retrieval). A remote Streamable-HTTP connector is also available at `https://clude.io/api/mcp` (`npx @clude/sdk connect`).
+
+## CLI
+
+```bash
+npx @clude/sdk setup          # Guided setup: register + config + MCP install
+npx @clude/sdk status         # Mode, storage, MCP detection, memory stats
+npx @clude/sdk register       # Get a hosted API key
+npx @clude/sdk mcp-install    # Install MCP config for your IDE
+npx @clude/sdk mcp-serve      # Run as a stdio MCP server
+npx @clude/sdk connect        # Connect Claude Desktop / claude.ai via remote MCP
+npx @clude/sdk export         # Export memories (json/md/chatgpt/gemini/memorypack)
+npx @clude/sdk import         # Import from ChatGPT export, markdown, JSON
+npx @clude/sdk doctor         # Diagnostics
+```
+
+## Memory model
+
+Five typed stores with differential decay — accessed memories are reinforced, unaccessed ones fade:
+
+| Type | Decay/day | Use for |
+|---|---|---|
+| `episodic` | 7% | events, conversations |
+| `semantic` | 2% | facts, knowledge, insights |
+| `procedural` | 3% | workflows, what works |
+| `self_model` | 1% | identity, preferences |
+| `introspective` | 2% | reflections, journals |
+
+Retrieval is hybrid-scored (recency + relevance + importance + vector similarity, weighted by decay) with entity-aware expansion and bond-typed graph traversal. Co-retrieved memories strengthen their links (Hebbian reinforcement).
+
+## Docs
+
+- **Complete integration reference (one fetch, agent-friendly):** [clude.io/llms-full.txt](https://clude.io/llms-full.txt)
+- Docs: [clude.io/docs](https://clude.io/docs) · Dashboard: [clude.io/dashboard](https://clude.io/dashboard)
+- REST API: `POST https://clude.io/api/cortex/register` → then `/store`, `/recall`, `/stats`, ... with `Authorization: Bearer <key>`
+- Source, issues, benchmarks: [github.com/sebbsssss/clude](https://github.com/sebbsssss/clude)
+
+Built on research from [Stanford Generative Agents](https://arxiv.org/abs/2304.03442), [MemGPT/Letta](https://arxiv.org/abs/2310.08560), and [CoALA](https://arxiv.org/abs/2309.02427). The same engine powers [@Cludebot](https://x.com/Cludebot), an autonomous agent running publicly 24/7 — a live demonstration of the memory system.
+
+## License
+
+MIT

package/dist/cli/index.js

@@ -3041,9 +3041,45 @@ function printSqliteStatus() {
   try {
     const Database2 = require("better-sqlite3");
     const db = new Database2(BRAIN_DB, { readonly: true });
-    const row = db.prepare("SELECT COUNT(*) AS n FROM memories").get();
+    const total = db.prepare("SELECT COUNT(*) AS n FROM memories").get().n;
+    printSuccess(`${total} memories in local SQLite store`);
+    if (total > 0) {
+      const byType = db.prepare(
+        "SELECT memory_type, COUNT(*) AS n FROM memories GROUP BY memory_type ORDER BY n DESC"
+      ).all();
+      printInfo(byType.map((r) => `${r.memory_type} ${r.n}`).join(" \xB7 "));
+      const agg = db.prepare(
+        "SELECT AVG(decay_factor) AS decay, AVG(importance) AS imp, SUM(access_count > 1) AS reinforced FROM memories"
+      ).get();
+      printInfo(`health: avg decay ${(agg.decay ?? 1).toFixed(2)} \xB7 avg importance ${(agg.imp ?? 0).toFixed(2)} \xB7 ${agg.reinforced ?? 0} reinforced by recall`);
+      let semantic = false;
+      try {
+        require.resolve("@huggingface/transformers");
+        semantic = true;
+      } catch {
+      }
+      if (semantic) {
+        printInfo("search: semantic (local embeddings) + keyword");
+      } else {
+        printWarn("search: keyword-only \u2014 install @huggingface/transformers for offline semantic search");
+      }
+      try {
+        const bonds = db.prepare("SELECT COUNT(*) AS n FROM links").get().n;
+        const queued = db.prepare("SELECT COUNT(*) AS n FROM dream_queue").get().n;
+        if (bonds > 0 || queued > 0) {
+          printInfo(`graph: ${bonds} bonds between memories \xB7 ${queued} dream ops queued`);
+        }
+      } catch {
+      }
+      const top = db.prepare(
+        "SELECT summary, access_count FROM memories WHERE access_count > 1 ORDER BY access_count DESC LIMIT 1"
+      ).get();
+      if (top) {
+        const label = top.summary.length > 60 ? top.summary.slice(0, 57) + "..." : top.summary;
+        printInfo(`most reinforced: "${label}" (recalled ${top.access_count}\xD7)`);
+      }
+    }
     db.close();
-    printSuccess(`${row.n} memories in local SQLite store`);
   } catch {
     printSuccess("Local SQLite store ready");
   }
@@ -11245,7 +11281,7 @@ var require_package = __commonJS({
   "packages/brain/package.json"(exports2, module2) {
     module2.exports = {
       name: "@clude/brain",
-      version: "3.3.0",
+      version: "3.4.0",
       private: true,
       description: "Clude brain \u2014 memory, dreams, agents, personality, SDK",
       main: "dist/index.js",
@@ -11480,11 +11516,6 @@ function loadSelfHosted() {
       _deleteMemory = memory.deleteMemory;
       _updateMemory = memory.updateMemory;
       _listMemories = memory.listMemories;
-      try {
-        const skillExtraction = require("@clude/shared/core/skill-extraction");
-        _extractSkill = skillExtraction.extractSkill;
-      } catch {
-      }
       try {
         const confidenceGate = (init_confidence_gate(), __toCommonJS(confidence_gate_exports));
         _evaluateConfidence = confidenceGate.evaluateConfidence;
@@ -11536,7 +11567,7 @@ async function main() {
   await server.connect(transport);
   console.error(`[clude-mcp] Server started on stdio`);
 }
-var import_mcp, import_stdio, import_zod, CORTEX_API_KEY, CORTEX_HOST_URL, isLocalMode, isHostedMode, SUPABASE_URL, isSqliteMode, FETCH_TIMEOUT_MS, _sqliteStore, _recallMemories, _storeMemory, _getMemoryStats, _evaluateConfidence, _deleteMemory, _updateMemory, _listMemories, _extractSkill, server, MEMORY_TYPES;
+var import_mcp, import_stdio, import_zod, CORTEX_API_KEY, CORTEX_HOST_URL, isLocalMode, isHostedMode, SUPABASE_URL, isSqliteMode, FETCH_TIMEOUT_MS, _sqliteStore, _recallMemories, _storeMemory, _getMemoryStats, _evaluateConfidence, _deleteMemory, _updateMemory, _listMemories, server, MEMORY_TYPES;
 var init_server = __esm({
   "packages/brain/src/mcp/server.ts"() {
     "use strict";
@@ -12204,73 +12235,6 @@ var init_server = __esm({
         }]
       })
     );
-    server.tool(
-      "extract_skill",
-      "Extract domain-specific knowledge from memory into a shareable skills document. Performs multi-pass extraction across the memory bank and entity graph, then synthesizes results into a structured markdown document.",
-      {
-        domain: import_zod.z.string().describe('Domain or topic to extract (e.g., "DeFi", "React", "Solana development")'),
-        depth: import_zod.z.enum(["shallow", "deep"]).optional().describe("shallow = seed memories only, deep = graph expansion via entity relations (default: deep)"),
-        include_provenance: import_zod.z.boolean().optional().describe("Include source memory IDs for traceability (default: false)"),
-        max_memories: import_zod.z.number().min(10).max(500).optional().describe("Max memories to include in extraction (default: 200)")
-      },
-      async (args) => {
-        try {
-          if (isSqliteMode || isLocalMode) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({ error: "extract_skill is not available in local/SQLite mode \u2014 requires Supabase for entity graph and embeddings." }) }],
-              isError: true
-            };
-          }
-          if (isHostedMode) {
-            const result2 = await cortexFetch("POST", "/api/cortex/extract-skill", {
-              domain: args.domain,
-              depth: args.depth,
-              include_provenance: args.include_provenance,
-              max_memories: args.max_memories
-            });
-            return {
-              content: [{
-                type: "text",
-                text: JSON.stringify({
-                  markdown: result2.markdown,
-                  stats: result2.stats,
-                  warning: result2.warning
-                }, null, 2)
-              }]
-            };
-          }
-          loadSelfHosted();
-          if (!_extractSkill) {
-            return {
-              content: [{ type: "text", text: JSON.stringify({ error: "Skill extraction module not available. Check that src/core/skill-extraction.ts is built." }) }],
-              isError: true
-            };
-          }
-          const result = await _extractSkill({
-            domain: args.domain,
-            depth: args.depth || "deep",
-            includeProvenance: args.include_provenance || false,
-            maxMemories: args.max_memories || 200
-          });
-          return {
-            content: [{
-              type: "text",
-              text: JSON.stringify({
-                markdown: result.markdown,
-                stats: result.stats,
-                warning: result.warning
-              }, null, 2)
-            }]
-          };
-        } catch (err) {
-          console.error("[clude-mcp] extract_skill error:", err.message);
-          return {
-            content: [{ type: "text", text: JSON.stringify({ error: err.message }) }],
-            isError: true
-          };
-        }
-      }
-    );
     main().catch((err) => {
       console.error("[clude-mcp] Fatal error:", err);
       process.exit(1);

package/dist/mcp/server.js

@@ -6001,7 +6001,7 @@ var require_package = __commonJS({
   "packages/brain/package.json"(exports2, module2) {
     module2.exports = {
       name: "@clude/brain",
-      version: "3.3.0",
+      version: "3.4.0",
       private: true,
       description: "Clude brain \u2014 memory, dreams, agents, personality, SDK",
       main: "dist/index.js",
@@ -6488,7 +6488,6 @@ var _evaluateConfidence;
 var _deleteMemory;
 var _updateMemory;
 var _listMemories;
-var _extractSkill;
 function loadSelfHosted() {
   if (!_recallMemories) {
     try {
@@ -6499,11 +6498,6 @@ function loadSelfHosted() {
       _deleteMemory = memory.deleteMemory;
       _updateMemory = memory.updateMemory;
       _listMemories = memory.listMemories;
-      try {
-        const skillExtraction = require("@clude/shared/core/skill-extraction");
-        _extractSkill = skillExtraction.extractSkill;
-      } catch {
-      }
       try {
         const confidenceGate = (init_confidence_gate(), __toCommonJS(confidence_gate_exports));
         _evaluateConfidence = confidenceGate.evaluateConfidence;
@@ -7168,73 +7162,6 @@ server.prompt(
     }]
   })
 );
-server.tool(
-  "extract_skill",
-  "Extract domain-specific knowledge from memory into a shareable skills document. Performs multi-pass extraction across the memory bank and entity graph, then synthesizes results into a structured markdown document.",
-  {
-    domain: import_zod.z.string().describe('Domain or topic to extract (e.g., "DeFi", "React", "Solana development")'),
-    depth: import_zod.z.enum(["shallow", "deep"]).optional().describe("shallow = seed memories only, deep = graph expansion via entity relations (default: deep)"),
-    include_provenance: import_zod.z.boolean().optional().describe("Include source memory IDs for traceability (default: false)"),
-    max_memories: import_zod.z.number().min(10).max(500).optional().describe("Max memories to include in extraction (default: 200)")
-  },
-  async (args) => {
-    try {
-      if (isSqliteMode || isLocalMode) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({ error: "extract_skill is not available in local/SQLite mode \u2014 requires Supabase for entity graph and embeddings." }) }],
-          isError: true
-        };
-      }
-      if (isHostedMode) {
-        const result2 = await cortexFetch("POST", "/api/cortex/extract-skill", {
-          domain: args.domain,
-          depth: args.depth,
-          include_provenance: args.include_provenance,
-          max_memories: args.max_memories
-        });
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify({
-              markdown: result2.markdown,
-              stats: result2.stats,
-              warning: result2.warning
-            }, null, 2)
-          }]
-        };
-      }
-      loadSelfHosted();
-      if (!_extractSkill) {
-        return {
-          content: [{ type: "text", text: JSON.stringify({ error: "Skill extraction module not available. Check that src/core/skill-extraction.ts is built." }) }],
-          isError: true
-        };
-      }
-      const result = await _extractSkill({
-        domain: args.domain,
-        depth: args.depth || "deep",
-        includeProvenance: args.include_provenance || false,
-        maxMemories: args.max_memories || 200
-      });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            markdown: result.markdown,
-            stats: result.stats,
-            warning: result.warning
-          }, null, 2)
-        }]
-      };
-    } catch (err) {
-      console.error("[clude-mcp] extract_skill error:", err.message);
-      return {
-        content: [{ type: "text", text: JSON.stringify({ error: err.message }) }],
-        isError: true
-      };
-    }
-  }
-);
 async function main() {
   if (isSqliteMode) {
     console.error("[clude-mcp] SQLite mode: local-first storage at ~/.clude/brain.db");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clude/sdk",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "mcpName": "io.github.sebbsssss/clude",
   "description": "Persistent memory SDK for AI agents — Stanford Generative Agents architecture on Supabase + pgvector",
   "main": "dist/sdk/index.js",
@@ -31,7 +31,9 @@
   ],
   "scripts": {
     "build:publish": "node scripts/build-publish.mjs",
-    "prepublishOnly": "pnpm --filter @clude/shared build && pnpm --filter @clude/brain build && node scripts/build-publish.mjs",
+    "prepublishOnly": "pnpm --filter @clude/brain... build && node scripts/build-publish.mjs",
+    "prepack": "node scripts/swap-readme.mjs pack",
+    "postpack": "node scripts/swap-readme.mjs restore",
     "typecheck": "tsc --noEmit",
     "dashboard": "cd apps/dashboard && pnpm run dev",
     "dashboard:build": "cd apps/dashboard && pnpm run build"
@@ -77,7 +79,6 @@
   "packageManager": "pnpm@10.18.1",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
-    "@huggingface/transformers": "^4.1.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@solana/web3.js": "^1.98.4",
     "@supabase/supabase-js": "^2.95.3",
@@ -100,6 +101,7 @@
     "typescript": "^5.6.0"
   },
   "optionalDependencies": {
+    "@huggingface/transformers": "^4.1.0",
     "utf-8-validate": "^5.0.10"
   },
   "types": "./dist/sdk/index.d.ts"