feat(cli): show the cognitive layer in clude status

.gitignore

@@ -88,3 +88,4 @@ apps/mobile/ios/.symlinks/
 apps/mobile/android/.gradle/
 apps/mobile/android/local.properties
 apps/mobile/*.iml
+.README.repo.md

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [3.3.1] — 2026-07-11
+
+### Removed
+- **`extract_skill` MCP tool** — it was nonfunctional in every mode (the hosted endpoint was never implemented and the self-hosted module doesn't exist). Removed rather than advertise a tool that can't work; it can return with a real implementation.
+
+### Changed
+- **npm gets its own README** — `npm pack`/`publish` now swaps in a dev-focused `README.npm.md` (architecture, benchmarks, quick starts, API) via `prepack`/`postpack`; the repository README is unchanged.
+- **Docs synced with the product** — README and SKILL.md now document all 8 MCP tools, the SQLite-default local mode (`~/.clude/brain.db`) vs the `CLUDE_LOCAL` JSON store, headless setup with `CLUDE_SETUP_EMAIL`, `clude connect`/`doctor`, and TypeScript declarations; removed a dead `examples/` link. The `/install` page sample output matches the real setup flow, and its SDK example includes the required `summary` field.
+
 ## [3.3.0] — 2026-07-11
 
 First-run experience overhaul, driven by a clean-room installation audit.

README.md

@@ -141,13 +141,17 @@ 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
@@ -175,24 +179,31 @@ Add Clude to any MCP-compatible agent. Run `npx @clude/sdk setup` for automatic
 
 ### MCP Tools
 
-Your agent gets 4 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 three modes, auto-detected from environment:
+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** | `--local` flag or `CLUDE_LOCAL=true` | `~/.clude/memories.json` |
+| **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.
 
 ---
 
@@ -207,7 +218,7 @@ Go to [supabase.com](https://supabase.com) and create a free project.
 Open the SQL Editor in your Supabase dashboard and paste the contents of `supabase-schema.sql`:
 
 ```bash
-cat node_modules/clude/supabase-schema.sql
+cat node_modules/@clude/sdk/supabase-schema.sql
 ```
 
 Or let `brain.init()` attempt auto-creation.
@@ -229,6 +240,8 @@ CREATE EXTENSION IF NOT EXISTS pg_trgm;
 
 ## 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:**
@@ -484,14 +497,9 @@ npm run dev
 
 TypeScript, Supabase (PostgreSQL + pgvector), Anthropic Claude, Voyage AI / OpenAI embeddings, Solana, Node.js.
 
-## Examples
-
-See [`examples/`](./examples) for runnable scripts:
+## Docs for AI agents
 
-- **[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
+Integrating 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.
 
 ---
 

README.npm.md

@@ -0,0 +1,115 @@
+# 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.
+
+## 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

SKILL.md

@@ -44,6 +44,18 @@ Store a new memory. Memories persist across conversations and decay over time if
 - `related_wallet` — associated Solana wallet
 - `metadata` — arbitrary JSON metadata
 
+### `batch_store_memories`
+Store up to 50 memories in a single call. Returns an array of results with memory IDs. Same fields per memory as `store_memory`.
+
+### `list_memories`
+Browse memories without a search query. Paginated; sort by recency, importance, or last access. Filter by type or tags.
+
+### `update_memory`
+Update fields of an existing memory by its ID. Only provided fields are changed.
+
+### `delete_memory`
+Permanently delete a memory by its ID. Irreversible.
+
 ### `get_memory_stats`
 Get statistics: counts by type, average importance/decay, dream session history, top tags.
 
@@ -64,7 +76,8 @@ The MCP server auto-detects its mode from environment:
 |------|--------|---------|
 | **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` |
+| **Local SQLite (default)** | none | `~/.clude/brain.db` (local embeddings, fully offline) |
+| **Local JSON** | `--local` flag or `CLUDE_LOCAL=true` | `~/.clude/memories.json` (portable single file) |
 
 ## Setup
 

apps/web/public/install.html

@@ -258,12 +258,13 @@ <h2>Run the installer</h2>
 <div><span class="ok">  ✓</span>  Registered              <span class="blue">clk_xxxxxxxx…</span></div>
 <div><span class="ok">  ✓</span>  Config saved            <span class="dim">~/.clude/config.json</span></div>
 <div><span class="ok">  ✓</span>  Database ready          <span class="dim">~/.clude/brain.db</span></div>
-<div><span class="ok">  ✓</span>  MCP installed           <span class="dim">Claude Code, Cursor</span></div>
+<div><span class="ok">  ✓</span>  MCP installed           <span class="dim">Claude Code  ~/.claude.json</span></div>
+<div><span class="ok">  ✓</span>  Validated               <span class="dim">store → recall → ✓</span></div>
 <div class="out">&nbsp;</div>
 <div class="out">  <span class="blue">Your agent now has memory.</span></div>
           </div>
         </div>
-        <p>That's it. Restart your IDE. Your agent now has <code class="inline">store_memory</code>, <code class="inline">recall_memories</code>, and <code class="inline">get_memory_stats</code> tools.</p>
+        <p>That's it. Restart your IDE. Your agent now has 8 memory tools — <code class="inline">store_memory</code>, <code class="inline">recall_memories</code>, <code class="inline">batch_store_memories</code>, <code class="inline">list_memories</code>, <code class="inline">update_memory</code>, <code class="inline">delete_memory</code>, <code class="inline">get_memory_stats</code>, and <code class="inline">find_clinamen</code>. Works headless too: no TTY means no prompts (set <code class="inline">CLUDE_SETUP_EMAIL</code> in CI).</p>
       </div>
     </section>
 
@@ -301,6 +302,7 @@ <h2>Use the SDK directly</h2>
 <span class="k">await</span> brain.store({
   type: <span class="s">'episodic'</span>,
   content: <span class="s">'User prefers concise answers'</span>,
+  summary: <span class="s">'User prefers concise answers'</span>,
   source: <span class="s">'my-agent'</span>,
 });
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clude/sdk",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "mcpName": "io.github.sebbsssss/clude",
   "description": "Persistent memory SDK for AI agents — Stanford Generative Agents architecture on Supabase + pgvector",
   "main": "dist/sdk/index.js",
@@ -32,6 +32,8 @@
   "scripts": {
     "build:publish": "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"

packages/brain/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clude/brain",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "private": true,
   "description": "Clude brain — memory, dreams, agents, personality, SDK",
   "main": "dist/index.js",

packages/brain/src/cli/status.ts

@@ -95,9 +95,40 @@ function printSqliteStatus(): void {
   try {
     const Database = require('better-sqlite3');
     const db = new Database(BRAIN_DB, { readonly: true });
-    const row = db.prepare('SELECT COUNT(*) AS n FROM memories').get() as { n: number };
+    const total = (db.prepare('SELECT COUNT(*) AS n FROM memories').get() as { n: number }).n;
+    printSuccess(`${total} memories in local SQLite store`);
+
+    if (total > 0) {
+      // The cognitive layer (decay, reinforcement, bonds) runs silently —
+      // status is where users get to see that their memory is alive.
+      const byType = db.prepare(
+        'SELECT memory_type, COUNT(*) AS n FROM memories GROUP BY memory_type ORDER BY n DESC'
+      ).all() as Array<{ memory_type: string; n: number }>;
+      printInfo(byType.map((r) => `${r.memory_type} ${r.n}`).join(' · '));
+
+      const agg = db.prepare(
+        'SELECT AVG(decay_factor) AS decay, AVG(importance) AS imp, SUM(access_count > 1) AS reinforced FROM memories'
+      ).get() as { decay: number | null; imp: number | null; reinforced: number | null };
+      printInfo(`health: avg decay ${(agg.decay ?? 1).toFixed(2)} · avg importance ${(agg.imp ?? 0).toFixed(2)} · ${agg.reinforced ?? 0} reinforced by recall`);
+
+      // Bonds and queued dream work may not exist in older databases
+      try {
+        const bonds = (db.prepare('SELECT COUNT(*) AS n FROM links').get() as { n: number }).n;
+        const queued = (db.prepare('SELECT COUNT(*) AS n FROM dream_queue').get() as { n: number }).n;
+        if (bonds > 0 || queued > 0) {
+          printInfo(`graph: ${bonds} bonds between memories · ${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() as { summary: string; access_count: number } | undefined;
+      if (top) {
+        const label = top.summary.length > 60 ? top.summary.slice(0, 57) + '...' : top.summary;
+        printInfo(`most reinforced: "${label}" (recalled ${top.access_count}×)`);
+      }
+    }
     db.close();
-    printSuccess(`${row.n} memories in local SQLite store`);
   } catch {
     printSuccess('Local SQLite store ready');
   }