jasper-recall 0.3.1 → 0.3.3

package/README.md

@@ -150,6 +150,36 @@ summarize-old --min-size 1000    # Only summarize files larger than 1000 chars
 - Rule-based summarization (no LLM required)
 - Preserves headings, bullets, dates, and key markers
 
+### doctor (v0.3.2+)
+
+System health check and auto-repair:
+
+```bash
+npx jasper-recall doctor              # Check system health (default)
+npx jasper-recall doctor --fix        # Auto-repair issues
+npx jasper-recall doctor --dry-run    # Verbose mode, show exact commands
+```
+
+**Default mode** (no flags):
+- Shows ✅/⚠️/❌ status for all checks
+- For issues found, suggests what `--fix` would do
+- Example: `❌ ChromaDB not installed → run with --fix to install`
+
+**Fix mode** (`--fix`):
+- Automatically repairs fixable issues:
+  - Creates Python venv if missing: `python3 -m venv ~/.openclaw/rag-env`
+  - Installs ChromaDB: `pip install chromadb`
+  - Installs sentence-transformers: `pip install sentence-transformers`
+  - Creates required directories (chroma-db, memory)
+  - Runs initial index if no collections exist
+- Shows what it fixed: `🔧 Installed ChromaDB via pip`
+- Non-fixable issues show manual instructions: `❌ Node.js <18 — please upgrade manually`
+
+**Dry-run mode** (`--dry-run`):
+- Same as default, but more verbose
+- Shows exact commands that `--fix` would run
+- Example: `Would run: ~/.openclaw/rag-env/bin/pip install chromadb`
+
 ### sync-shared (v0.2.0+)
 
 Extract `[public]` tagged entries to shared memory:

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jasper-recall
-version: 0.3.0
+version: 0.3.1
 description: Local RAG system for agent memory using ChromaDB and sentence-transformers. v0.3.0 adds multi-agent mesh (N agents sharing memory), OpenClaw plugin with autoRecall, and agent-specific collections. Commands: recall, index-digests, digest-sessions, privacy-check, sync-shared, serve, recall-mesh.
 ---
 

package/cli/doctor.js

@@ -102,10 +102,20 @@ function countMemoryFiles() {
   }
 }
 
-function runDoctor() {
+function runDoctor(options = {}) {
+  const { fix = false, dryRun = false } = options;
+  const verbose = dryRun;
+  
   console.log('🏥 Jasper Recall Doctor\n');
   
+  if (fix) {
+    console.log('🔧 Fix mode enabled - will attempt to repair issues\n');
+  } else if (dryRun) {
+    console.log('👁️  Dry-run mode - showing what --fix would do\n');
+  }
+  
   const checks = [];
+  const fixes = [];
   
   // Node.js version check
   const nodeResult = exec('node --version');
@@ -115,7 +125,9 @@ function runDoctor() {
     label: 'Node.js',
     status: nodeOk ? '✅' : '❌',
     value: nodeResult.success ? `v${nodeVersion}` : 'not found',
-    ok: nodeOk
+    ok: nodeOk,
+    fixable: false,
+    fixMessage: 'Please upgrade Node.js manually: https://nodejs.org/'
   });
   
   // Python version check
@@ -127,7 +139,32 @@ function runDoctor() {
     label: 'Python',
     status: pythonOk ? '✅' : '❌',
     value: pythonVersion || 'not found',
-    ok: pythonOk
+    ok: pythonOk,
+    fixable: false,
+    fixMessage: 'Please install Python 3: https://www.python.org/downloads/'
+  });
+  
+  // Virtual environment check
+  const venvExists = fs.existsSync(VENV_PATH);
+  checks.push({
+    label: 'Venv',
+    status: venvExists ? '✅' : '❌',
+    value: venvExists ? VENV_PATH : 'not found',
+    ok: venvExists,
+    fixable: !venvExists && pythonOk,
+    fixMessage: !venvExists ? `create virtual environment at ${VENV_PATH}` : null,
+    fixCommand: `python3 -m venv ${VENV_PATH}`,
+    fixAction: () => {
+      console.log(`  🔧 Creating virtual environment...`);
+      const result = exec(`python3 -m venv ${VENV_PATH}`, { silent: false });
+      if (result.success) {
+        console.log(`  ✅ Virtual environment created at ${VENV_PATH}`);
+        return true;
+      } else {
+        console.log(`  ❌ Failed to create virtual environment`);
+        return false;
+      }
+    }
   });
   
   // ChromaDB check
@@ -140,7 +177,21 @@ function runDoctor() {
     label: 'ChromaDB',
     status: chromaOk ? '✅' : '❌',
     value: chromaVersion ? `installed (${chromaVersion})` : 'not installed',
-    ok: chromaOk
+    ok: chromaOk,
+    fixable: !chromaOk && venvExists,
+    fixMessage: !chromaOk ? 'install chromadb via pip' : null,
+    fixCommand: `${pipPath} install chromadb`,
+    fixAction: () => {
+      console.log(`  🔧 Installing ChromaDB...`);
+      const result = exec(`${pipPath} install chromadb`, { silent: false });
+      if (result.success) {
+        console.log(`  ✅ ChromaDB installed successfully`);
+        return true;
+      } else {
+        console.log(`  ❌ Failed to install ChromaDB`);
+        return false;
+      }
+    }
   });
   
   // Sentence-transformers check
@@ -152,16 +203,21 @@ function runDoctor() {
     label: 'Transformers',
     status: transformersOk ? '✅' : '❌',
     value: transformersVersion ? 'sentence-transformers installed' : 'not installed',
-    ok: transformersOk
-  });
-  
-  // Virtual environment check
-  const venvExists = fs.existsSync(VENV_PATH);
-  checks.push({
-    label: 'Venv',
-    status: venvExists ? '✅' : '❌',
-    value: venvExists ? VENV_PATH : 'not found',
-    ok: venvExists
+    ok: transformersOk,
+    fixable: !transformersOk && venvExists,
+    fixMessage: !transformersOk ? 'install sentence-transformers via pip' : null,
+    fixCommand: `${pipPath} install sentence-transformers`,
+    fixAction: () => {
+      console.log(`  🔧 Installing sentence-transformers...`);
+      const result = exec(`${pipPath} install sentence-transformers`, { silent: false });
+      if (result.success) {
+        console.log(`  ✅ sentence-transformers installed successfully`);
+        return true;
+      } else {
+        console.log(`  ❌ Failed to install sentence-transformers`);
+        return false;
+      }
+    }
   });
   
   // ChromaDB directory check
@@ -171,7 +227,21 @@ function runDoctor() {
     label: 'Database',
     status: chromaExists ? '✅' : '❌',
     value: chromaExists ? `${CHROMA_PATH} (${collections} collections)` : 'not found',
-    ok: chromaExists
+    ok: chromaExists,
+    fixable: !chromaExists,
+    fixMessage: !chromaExists ? `create database directory at ${CHROMA_PATH}` : null,
+    fixCommand: `mkdir -p ${CHROMA_PATH}`,
+    fixAction: () => {
+      console.log(`  🔧 Creating ChromaDB directory...`);
+      try {
+        fs.mkdirSync(CHROMA_PATH, { recursive: true });
+        console.log(`  ✅ Created directory: ${CHROMA_PATH}`);
+        return true;
+      } catch (e) {
+        console.log(`  ❌ Failed to create directory: ${e.message}`);
+        return false;
+      }
+    }
   });
   
   // Memory files check
@@ -181,17 +251,47 @@ function runDoctor() {
     label: 'Memory files',
     status: memoryExists ? '✅' : '⚠️',
     value: memoryExists ? `${memoryCount} files in memory/` : 'directory not found',
-    ok: memoryExists
+    ok: memoryExists,
+    fixable: !memoryExists,
+    fixMessage: !memoryExists ? `create memory directory at ${MEMORY_PATH}` : null,
+    fixCommand: `mkdir -p ${MEMORY_PATH}`,
+    fixAction: () => {
+      console.log(`  🔧 Creating memory directory...`);
+      try {
+        fs.mkdirSync(MEMORY_PATH, { recursive: true });
+        console.log(`  ✅ Created directory: ${MEMORY_PATH}`);
+        return true;
+      } catch (e) {
+        console.log(`  ❌ Failed to create directory: ${e.message}`);
+        return false;
+      }
+    }
   });
   
-  // Last index time
+  // Last index time / collections check
   const lastIndexMs = getLastIndexTime();
-  const lastIndexOk = lastIndexMs !== null && lastIndexMs < 7 * 24 * 60 * 60 * 1000; // < 7 days
+  const needsIndex = collections === 0 && chromaExists;
+  const lastIndexOk = !needsIndex && (lastIndexMs !== null && lastIndexMs < 7 * 24 * 60 * 60 * 1000); // < 7 days
   checks.push({
     label: 'Last indexed',
     status: lastIndexMs === null ? '⚠️' : (lastIndexOk ? '✅' : '⚠️'),
-    value: lastIndexMs === null ? 'never' : formatTime(lastIndexMs),
-    ok: lastIndexMs !== null
+    value: needsIndex ? 'no collections - needs initial index' : (lastIndexMs === null ? 'never' : formatTime(lastIndexMs)),
+    ok: lastIndexMs !== null && !needsIndex,
+    fixable: needsIndex,
+    fixMessage: needsIndex ? 'run initial indexing with index-digests' : null,
+    fixCommand: 'index-digests',
+    fixAction: () => {
+      console.log(`  🔧 Running initial index...`);
+      const indexScript = path.join(__dirname, 'index-digests.js');
+      const result = exec(`node ${indexScript}`, { silent: false });
+      if (result.success) {
+        console.log(`  ✅ Initial indexing complete`);
+        return true;
+      } else {
+        console.log(`  ⚠️  Indexing may have completed with warnings`);
+        return true; // Don't treat warnings as failure
+      }
+    }
   });
   
   // Print results
@@ -199,10 +299,66 @@ function runDoctor() {
   for (const check of checks) {
     const padding = ' '.repeat(maxLabelLength - check.label.length);
     console.log(`  ${check.label}:${padding} ${check.status} ${check.value}`);
+    
+    // Show fix suggestions in default/dry-run mode
+    if (!check.ok && !fix) {
+      if (check.fixable && check.fixMessage) {
+        if (verbose && check.fixCommand) {
+          console.log(`    ${dryRun ? '📋' : '→'} Would run: ${check.fixCommand}`);
+        } else {
+          console.log(`    → run with --fix to ${check.fixMessage}`);
+        }
+      } else if (!check.fixable && check.fixMessage) {
+        console.log(`    ❌ ${check.fixMessage}`);
+      }
+    }
   }
   
   console.log('');
   
+  // Apply fixes if requested
+  if (fix) {
+    const fixableIssues = checks.filter(c => !c.ok && c.fixable && c.fixAction);
+    
+    if (fixableIssues.length === 0) {
+      const unfixableIssues = checks.filter(c => !c.ok && !c.fixable);
+      if (unfixableIssues.length > 0) {
+        console.log('⚠️  Some issues require manual intervention:\n');
+        for (const issue of unfixableIssues) {
+          console.log(`  ❌ ${issue.label}: ${issue.fixMessage}`);
+        }
+        console.log('');
+      }
+    } else {
+      console.log('🔧 Applying fixes...\n');
+      
+      for (const issue of fixableIssues) {
+        const success = issue.fixAction();
+        fixes.push({ issue: issue.label, success });
+        console.log('');
+      }
+      
+      const successCount = fixes.filter(f => f.success).length;
+      const failCount = fixes.filter(f => !f.success).length;
+      
+      if (failCount === 0) {
+        console.log(`✅ All ${successCount} issue${successCount > 1 ? 's' : ''} fixed!\n`);
+      } else {
+        console.log(`⚠️  Fixed ${successCount}/${fixes.length} issues (${failCount} failed)\n`);
+      }
+      
+      // Check for remaining unfixable issues
+      const unfixableIssues = checks.filter(c => !c.ok && !c.fixable);
+      if (unfixableIssues.length > 0) {
+        console.log('⚠️  Remaining issues require manual intervention:\n');
+        for (const issue of unfixableIssues) {
+          console.log(`  ❌ ${issue.label}: ${issue.fixMessage}`);
+        }
+        console.log('');
+      }
+    }
+  }
+  
   // Summary
   const allOk = checks.every(c => c.ok);
   if (allOk) {
@@ -210,23 +366,17 @@ function runDoctor() {
     return 0;
   } else {
     const failed = checks.filter(c => !c.ok);
-    console.log(`⚠️  ${failed.length} issue${failed.length > 1 ? 's' : ''} detected.\n`);
     
-    if (!pythonOk) {
-      console.log('→ Install Python 3: https://www.python.org/downloads/');
-    }
-    if (!venvExists || !chromaOk || !transformersOk) {
-      console.log('→ Run: npx jasper-recall setup');
-    }
-    if (!memoryExists) {
-      console.log(`→ Create memory directory: mkdir -p ${MEMORY_PATH}`);
-    }
-    if (lastIndexMs === null || !lastIndexOk) {
-      console.log('→ Index your memory: index-digests');
+    if (!fix) {
+      console.log(`⚠️  ${failed.length} issue${failed.length > 1 ? 's' : ''} detected.\n`);
+      
+      const hasFixableIssues = failed.some(c => c.fixable);
+      if (hasFixableIssues) {
+        console.log('→ Run with --fix to automatically repair issues\n');
+      }
     }
     
-    console.log('');
-    return 1;
+    return fixes.length > 0 && fixes.every(f => f.success) ? 0 : 1;
   }
 }
 
@@ -234,5 +384,11 @@ module.exports = { runDoctor };
 
 // Allow direct execution
 if (require.main === module) {
-  process.exit(runDoctor());
+  const args = process.argv.slice(2);
+  const options = {
+    fix: args.includes('--fix'),
+    dryRun: args.includes('--dry-run')
+  };
+  
+  process.exit(runDoctor(options));
 }

package/cli/jasper-recall.js

@@ -26,6 +26,9 @@ const VENV_PATH = path.join(os.homedir(), '.openclaw', 'rag-env');
 const CHROMA_PATH = path.join(os.homedir(), '.openclaw', 'chroma-db');
 const BIN_PATH = path.join(os.homedir(), '.local', 'bin');
 const SCRIPTS_DIR = path.join(__dirname, '..', 'scripts');
+const EXTENSIONS_DIR = path.join(__dirname, '..', 'extensions');
+const OPENCLAW_CONFIG = path.join(os.homedir(), '.openclaw', 'openclaw.json');
+const OPENCLAW_SKILLS = path.join(os.homedir(), '.openclaw', 'workspace', 'skills');
 
 function log(msg) {
   console.log(`🦊 ${msg}`);
@@ -47,6 +50,70 @@ function run(cmd, opts = {}) {
   }
 }
 
+function setupOpenClawIntegration() {
+  log('Setting up OpenClaw integration...');
+  
+  // Check if OpenClaw is installed
+  const openclawDir = path.join(os.homedir(), '.openclaw');
+  if (!fs.existsSync(openclawDir)) {
+    console.log('  ⚠ OpenClaw not detected (~/.openclaw not found)');
+    console.log('  → Skipping OpenClaw integration');
+    return false;
+  }
+  
+  // Install SKILL.md to skills directory
+  const skillSrc = path.join(EXTENSIONS_DIR, 'openclaw-plugin', 'SKILL.md');
+  const skillDest = path.join(OPENCLAW_SKILLS, 'jasper-recall', 'SKILL.md');
+  
+  if (fs.existsSync(skillSrc)) {
+    fs.mkdirSync(path.dirname(skillDest), { recursive: true });
+    fs.copyFileSync(skillSrc, skillDest);
+    console.log(`  ✓ Installed SKILL.md: ${skillDest}`);
+  } else {
+    console.log('  ⚠ SKILL.md not found in package (try reinstalling)');
+  }
+  
+  // Update openclaw.json with plugin config
+  if (fs.existsSync(OPENCLAW_CONFIG)) {
+    try {
+      const configRaw = fs.readFileSync(OPENCLAW_CONFIG, 'utf8');
+      const config = JSON.parse(configRaw);
+      
+      // Initialize plugins structure if needed
+      if (!config.plugins) config.plugins = {};
+      if (!config.plugins.entries) config.plugins.entries = {};
+      
+      // Check if already configured
+      if (config.plugins.entries['jasper-recall']) {
+        console.log('  ✓ Plugin already configured in openclaw.json');
+      } else {
+        // Add plugin config
+        config.plugins.entries['jasper-recall'] = {
+          enabled: true,
+          config: {
+            autoRecall: true,
+            minScore: 0.3,
+            defaultLimit: 5
+          }
+        };
+        
+        // Write back with nice formatting
+        fs.writeFileSync(OPENCLAW_CONFIG, JSON.stringify(config, null, 2) + '\n');
+        console.log('  ✓ Added jasper-recall plugin to openclaw.json');
+        console.log('  → Restart OpenClaw gateway to activate: openclaw gateway restart');
+      }
+    } catch (e) {
+      console.log(`  ⚠ Could not update openclaw.json: ${e.message}`);
+      console.log('  → Manually add plugin config (see docs)');
+    }
+  } else {
+    console.log('  ⚠ openclaw.json not found');
+    console.log('  → Create config or manually add jasper-recall plugin');
+  }
+  
+  return true;
+}
+
 function setup() {
   log('Jasper Recall — Setup');
   console.log('=' .repeat(40));
@@ -118,6 +185,11 @@ function setup() {
     console.log(`  export PATH="$HOME/.local/bin:$PATH"`);
   }
   
+  console.log('');
+  
+  // OpenClaw integration
+  setupOpenClawIntegration();
+  
   console.log('');
   console.log('=' .repeat(40));
   log('Setup complete!');
@@ -139,6 +211,7 @@ USAGE:
 COMMANDS:
   setup       Install dependencies and CLI scripts
   doctor      Run system health check
+              Flags: --fix (auto-repair issues), --dry-run (verbose output)
   recall      Search your memory (alias for the recall command)
   index       Index memory files (alias for index-digests)
   digest      Process session logs (alias for digest-sessions)
@@ -231,7 +304,12 @@ switch (command) {
   case 'doctor':
     // Run system health check
     const { runDoctor } = require('./doctor');
-    process.exit(runDoctor());
+    const args = process.argv.slice(3);
+    const options = {
+      fix: args.includes('--fix'),
+      dryRun: args.includes('--dry-run')
+    };
+    process.exit(runDoctor(options));
     break;
   case 'config':
     // Configuration management

package/extensions/jasper-recall/SKILL.md

@@ -0,0 +1,204 @@
+# Jasper Recall - OpenClaw Plugin
+
+Semantic search over indexed memory using ChromaDB. Automatically injects relevant context before agent processing.
+
+## Features
+
+- **`recall` tool** — Manual semantic search over memory
+- **`/recall` command** — Quick lookups from chat
+- **`/index` command** — Re-index memory files
+- **Auto-recall** — Automatically inject relevant memories before processing
+
+---
+
+## Auto-Recall (The Magic ✨)
+
+When `autoRecall` is enabled, jasper-recall hooks into the agent lifecycle and automatically searches your memory before every message is processed.
+
+### How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. Message arrives from user                               │
+│  2. before_agent_start hook fires                           │
+│  3. jasper-recall searches ChromaDB with message as query   │
+│  4. Results filtered by minScore (default: 30%)             │
+│  5. Relevant memories injected via prependContext           │
+│  6. Agent sees memories + original message                  │
+│  7. Agent responds with full context                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### What Gets Injected
+
+```xml
+<relevant-memories>
+The following memories may be relevant to this conversation:
+- [memory/2026-02-05.md] Worker orchestration decisions...
+- [MEMORY.md] Git workflow: feature → develop → main...
+- [memory/sops/codex-integration-sop.md] Codex Cloud sync...
+</relevant-memories>
+```
+
+### What's Skipped
+
+Auto-recall won't run for:
+- Heartbeat polls (`HEARTBEAT...`)
+- System prompts containing `NO_REPLY`
+- Messages shorter than 10 characters
+
+---
+
+## Configuration
+
+In `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "jasper-recall": {
+        "enabled": true,
+        "config": {
+          "autoRecall": true,
+          "minScore": 0.3,
+          "defaultLimit": 5,
+          "publicOnly": false
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable plugin |
+| `autoRecall` | boolean | `false` | Auto-inject memories before processing |
+| `minScore` | number | `0.3` | Minimum similarity score (0-1) for auto-recall |
+| `defaultLimit` | number | `5` | Default number of results |
+| `publicOnly` | boolean | `false` | Only search public memory (sandboxed agents) |
+
+### Score Tuning
+
+- `minScore: 0.3` — Include loosely related memories (more context, may include noise)
+- `minScore: 0.5` — Only moderately relevant (balanced)
+- `minScore: 0.7` — Only highly relevant (precise, may miss useful context)
+
+---
+
+## Tools
+
+### `recall`
+
+Manual semantic search over memory.
+
+**Parameters:**
+- `query` (string, required): Natural language search query
+- `limit` (number, optional): Max results (default: 5)
+
+**Example:**
+```
+recall query="what did we decide about the API design" limit=3
+```
+
+**Returns:** Formatted markdown with matching memories, scores, and sources.
+
+---
+
+## Commands
+
+### `/recall <query>`
+
+Quick memory search from chat.
+
+```
+/recall worker orchestration decisions
+```
+
+### `/index`
+
+Re-index memory files into ChromaDB. Run after updating notes.
+
+```
+/index
+```
+
+---
+
+## RPC Methods
+
+For external integrations:
+
+### `recall.search`
+
+```json
+{ "query": "search terms", "limit": 5 }
+```
+
+### `recall.index`
+
+Re-index memory files (no params).
+
+---
+
+## Requirements
+
+- `recall` command in `~/.local/bin/`
+- ChromaDB index at `~/.openclaw/chroma-db`
+- Python venv at `~/.openclaw/rag-env`
+
+## Installation
+
+```bash
+npx jasper-recall setup
+```
+
+This sets up:
+1. Python venv with ChromaDB + sentence-transformers
+2. `recall`, `index-digests`, `digest-sessions` scripts
+3. Initial index of memory files
+
+---
+
+## When Auto-Recall Helps
+
+✅ **Great for:**
+- Questions about past decisions ("what did we decide about X?")
+- Following up on previous work ("where were we with the worker setup?")
+- Context about people, preferences, projects
+- Finding SOPs and procedures
+
+⚠️ **Less useful for:**
+- Brand new topics with no memory
+- Simple commands ("list files")
+- Real-time data (weather, time)
+
+---
+
+## Sandboxed Agents
+
+For agents processing untrusted input, use `publicOnly`:
+
+```json
+{
+  "jasper-recall": {
+    "config": {
+      "publicOnly": true,
+      "autoRecall": true
+    }
+  }
+}
+```
+
+This restricts searches to `memory/shared/` and public-tagged content, preventing leakage of private memories.
+
+---
+
+## Links
+
+- **GitHub**: https://github.com/E-x-O-Entertainment-Studios-Inc/jasper-recall
+- **npm**: `npx jasper-recall setup`
+- **ClawHub**: `clawhub install jasper-recall`