vektor-slipstream 1.4.3 → 1.4.4

package/README.md

@@ -3,6 +3,7 @@
 Hardware-accelerated persistent memory for AI agents. Local-first. No cloud. One-time payment.
 
 [![npm](https://img.shields.io/npm/v/vektor-slipstream)](https://www.npmjs.com/package/vektor-slipstream)
+[![downloads](https://img.shields.io/npm/dw/vektor-slipstream)](https://www.npmjs.com/package/vektor-slipstream)
 [![license](https://img.shields.io/badge/license-Commercial-blue)](https://vektormemory.com/product#pricing)
 
 ## Install
@@ -39,7 +40,83 @@ const delta = await memory.delta('project decisions', 7);
 const brief = await memory.briefing();
 ```
 
-## CLI
+---
+
+## CLI Chat — Persistent Memory Terminal
+
+Chat with any LLM with full memory across every session. Zero configuration.
+
+```bash
+npx vektor chat                          # start chat (auto-detects Ollama)
+npx vektor chat --provider claude        # use Anthropic Claude
+npx vektor chat --provider groq --model llama-3.3-70b-versatile
+npx vektor chat --provider gemini
+npx vektor chat --provider openai
+```
+
+### Providers
+
+| Provider | Details |
+|---|---|
+| `ollama` | Default — free, local, no API key. Auto-detects best installed model. |
+| `claude` | Anthropic Claude — set `ANTHROPIC_API_KEY` |
+| `openai` | OpenAI GPT — set `OPENAI_API_KEY` |
+| `groq` | Groq LLaMA — set `GROQ_API_KEY` (free tier available) |
+| `gemini` | Google Gemini — set `GEMINI_API_KEY` |
+
+Set a permanent default:
+```bash
+# Windows
+$env:VEKTOR_PROVIDER = "claude"
+
+# macOS/Linux
+export VEKTOR_PROVIDER=claude
+```
+
+### In-chat commands
+
+Type `/` to see available commands with autocomplete. Tab to select, arrow keys to navigate.
+
+| Command | Action |
+|---|---|
+| `/recall <query>` | Search MAGMA memory mid-conversation |
+| `/stats` | Show memory node count, edges, pinned |
+| `/briefing` | Generate memory briefing inline |
+| `/exit` | Exit chat (Ctrl+C also works) |
+
+### One-liner commands
+
+```bash
+# Store a fact
+npx vektor remember "I prefer TypeScript over JavaScript"
+npx vektor remember "deadline is Friday" --importance 5
+
+# Pipe support
+cat meeting-notes.txt | npx vektor remember
+
+# One-shot recall + LLM answer
+npx vektor ask "what stack am I using?"
+npx vektor ask "what did we decide about the database?"
+
+# Autonomous goal executor
+npx vektor agent "summarise everything I know about project Alpha"
+npx vektor agent "research AI memory tools" --steps 15 --provider groq
+```
+
+### Ollama auto-detection
+
+VEKTOR queries `http://localhost:11434/api/tags` and picks the best available model:
+`qwen3` → `qwen2` → `llama` → `mistral` → first available.
+
+Override:
+```bash
+$env:OLLAMA_MODEL = "qwen3.5:4b"
+export OLLAMA_MODEL=qwen3.5:4b
+```
+
+---
+
+## All CLI Commands
 
 ```bash
 npx vektor setup      # First-run wizard — licence, hardware, integrations
@@ -48,49 +125,110 @@ npx vektor test       # Test memory engine with progress bar
 npx vektor status     # System health check
 npx vektor mcp        # Start Claude Desktop MCP server
 npx vektor rem        # Run REM dream cycle
-npx vektor chat       # Persistent memory chat (all LLMs)
-npx vektor remember   # Store a fact: npx vektor remember "I prefer TypeScript"
-npx vektor ask        # Query memory: npx vektor ask "what stack am I using?"
-npx vektor agent      # Autonomous goal executor
+npx vektor chat       # Persistent memory chat (all LLMs)
+npx vektor remember   # Store a fact
+npx vektor ask        # Query memory + LLM answer
+npx vektor agent      # Autonomous goal executor
 npx vektor help       # All commands
 ```
 
-## CLOAK — Developer Context Layer for Claude Code
+---
+
+## Claude Desktop Extension (DXT)
+
+Install the `.dxt` extension for zero-config memory in every Claude Desktop session.
+
+**Install:** drag `vektor-slipstream.dxt` onto the Claude Desktop Extensions page.
+
+Once installed, Claude automatically:
+- Recalls relevant context at session start
+- Stores facts and decisions during conversation
+- Summarises at session end
 
-CLOAK is a 4-tool MCP layer that gives Claude Code persistent memory of your project.
-Every session starts with full context. Every error is remembered. Every wasted token is tracked.
+All 28 tools are available in Claude Desktop — no configuration needed beyond your licence key.
 
-### What it does
+**User config fields:**
 
-| Tool | Does exactly one thing |
+| Field | Purpose |
 |---|---|
-| `cloak_cortex` | Scans project files, builds a token-aware anatomy index in Vektor's entity graph |
-| `cloak_axon` | Session boundary handler — loads last context on start, saves MemCell on stop |
-| `cloak_cerebellum` | Pre-write enforcer — checks writes against known error patterns, auto-resolves fixes |
-| `cloak_token` | Token ledger — detects repeated reads and waste, one summary write per session |
+| `licence_key` | Your Polar licence key (required) |
+| `db_path` | Memory DB path (defaults to `~/vektor-slipstream-memory.db`) |
+| `project_path` | Default path for `cloak_cortex` project scanning (optional) |
 
-### Import
+Download the latest `.dxt` from [vektormemory.com/docs/dxt](https://vektormemory.com/docs/dxt).
 
-```js
-const { runCortex }        = require('vektor-slipstream/cloak/cortex');
-const { onSessionStart,
-        onSessionStop }    = require('vektor-slipstream/cloak/axon');
-const { checkWrite,
-        recordError }      = require('vektor-slipstream/cloak/cerebellum');
-const { getSessionSummary} = require('vektor-slipstream/cloak/token');
-
-// Clean terminal output (replaces emoji with box-drawing chars)
-const { createMemory }     = require('vektor-slipstream/boot');
-```
+---
+
+## MCP Tools — All 28
+
+### Memory Tools
 
-### Claude Code setup
+| Tool | Function |
+|---|---|
+| `vektor_recall` | Semantic search across MAGMA graph |
+| `vektor_store` | Store memory with importance score |
+| `vektor_graph` | Traverse associative memory graph |
+| `vektor_delta` | See what changed on a topic over time |
+| `vektor_briefing` | Generate morning briefing from recent memories |
+
+### CLOAK Core
+
+| Tool | Function |
+|---|---|
+| `cloak_fetch` | Stealth headless browser fetch via Playwright |
+| `cloak_fetch_smart` | Checks `llms.txt` first, falls back to stealth browser |
+| `cloak_render` | Full CSS/DOM layout sensor |
+| `cloak_diff` | Semantic diff of URL since last fetch |
+| `cloak_diff_text` | Structural diff between two text blobs |
+| `cloak_passport` | AES-256-GCM credential vault (get/set/delete/list) |
+| `tokens_saved` | Token efficiency ROI calculator |
+
+### Identity Tools
+
+| Tool | Function |
+|---|---|
+| `cloak_identity_create` | Create persistent browser fingerprint identity |
+| `cloak_identity_use` | Apply saved identity to a fetch call |
+| `cloak_identity_list` | List all saved identities with trust summary |
+
+### Behaviour Tools
+
+| Tool | Function |
+|---|---|
+| `cloak_inject_behaviour` | Human mouse/scroll injection for reCAPTCHA/Cloudflare bypass |
+| `cloak_behaviour_stats` | List available patterns and categories |
+| `cloak_load_pattern` | Load custom recorded behaviour pattern |
+| `cloak_pattern_stats` | Self-improving pattern store tier breakdown |
+| `cloak_pattern_list` | List patterns with scores and tier |
+| `cloak_pattern_prune` | Remove stale/low-scoring patterns |
+| `cloak_pattern_seed` | Seed store with built-in patterns |
+
+### CAPTCHA Tools
+
+| Tool | Function |
+|---|---|
+| `cloak_detect_captcha` | Detect CAPTCHA type and sitekey |
+| `cloak_solve_captcha` | Solve via vision AI (Claude/GPT-4o/2captcha) |
+
+### Compression & Cortex Tools
+
+| Tool | Function |
+|---|---|
+| `turbo_quant_compress` | PolarQuant vector compression (~75% smaller) |
+| `turbo_quant_stats` | Compression ratio and savings stats |
+| `cloak_cortex` | Scan project directory into MAGMA entity graph |
+| `cloak_cortex_anatomy` | Get cached file anatomy without rescanning |
+
+---
+
+## Claude Code Setup
 
 Add to `.claude/settings.json` in your project:
 
 ```json
 {
   "mcpServers": {
-    "cloak": {
+    "vektor": {
       "command": "node",
       "args": ["/path/to/node_modules/vektor-slipstream/index.js"],
       "env": {
@@ -98,70 +236,11 @@ Add to `.claude/settings.json` in your project:
         "CLOAK_PROJECT_PATH": "/path/to/your/project"
       }
     }
-  },
-  "hooks": {
-    "SessionStart": [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook SessionStart" }],
-    "Stop":         [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook Stop" }],
-    "PreToolUse":   [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PreToolUse" }],
-    "PostToolUse":  [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PostToolUse" }]
   }
 }
 ```
 
-### Usage
-
-```js
-// Scan project files into Vektor entity graph (call once on init)
-await cloak_cortex({})
-
-// Start session — loads last context automatically
-await cloak_axon({ action: 'start' })
-
-// Check before a risky write
-await cloak_cerebellum({
-  action: 'check',
-  content: '...code...',
-  filePath: 'src/auth.ts'
-})
-
-// Record a bug you just hit
-await cloak_cerebellum({
-  action: 'record_error',
-  description: 'Null ref on user.id when DB returns empty',
-  filePath: 'src/auth.ts',
-  errorType: 'null_reference',
-  fix: 'Add guard: if (user && user.id)'
-})
-
-// Save session with intent — the "why" not just the "what"
-await cloak_axon({
-  action: 'stop',
-  narrative: 'Fixed null reference in auth module'
-})
-
-// Check token waste
-await cloak_token({ action: 'summary' })
-```
-
-### Architecture
-
-```
-Claude Code
-    ↓ hooks + MCP tool calls
-CLOAK (4 tools, ~800 lines Node.js)
-    ↓ memory.remember() / memory.recall()
-Vektor / MAGMA
-    ↓ 4-layer graph (semantic, temporal, causal, entity)
-SQLite-vec (local, no cloud)
-```
-
-### DB growth
-
-CLOAK writes 3-5 nodes per session — not per operation.
-At 1 year of daily use: ~1,000 nodes. Sub-millisecond recall throughout.
-
-> ⚠️ **Concurrency warning**: Use stdio MCP (default). The HTTP mode
-> (`CLOAK_HTTP=1`) does not support concurrent multi-agent sessions.
+All 28 tools are available in Claude Code via this config.
 
 ---
 
@@ -177,37 +256,19 @@ At 1 year of daily use: ~1,000 nodes. Sub-millisecond recall throughout.
 
 ### Integrations
 
-- **Claude MCP** — `vektor_recall`, `vektor_store`, `vektor_graph`, `vektor_delta`
-- **Claude Code** — CLOAK 4-tool developer context layer (see above)
+- **Claude Desktop** — DXT extension, 28 tools, auto-memory system prompt
+- **Claude Code** — MCP server, all 28 tools
+- **CLI** — `chat`, `remember`, `ask`, `agent` commands
 - **LangChain** — v1 + v2 adapter included
 - **OpenAI Agents SDK** — drop-in integration
-- **Mistral** — `vektor_memoire` HTTP tool, localhost bridge
 - **Gemini · Groq · Ollama** — provider agnostic
 
-### Cloak (Sovereign Identity)
-
-- `cloak_fetch` — stealth headless browser fetch
-- `cloak_render` — computed CSS · post-JS DOM sensor
-- `cloak_passport` — AES-256-GCM credential vault, machine-bound
-- `cloak_diff` — semantic diff since last fetch
-- `tokens_saved` — ROI audit per session
-
-```js
-const { cloak_passport, cloak_fetch, tokens_saved } = require('vektor-slipstream/cloak');
-
-cloak_passport('GITHUB_TOKEN', 'ghp_xxxx');
-const token = cloak_passport('GITHUB_TOKEN');
-
-const { text, tokensSaved } = await cloak_fetch('https://example.com');
-
-const roi = tokens_saved({ raw_tokens: 10000, actual_tokens: 3000 });
-// → { reduction_pct: 70, cost_saved_usd: 0.0175, roi_multiple: 2.3 }
-```
+---
 
 ## Performance
 
 | Metric | Value |
-|--------|-------|
+|---|---|
 | Recall latency | ~8ms avg (local SQLite) |
 | Embedding cost | $0 — fully local ONNX |
 | Embedding latency | ~10ms GPU / ~25ms CPU |
@@ -222,15 +283,19 @@ Zero config. VEKTOR detects and uses the best available accelerator:
 - **Apple Silicon** — CoreML
 - **CPU** — optimised fallback, works everywhere
 
+---
+
 ## Licence
 
 Commercial licence. One-time payment of $159. Activates on up to 3 machines.
 Manage at [polar.sh](https://polar.sh).
 
-Purchase: [vektormemory.com/product#pricing](https://vektormemory.com/product#pricing)
-Docs: [vektormemory.com/docs](https://vektormemory.com/docs)
+Purchase: [vektormemory.com/product#pricing](https://vektormemory.com/product#pricing)  
+Docs: [vektormemory.com/docs](https://vektormemory.com/docs)  
 Support: hello@vektormemory.com
 
+---
+
 ## Research
 
 Built on peer-reviewed research:
@@ -238,4 +303,4 @@ Built on peer-reviewed research:
 - [MAGMA (arxiv:2601.03236)](https://arxiv.org/abs/2601.03236) — Multi-Graph Agentic Memory Architecture
 - [EverMemOS (arxiv:2601.02163)](https://arxiv.org/abs/2601.02163) — Self-Organizing Memory OS
 - [HippoRAG (arxiv:2405.14831)](https://arxiv.org/abs/2405.14831) — Neurobiologically Inspired Long-Term Memory (NeurIPS 2024)
-- [Mem0 (arxiv:2504.19413)](https://arxiv.org/abs/2504.19413) — Production-Ready Agent Memory
+- [Mem0 (arxiv:2504.19413)](https://arxiv.org/abs/2504.19413) — Production-Ready Agent Memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vektor-slipstream",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Hardware-accelerated persistent memory for AI agents. Local-first, zero cloud dependency, $0 embedding cost.",
   "main": "slipstream-core-extended.js",
   "types": "./types/index.d.ts",
@@ -72,7 +72,7 @@
   "dependencies": {
     "better-sqlite3": "^12.8.0",
     "onnxruntime-node": "^1.17.3",
-    "vektor-slipstream": "^1.4.2"
+    "vektor-slipstream": "^1.4.4"
   },
   "optionalDependencies": {
     "@anthropic-ai/sdk": "^0.82.0",

package/vektor-cli.js

@@ -1,482 +1,259 @@
-#!/usr/bin/env node
+/**
+ * vektor-cli.js  (v1.5.x patch)
+ * VEKTOR Slipstream
+ * CLI router — drop-in replacement for the v1.4.x router.
+ *
+ * New commands added in v1.5.x:
+ *   npx vektor agent --tools    full tool suite
+ *   npx vektor watch            filesystem watcher
+ *   npx vektor sync             P2P memory sync
+ *   npx vektor swarm            multi-agent coordination
+ *
+ * All existing v1.4.x commands (chat, remember, ask, agent) are preserved.
+ */
+
 'use strict';
 
-const path   = require('path');
-const os     = require('os');
-const fs     = require('fs');
-const PKG    = require('./package.json');
-const loader = require('./vektor-banner-loader');
-
-const command = process.argv[2] || 'help';
-
-// ── Colours ───────────────────────────────────────────────────────────────────
-
-const C = {
-  reset:  '\x1b[0m',
-  cyan:   '\x1b[36m',
-  green:  '\x1b[32m',
-  yellow: '\x1b[33m',
-  red:    '\x1b[31m',
-  dim:    '\x1b[2m',
-  bold:   '\x1b[1m',
-  orange: '\x1b[38;5;214m',
+const path = require('path');
+
+// ─── Command registry ─────────────────────────────────────────────────────────
+
+const COMMANDS = {
+  // ── v1.4.x (existing) ──────────────────────────────────────────────────
+  chat:     () => require('./vektor-cli-chat.js').runChat,
+  remember: () => require('./vektor-cli-chat.js').runRemember,
+  ask:      () => require('./vektor-cli-chat.js').runAsk,
+
+  // ── v1.5.x (new) ───────────────────────────────────────────────────────
+
+  /**
+   * npx vektor agent [goal] [--tools web,fs,code] [--continue]
+   * Autonomous agent with web search, file system, code execution.
+   */
+  agent: () => async (argv) => {
+    const { default: runAgent, main } = (() => {
+      try { return require('./vektor-agent.js'); } catch { return require('../vektor-agent.js'); }
+    })();
+    // Delegate to vektor-agent CLI main — it reads process.argv
+    await main?.() ?? runAgent({
+      goal: argv.filter(a => !a.startsWith('-')).join(' '),
+      tools: ['web', 'fs', 'code', 'memory'],
+      provider: process.env.VEKTOR_PROVIDER || 'ollama',
+    });
+  },
+
+  /**
+   * npx vektor watch [path] [--ext js,ts] [--no-llm]
+   * Filesystem watcher — auto-stores change summaries into MAGMA.
+   */
+  watch: () => async (_argv) => {
+    const { startWatch, parseArgs } = (() => {
+      try { return require('./vektor-watch.js'); } catch { return require('../vektor-watch.js'); }
+    })();
+    const opts = parseArgs(process.argv);
+    await startWatch(opts);
+  },
+
+  /**
+   * npx vektor sync --host [--pin X]
+   * npx vektor sync --connect <ip> [--pin X]
+   * Encrypted P2P memory sync between machines.
+   */
+  sync: () => async (_argv) => {
+    const { main } = (() => {
+      try { return require('./vektor-sync.js'); } catch { return require('../vektor-sync.js'); }
+    })();
+    await main?.();
+  },
+
+  /**
+   * npx vektor swarm "goal" [--agents 3] [--roles r1,r2,r3]
+   * Multi-agent swarm coordination.
+   */
+  swarm: () => async (_argv) => {
+    const { main } = (() => {
+      try { return require('./vektor-swarm.js'); } catch { return require('../vektor-swarm.js'); }
+    })();
+    await main?.();
+  },
+
+  // ── Utility ────────────────────────────────────────────────────────────
+
+  providers: () => async (_argv) => {
+    await checkProviders();
+  },
+
+  version: () => async (_argv) => {
+    const pkg = safeRequirePackageJson();
+    console.log(`VEKTOR Slipstream v${pkg.version || '1.5.0'}`);
+  },
+
+  help: () => async (_argv) => {
+    printHelp();
+  },
 };
-const cyan   = s => C.cyan   + s + C.reset;
-const green  = s => C.green  + s + C.reset;
-const yellow = s => C.yellow + s + C.reset;
-const red    = s => C.red    + s + C.reset;
-const dim    = s => C.dim    + s + C.reset;
-const bold   = s => C.bold   + s + C.reset;
-const orange = s => C.orange + s + C.reset;
-
-// Banner is printed automatically by vektor-banner-loader on require
-
-function printBox() {
-  loader.complete('Ready');
-  console.log(cyan('  +------------------------------------------------------+'));
-  console.log(cyan('  |') + bold('         VEKTOR SLIPSTREAM CLI                        ') + cyan('|'));
-  console.log(cyan('  +------------------------------------------------------+'));
-  console.log(dim('  v' + PKG.version + ' . vektormemory.com'));
-  console.log('');
-}
 
-// ── Help ──────────────────────────────────────────────────────────────────────
+// ─── Provider checker ─────────────────────────────────────────────────────────
 
-async function cmdHelp() {
-  printBox();
-  console.log(bold('  MEMORY COMMANDS\n'));
+async function checkProviders() {
+  const C = { green: '\x1b[32m', red: '\x1b[31m', dim: '\x1b[2m', reset: '\x1b[0m', bold: '\x1b[1m' };
+  console.log(`\n${C.bold}VEKTOR Provider Status${C.reset}\n`);
 
-  const memoryCmds = [
-    ['chat',        'Persistent memory chat — all conversations stored in MAGMA graph'],
-    ['remember',    'Store a fact instantly: npx vektor remember "I prefer TypeScript"'],
-    ['ask',         'Ask a question using your memory: npx vektor ask "what stack am I using?"'],
-    ['agent',       'Autonomous goal executor: npx vektor agent "research X and summarise"'],
-    ['briefing',    'Generate a morning briefing from recent memories'],
-    ['rem',         'Run the REM dream cycle — compress and consolidate memories'],
-    ['tui',         'Launch the interactive memory browser (terminal UI)'],
+  const checks = [
+    { name: 'Claude (Anthropic)', key: 'ANTHROPIC_API_KEY',  test: () => testClaude() },
+    { name: 'OpenAI',             key: 'OPENAI_API_KEY',     test: () => testOpenAI() },
+    { name: 'Groq',               key: 'GROQ_API_KEY',       test: () => testGroq() },
+    { name: 'Google Gemini',      key: 'GEMINI_API_KEY',     test: () => testGemini() },
+    { name: 'Ollama (local)',     key: null,                 test: () => testOllama() },
   ];
 
-  memoryCmds.forEach(([cmd, desc]) => {
-    console.log('  ' + cyan(('npx vektor ' + cmd).padEnd(26)) + dim(desc));
-  });
-
-  console.log('');
-  console.log(bold('  SYSTEM COMMANDS\n'));
-
-  const sysCmds = [
-    ['setup',      'First-run wizard — activate licence, test memory, configure integrations'],
-    ['activate',   'Activate your licence key on this machine'],
-    ['deactivate', "Free up this machine's activation slot"],
-    ['status',     'Show licence status, memory stats, and system info'],
-    ['test',       'Run a quick memory test (remember + recall + briefing)'],
-    ['mcp',        'Start the Claude MCP server (for Claude Desktop)'],
-    ['help',       'Show this help message'],
-  ];
-
-  sysCmds.forEach(([cmd, desc]) => {
-    console.log('  ' + cyan(('npx vektor ' + cmd).padEnd(26)) + dim(desc));
-  });
-
-  console.log('');
-  console.log(bold('  CHAT PROVIDERS\n'));
-  console.log('  ' + cyan('--provider claude ') + '  ' + dim('Anthropic Claude  (ANTHROPIC_API_KEY)'));
-  console.log('  ' + cyan('--provider openai ') + '  ' + dim('OpenAI GPT        (OPENAI_API_KEY)'));
-  console.log('  ' + cyan('--provider groq   ') + '  ' + dim('Groq LLaMA        (GROQ_API_KEY)'));
-  console.log('  ' + cyan('--provider gemini ') + '  ' + dim('Google Gemini     (GEMINI_API_KEY)'));
-  console.log('  ' + cyan('--provider ollama ') + '  ' + dim('Local Ollama      (free, ollama serve)'));
-
-  console.log('');
-  console.log(bold('  ENVIRONMENT\n'));
-  console.log('  ' + cyan('VEKTOR_LICENCE_KEY') + '  ' + dim('Your Polar licence key'));
-  console.log('  ' + cyan('VEKTOR_DB_PATH    ') + '  ' + dim('Path to memory database (default: ~/vektor-slipstream-memory.db)'));
-  console.log('  ' + cyan('VEKTOR_PROVIDER   ') + '  ' + dim('Default LLM provider (default: ollama)'));
-  console.log('  ' + cyan('VEKTOR_AGENT_ID   ') + '  ' + dim('Agent identifier (default: vektor-cli)'));
-  console.log('');
-  console.log(bold('  EXAMPLES\n'));
-  console.log(dim('  # Start chatting with persistent memory (uses Ollama by default)'));
-  console.log('  npx vektor chat\n');
-  console.log(dim('  # Chat with Claude'));
-  console.log('  npx vektor chat --provider claude\n');
-  console.log(dim('  # Store a fact instantly'));
-  console.log('  npx vektor remember "Client deadline is April 20th" --importance 5\n');
-  console.log(dim('  # Ask your memory a question'));
-  console.log('  npx vektor ask "what projects am I working on?"\n');
-  console.log(dim('  # Run an autonomous research agent'));
-  console.log('  npx vektor agent "research VEKTOR competitors and summarise findings"\n');
-  console.log(dim('  # Pipe content into memory'));
-  console.log('  cat README.md | npx vektor remember\n');
-  console.log(dim('  # Connect to Claude Desktop'));
-  console.log('  npx vektor mcp\n');
-  console.log('  ' + dim('Purchase at: https://vektormemory.com/product#pricing'));
-  console.log('');
-}
-
-// ── Status ────────────────────────────────────────────────────────────────────
-
-async function cmdStatus() {
-  printBox();
-  console.log(bold('  SYSTEM STATUS\n'));
-
-  const nodeVer = parseInt(process.version.slice(1));
-  const nodeOk  = nodeVer >= 18;
-  console.log('  Node.js       ' + (nodeOk ? green('✓ ' + process.version) : red('✗ ' + process.version + ' (requires >=18)')));
-
-  const cacheFile = path.join(os.homedir(), '.vektor', 'licence.json');
-  const hasCache  = fs.existsSync(cacheFile);
-  console.log('  Licence cache ' + (hasCache ? green('✓ found') : yellow('– not found')) + dim(' (' + cacheFile + ')'));
-
-  const envKey = process.env.VEKTOR_LICENCE_KEY;
-  console.log('  Licence env   ' + (envKey ? green('✓ VEKTOR_LICENCE_KEY set') : dim('– not set')));
-
-  const dbPath = process.env.VEKTOR_DB_PATH ||
-    path.join(os.homedir(), 'vektor-slipstream-memory.db');
-  const hasDb = fs.existsSync(dbPath);
-  console.log('  Memory DB     ' + (hasDb ? green('✓ ' + dbPath) : dim('– not found (run: npx vektor test)')));
-
-  const vaultFile = path.join(os.homedir(), '.vektor', 'vault.enc');
-  console.log('  Cloak vault   ' + (fs.existsSync(vaultFile) ? green('✓ found') : dim('– not initialised')));
-
-  let hasPw = false;
-  try { require('playwright'); hasPw = true; } catch (_) {}
-  console.log('  Playwright    ' + (hasPw ? green('✓ installed') : yellow('– optional (npx playwright install chromium)')));
-
-  let hasOnnx = false;
-  try { require('onnxruntime-node'); hasOnnx = true; } catch (_) {}
-  console.log('  ONNX runtime  ' + (hasOnnx ? green('✓ installed') : red('✗ missing (npm install onnxruntime-node)')));
-
-  // Provider check
-  const provider = process.env.VEKTOR_PROVIDER || 'ollama';
-  console.log('  LLM provider  ' + cyan(provider));
-  if (provider === 'ollama') {
+  for (const check of checks) {
+    const hasKey = check.key ? !!process.env[check.key] : true;
+    if (!hasKey) {
+      console.log(`  ${C.red}✗${C.reset}  ${check.name}  ${C.dim}(${check.key} not set)${C.reset}`);
+      continue;
+    }
+    process.stdout.write(`  ⏳ ${check.name}…`);
     try {
-      const res = await fetch('http://localhost:11434/api/tags', { signal: AbortSignal.timeout(2000) });
-      const data = await res.json();
-      const models = data.models?.map(m => m.name).join(', ') || 'none';
-      console.log('  Ollama models ' + green('✓ running') + dim(' — ' + models));
-    } catch {
-      console.log('  Ollama        ' + yellow('– not running (start with: ollama serve)'));
+      const model = await check.test();
+      process.stdout.write(`\r  ${C.green}✓${C.reset}  ${check.name}  ${C.dim}${model}${C.reset}\n`);
+    } catch (err) {
+      process.stdout.write(`\r  ${C.red}✗${C.reset}  ${check.name}  ${C.dim}${err.message}${C.reset}\n`);
     }
   }
-
-  console.log('\n  ' + cyan('vektor-slipstream') + ' ' + dim('v' + PKG.version));
   console.log('');
 }
 
-// ── Activate ──────────────────────────────────────────────────────────────────
-
-async function cmdActivate() {
-  printBox();
-  console.log('  Activating licence...\n');
-  try {
-    const { resolveAndValidateLicence } = require('./vektor-licence-prompt');
-    const { validateLicence }           = require('./vektor-licence');
-    await resolveAndValidateLicence(validateLicence);
-    console.log(green('  ✓ Licence activated successfully.'));
-    console.log(dim('  Run: npx vektor status'));
-  } catch (e) {
-    console.error(red('  ✗ Activation failed: ') + e.message);
-    process.exit(1);
-  }
-  console.log('');
+async function testClaude() {
+  const res = await fetchTimeout('https://api.anthropic.com/v1/models', {
+    headers: { 'x-api-key': process.env.ANTHROPIC_API_KEY, 'anthropic-version': '2023-06-01' },
+  }, 5000);
+  const j = await res.json();
+  const m = j.data?.[0]?.id || 'connected';
+  return m;
 }
-
-// ── Deactivate ────────────────────────────────────────────────────────────────
-
-async function cmdDeactivate() {
-  printBox();
-  const key = process.env.VEKTOR_LICENCE_KEY;
-  if (!key) {
-    console.error(red('  ✗ VEKTOR_LICENCE_KEY not set.'));
-    console.log(dim('  Set it: set VEKTOR_LICENCE_KEY=YOUR-KEY (Windows) or export VEKTOR_LICENCE_KEY=YOUR-KEY (Unix)'));
-    process.exit(1);
-  }
-  try {
-    const { deactivateMachine } = require('./vektor-licence');
-    await deactivateMachine(key);
-    console.log(green('  ✓ Machine deactivated. Activation slot freed.'));
-  } catch (e) {
-    console.error(red('  ✗ Deactivation error: ') + e.message);
-    process.exit(1);
-  }
-  console.log('');
+async function testOpenAI() {
+  const res = await fetchTimeout('https://api.openai.com/v1/models', {
+    headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
+  }, 5000);
+  const j = await res.json();
+  return j.data?.[0]?.id || 'connected';
 }
-
-// ── Test ──────────────────────────────────────────────────────────────────────
-
-async function cmdTest() {
-  printBox();
-  console.log('  Running memory test...\n');
-
-  const steps = ['Boot engine', 'Store memory', 'Recall memory', 'Briefing', 'Cleanup'];
-  let step = 0;
-
-  const bar = (label) => {
-    const pct    = Math.round((step / steps.length) * 100);
-    const filled = Math.round((step / steps.length) * 30);
-    const b      = '[' + '#'.repeat(filled) + '-'.repeat(30 - filled) + ']';
-    process.stdout.write('\r  ' + cyan(b) + ' ' + String(pct).padStart(3) + '% ' + dim(label || steps[step] || 'Done') + '   ');
-  };
-
-  bar();
-
-  try {
-    const { createMemory } = require('./slipstream-core');
-    const testDb = path.join(os.tmpdir(), 'vektor-test-' + Date.now() + '.db');
-
-    const memory = await createMemory({
-      agentId:    'vektor-cli-test',
-      dbPath:     testDb,
-      silent:     true,
-      licenceKey: process.env.VEKTOR_LICENCE_KEY,
-    });
-    step++; bar(); process.stdout.write('\n'); console.log(green('  ✓ Memory engine booted'));
-
-    const { id } = await memory.remember('VEKTOR CLI test — memory is working correctly', { importance: 3 });
-    step++; bar(); process.stdout.write('\n'); console.log(green('  ✓ Stored memory (id: ' + id + ')'));
-
-    const results = await memory.recall('CLI test memory working', 3);
-    step++; bar(); process.stdout.write('\n');
-    if (results.length > 0) {
-      console.log(green('  ✓ Recalled ' + results.length + ' result(s) — top score: ' + results[0].score.toFixed(4)));
-    } else {
-      console.log(yellow('  ⚠ Recall returned 0 results'));
-    }
-
-    try {
-      await memory.briefing();
-      step++; bar(); process.stdout.write('\n'); console.log(green('  ✓ Briefing generated'));
-    } catch (_) {
-      step++; bar(); process.stdout.write('\n'); console.log(dim('  – Briefing skipped (not enough memories)'));
-    }
-
-    try { if (memory.db) memory.db.close(); } catch (_) {}
-    await new Promise(r => setTimeout(r, 200));
-    try { fs.unlinkSync(testDb); } catch (_) {}
-    step++; bar('Done'); process.stdout.write('\n'); console.log(green('  ✓ Test database cleaned up'));
-
-    console.log('\n' + green('  ✓ All tests passed. VEKTOR is working correctly.\n'));
-  } catch (e) {
-    process.stdout.write('\n');
-    console.error(red('\n  ✗ Test failed: ') + e.message);
-    if (e.message.includes('better-sqlite3')) {
-      console.log(yellow('  Fix: npm rebuild better-sqlite3'));
-    }
-    if (e.message.includes('licence')) {
-      console.log(yellow('  Fix: npx vektor activate'));
-    }
-    process.exit(1);
-  }
+async function testGroq() {
+  const res = await fetchTimeout('https://api.groq.com/openai/v1/models', {
+    headers: { Authorization: `Bearer ${process.env.GROQ_API_KEY}` },
+  }, 5000);
+  const j = await res.json();
+  return j.data?.[0]?.id || 'connected';
+}
+async function testGemini() {
+  const res = await fetchTimeout(`https://generativelanguage.googleapis.com/v1beta/models?key=${process.env.GEMINI_API_KEY}`, {}, 5000);
+  const j = await res.json();
+  return j.models?.[0]?.name || 'connected';
+}
+async function testOllama() {
+  const res = await fetchTimeout('http://localhost:11434/api/tags', {}, 3000);
+  const j = await res.json();
+  const models = j.models?.map(m => m.name) || [];
+  if (!models.length) throw new Error('No models installed. Run: ollama pull qwen3');
+  return models.join(', ');
 }
 
-// ── MCP ───────────────────────────────────────────────────────────────────────
+function fetchTimeout(url, opts, ms) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), ms);
+  return fetch(url, { ...opts, signal: ctrl.signal }).finally(() => clearTimeout(t));
+}
 
-async function cmdMcp() {
-  const mcpScript = path.join(__dirname, 'examples', 'example-claude-mcp.js');
-  if (!fs.existsSync(mcpScript)) {
-    console.error(red('  ✗ MCP server not found: ') + mcpScript);
-    process.exit(1);
-  }
-  process.argv = ['node', mcpScript, '--mcp'];
-  require(mcpScript);
+// ─── Help ─────────────────────────────────────────────────────────────────────
+
+function printHelp() {
+  const C = { bold: '\x1b[1m', dim: '\x1b[2m', cyan: '\x1b[36m', green: '\x1b[32m', reset: '\x1b[0m' };
+  console.log(`
+${C.bold}VEKTOR Slipstream CLI${C.reset}
+
+${C.bold}Memory:${C.reset}
+  ${C.cyan}npx vektor remember${C.reset} "text"          Store a fact into MAGMA
+  ${C.cyan}npx vektor ask${C.reset} "question"           Recall + LLM answer
+  ${C.cyan}npx vektor chat${C.reset}                     Interactive persistent-memory chat
+
+${C.bold}Agent (v1.5):${C.reset}
+  ${C.cyan}npx vektor agent${C.reset} "goal"              Basic autonomous agent
+  ${C.cyan}npx vektor agent${C.reset} "goal" ${C.dim}--tools${C.reset}      Full tool suite (web+fs+code)
+  ${C.cyan}npx vektor agent${C.reset} "goal" ${C.dim}--continue${C.reset}   Resume last session
+  ${C.cyan}npx vektor agent${C.reset} "goal" ${C.dim}--tools web,fs,code${C.reset}
+
+${C.bold}Watch (v1.5):${C.reset}
+  ${C.cyan}npx vektor watch${C.reset} [path]              Watch filesystem, auto-store changes
+  ${C.cyan}npx vektor watch${C.reset} src/ ${C.dim}--ext ts,tsx${C.reset}
+  ${C.cyan}npx vektor watch${C.reset} ${C.dim}--no-llm${C.reset}            Heuristic summaries only
+
+${C.bold}Sync (v1.5):${C.reset}
+  ${C.cyan}npx vektor sync${C.reset} --host               Listen for incoming sync
+  ${C.cyan}npx vektor sync${C.reset} --connect <ip>       Sync with host machine
+  ${C.cyan}npx vektor sync${C.reset} --host ${C.dim}--pin 123456${C.reset}
+
+${C.bold}Swarm (v1.5):${C.reset}
+  ${C.cyan}npx vektor swarm${C.reset} "goal"              Multi-agent coordination
+  ${C.cyan}npx vektor swarm${C.reset} "goal" ${C.dim}--agents 4${C.reset}
+  ${C.cyan}npx vektor swarm${C.reset} "goal" ${C.dim}--roles researcher,coder,reviewer${C.reset}
+
+${C.bold}Utilities:${C.reset}
+  ${C.cyan}npx vektor providers${C.reset}                 Test all API key connections
+  ${C.cyan}npx vektor version${C.reset}                   Show version
+  ${C.cyan}npx vektor help${C.reset}                      Show this help
+
+${C.bold}Providers:${C.reset}  ${C.dim}--provider claude|openai|groq|gemini|ollama${C.reset}
+`);
 }
 
-// ── TUI ───────────────────────────────────────────────────────────────────────
+// ─── Helpers ──────────────────────────────────────────────────────────────────
 
-async function cmdTui() {
-  const tuiScript = path.join(__dirname, 'vektor-tui.js');
-  if (!fs.existsSync(tuiScript)) {
-    console.error(red('  ✗ TUI not found: ') + tuiScript);
-    process.exit(1);
+function safeRequirePackageJson() {
+  const candidates = [
+    path.join(__dirname, 'package.json'),
+    path.join(__dirname, '..', 'package.json'),
+  ];
+  for (const c of candidates) {
+    try { return require(c); } catch { /* skip */ }
   }
-  loader.complete('Launching TUI');
-  require(tuiScript);
+  return {};
 }
 
-// ── REM ───────────────────────────────────────────────────────────────────────
-
-async function cmdRem() {
-  printBox();
-  console.log('  Running REM dream cycle...\n');
-  try {
-    const { createMemory } = require('./boot-patch');
-    const dbPath = process.env.VEKTOR_DB_PATH ||
-      path.join(os.homedir(), 'vektor-slipstream-memory.db');
-
-    if (!fs.existsSync(dbPath)) {
-      console.error(yellow('  ⚠  No memory database found at: ' + dbPath));
-      console.log(dim('  Run: npx vektor test  to create one'));
-      process.exit(1);
-    }
-
-    const memory = await createMemory({
-      agentId:    process.env.VEKTOR_AGENT_ID || 'default',
-      dbPath,
-      silent:     true,
-      licenceKey: process.env.VEKTOR_LICENCE_KEY,
-    });
-
-    console.log('  ' + dim('┌─ Phase 1/4  Auditing memory graph...'));
-    const stats  = await memory.stats();
-    const total  = stats.total || 0;
-    console.log(dim('  │  Total nodes: ' + total));
+// ─── CLI dispatcher ───────────────────────────────────────────────────────────
 
-    if (total === 0) {
-      console.log(green('  └─ Memory graph is empty — nothing to consolidate\n'));
-      return;
-    }
-
-    console.log('  ' + dim('├─ Phase 2/4  Scanning recent activity...'));
-    const recent = await memory.recent(20);
-    console.log(dim('  │  Recent nodes scanned: ' + (recent ? recent.length : 0)));
-
-    console.log('  ' + dim('├─ Phase 3/4  Pruning noise nodes...'));
-    let pruned = 0;
-    const NOISE = [
-      'cloak warmup probe',
-      'VEKTOR CLI test — memory is working correctly',
-    ];
-    for (const pattern of NOISE) {
-      try {
-        const nodes = await memory.recall(pattern, 10);
-        if (!nodes || !nodes.length) continue;
-        for (const node of nodes) {
-          if (node.content && NOISE.some(n => node.content.includes(n))) {
-            if (node.id) { await memory.remove(node.id); pruned++; }
-          }
-        }
-      } catch { /* non-fatal */ }
-    }
-    console.log(dim('  │  Noise nodes pruned: ' + pruned));
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd  = argv[0];
 
-    console.log('  ' + dim('├─ Phase 4/4  Generating consolidation summary...'));
-    let briefSnippet = '';
-    try {
-      const brief = await memory.briefing();
-      if (brief) briefSnippet = brief.slice(0, 120) + (brief.length > 120 ? '...' : '');
-    } catch { /* non-fatal */ }
-
-    const statsAfter = await memory.stats();
-    const totalAfter = statsAfter.total || 0;
-    const delta      = total - totalAfter;
-
-    console.log(green('  └─ REM cycle complete\n'));
-    console.log('  ' + dim('Before:') + '  ' + total + ' nodes');
-    console.log('  ' + dim('After: ') + '  ' + totalAfter + ' nodes');
-    console.log('  ' + dim('Pruned:') + '  ' + pruned + ' noise nodes');
-    if (delta > pruned) {
-      console.log('  ' + dim('AUDN:  ') + '  ' + (delta - pruned) + ' duplicates resolved');
-    }
-    if (briefSnippet) {
-      console.log('\n  ' + dim('Briefing: ') + briefSnippet);
-    }
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    printHelp();
+    return;
+  }
+  if (cmd === '--version' || cmd === '-v') {
+    const pkg = safeRequirePackageJson();
+    console.log(`v${pkg.version || '1.5.0'}`);
+    return;
+  }
 
-  } catch (e) {
-    console.error(red('  ✗ REM error: ') + e.message);
+  const factory = COMMANDS[cmd];
+  if (!factory) {
+    console.error(`Unknown command: ${cmd}\nRun 'npx vektor help' for usage.`);
     process.exit(1);
   }
-  console.log('');
-}
-
-// ── Briefing ──────────────────────────────────────────────────────────────────
 
-async function cmdBriefing() {
-  printBox();
-  console.log('  Generating memory briefing...\n');
   try {
-    const { createMemory } = require('./slipstream-core');
-    const dbPath = process.env.VEKTOR_DB_PATH ||
-      path.join(os.homedir(), 'vektor-slipstream-memory.db');
-
-    if (!fs.existsSync(dbPath)) {
-      console.error(yellow('  ⚠ No memory database found at: ' + dbPath));
-      console.log(dim('  Run: npx vektor test  to create one'));
-      process.exit(1);
-    }
-
-    const memory = await createMemory({
-      agentId:    process.env.VEKTOR_AGENT_ID || 'default',
-      dbPath,
-      silent:     true,
-      licenceKey: process.env.VEKTOR_LICENCE_KEY,
-    });
-
-    const brief = await memory.briefing();
-    if (brief) {
-      console.log(bold('  ── MEMORY BRIEFING ──────────────────────────────────\n'));
-      console.log('  ' + brief.split('\n').join('\n  '));
-      console.log('\n  ' + dim('─────────────────────────────────────────────────────'));
-    } else {
-      console.log(dim('  No briefing available — add more memories first.'));
-      console.log(dim('  Try: npx vektor chat  or  npx vektor remember "some fact"'));
-    }
-  } catch (e) {
-    console.error(red('  ✗ Briefing error: ') + e.message);
+    const handler = factory();
+    await handler(argv.slice(1));
+  } catch (err) {
+    console.error(`Error in '${cmd}': ${err.message}`);
+    if (process.env.DEBUG) console.error(err);
     process.exit(1);
   }
-  console.log('');
-}
-
-// ── Setup ─────────────────────────────────────────────────────────────────────
-
-async function cmdSetup() {
-  require('./vektor-setup');
-}
-
-// ── Chat / Remember / Ask / Agent — from vektor-cli-chat.js ──────────────────
-
-async function cmdChat()     { const { cmdChat     } = require('./vektor-cli-chat'); await cmdChat(process.argv); }
-async function cmdRemember() { const { cmdRemember } = require('./vektor-cli-chat'); await cmdRemember(process.argv); }
-async function cmdAsk()      { const { cmdAsk      } = require('./vektor-cli-chat'); await cmdAsk(process.argv); }
-async function cmdAgent()    { const { cmdAgent    } = require('./vektor-cli-chat'); await cmdAgent(process.argv); }
-
-// ── Pipe support — cat file.txt | npx vektor remember ────────────────────────
-async function handlePipe() {
-  if (process.stdin.isTTY) return false;
-  const chunks = [];
-  for await (const chunk of process.stdin) chunks.push(chunk);
-  const piped = chunks.join('').trim();
-  if (!piped) return false;
-  // Inject piped content as the text argument
-  process.argv.push(piped);
-  return true;
 }
 
-// ── Router ────────────────────────────────────────────────────────────────────
-
-const commands = {
-  help:       cmdHelp,
-  status:     cmdStatus,
-  activate:   cmdActivate,
-  deactivate: cmdDeactivate,
-  test:       cmdTest,
-  mcp:        cmdMcp,
-  tui:        cmdTui,
-  rem:        cmdRem,
-  briefing:   cmdBriefing,
-  setup:      cmdSetup,
-  // New commands
-  chat:       cmdChat,
-  remember:   cmdRemember,
-  ask:        cmdAsk,
-  agent:      cmdAgent,
-};
-
-const fn = commands[command];
-if (!fn) {
-  console.error(red('\n  ✗ Unknown command: ') + bold(command));
-  console.log(dim('  Run: npx vektor help\n'));
-  process.exit(1);
+if (require.main === module) {
+  main();
 }
 
-// Handle pipe for remember command
-if (command === 'remember') {
-  handlePipe().then(() => fn()).catch(e => {
-    console.error(red('\n  ✗ Error: ') + e.message);
-    process.exit(1);
-  });
-} else {
-  fn().catch(e => {
-    console.error(red('\n  ✗ Error: ') + e.message);
-    process.exit(1);
-  });
-}
+module.exports = { COMMANDS, main };

package/vektor-setup.js

@@ -250,6 +250,10 @@ async function main() {
   console.log(dim('  const ctx = await memory.recall(\'coding preferences\');'));
   console.log('');
   console.log('  Commands:');
+  console.log(`  ${cyan('npx vektor chat')}     — persistent memory chat (Claude, Ollama, GPT, Groq, Gemini)`);
+  console.log(`  ${cyan('npx vektor remember')} — store a fact: npx vektor remember "I prefer TypeScript"`);
+  console.log(`  ${cyan('npx vektor ask')}      — query memory: npx vektor ask "what stack am I using?"`);
+  console.log(`  ${cyan('npx vektor agent')}    — autonomous goal executor`);
   console.log(`  ${cyan('npx vektor status')}   — check system health`);
   console.log(`  ${cyan('npx vektor test')}     — run memory test`);
   console.log(`  ${cyan('npx vektor mcp')}      — start Claude MCP server`);
@@ -263,4 +267,4 @@ async function main() {
 main().catch(e => {
   console.error(red('\n  Setup error: ') + e.message);
   process.exit(1);
-});
+});