openclaw-cortex-memory 0.1.0-Alpha.3 → 0.1.0-Alpha.31

package/scripts/repair-memory.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const isDryRun = args.includes('--dry-run');
+const isFix = args.includes('--fix');
+const targetArg = args.find(a => a.startsWith('--target='));
+const target = targetArg ? targetArg.split('=')[1] : 'all';
+
+const PROJECT_ROOT = process.cwd();
+const MEMORY_ROOT = path.join(PROJECT_ROOT, 'data', 'memory');
+
+const VALID_TARGETS = ['all', 'archive', 'active', 'vector'];
+
+function printUsage() {
+  console.log(`
+Memory Data Repair Tool
+
+Usage: node scripts/repair-memory.js [options]
+
+Options:
+  --dry-run          Scan and report issues without making changes
+  --fix              Remove invalid records and create quarantine file
+  --target=<target>  Specify target: all, archive, active, vector (default: all)
+
+Examples:
+  node scripts/repair-memory.js --dry-run
+  node scripts/repair-memory.js --fix --target=archive
+`);
+}
+
+if (!VALID_TARGETS.includes(target)) {
+  console.error(`Invalid target: ${target}. Valid targets: ${VALID_TARGETS.join(', ')}`);
+  printUsage();
+  process.exit(1);
+}
+
+if (!isDryRun && !isFix) {
+  printUsage();
+  process.exit(0);
+}
+
+function validateJsonlLine(line, lineNumber) {
+  const errors = [];
+  if (!line || !line.trim()) {
+    return { valid: true, errors: [], record: null };
+  }
+  let record;
+  try {
+    record = JSON.parse(line);
+  } catch (e) {
+    errors.push(`JSON parse error: ${e.message}`);
+    return { valid: false, errors, record: null };
+  }
+  if (!record || typeof record !== 'object') {
+    errors.push('Record is not an object');
+    return { valid: false, errors, record: null };
+  }
+  if (typeof record.id !== 'string' || !record.id.trim()) {
+    errors.push('Missing or invalid id field');
+  }
+  if (typeof record.timestamp !== 'string' || !record.timestamp.trim()) {
+    errors.push('Missing or invalid timestamp field');
+  }
+  if (record.layer !== 'active' && record.layer !== 'archive') {
+    errors.push('Missing or invalid layer field');
+  }
+  const anomalyPatterns = [
+    /\d+\.\d+,\s*"[^"]+"/,
+    /"[^"]+"\s+\d+\.\d+/,
+    /,\s*\d+\.\d+,/,
+    /"\w+\.\w+\.\w+"/,
+    /\d+\.\w+\.\d+/,
+  ];
+  const lineStr = JSON.stringify(record);
+  for (const pattern of anomalyPatterns) {
+    if (pattern.test(lineStr)) {
+      errors.push('Anomaly pattern detected in record');
+      break;
+    }
+  }
+  return { valid: errors.length === 0, errors, record };
+}
+
+function scanJsonlFile(filePath) {
+  const results = {
+    path: filePath,
+    exists: false,
+    totalLines: 0,
+    validLines: 0,
+    invalidLines: 0,
+    emptyLines: 0,
+    issues: [],
+  };
+  if (!fs.existsSync(filePath)) {
+    return results;
+  }
+  results.exists = true;
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) {
+      results.emptyLines++;
+      continue;
+    }
+    results.totalLines++;
+    const validation = validateJsonlLine(line, i + 1);
+    if (validation.valid) {
+      results.validLines++;
+    } else {
+      results.invalidLines++;
+      results.issues.push({
+        lineNumber: i + 1,
+        errors: validation.errors,
+        preview: line.slice(0, 100) + (line.length > 100 ? '...' : ''),
+      });
+    }
+  }
+  return results;
+}
+
+function repairJsonlFile(filePath, dryRun) {
+  const results = {
+    path: filePath,
+    exists: false,
+    totalLines: 0,
+    validLines: 0,
+    removedLines: 0,
+    quarantineLines: [],
+  };
+  if (!fs.existsSync(filePath)) {
+    return results;
+  }
+  results.exists = true;
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split(/\r?\n/);
+  const validRecords = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) {
+      continue;
+    }
+    results.totalLines++;
+    const validation = validateJsonlLine(line, i + 1);
+    if (validation.valid) {
+      results.validLines++;
+      validRecords.push(line);
+    } else {
+      results.removedLines++;
+      results.quarantineLines.push({
+        lineNumber: i + 1,
+        content: line,
+        errors: validation.errors,
+      });
+    }
+  }
+  if (!dryRun && results.removedLines > 0) {
+    const newContent = validRecords.join('\n') + (validRecords.length > 0 ? '\n' : '');
+    fs.writeFileSync(filePath, newContent, 'utf-8');
+    const quarantinePath = filePath + '.quarantine.jsonl';
+    const quarantineContent = results.quarantineLines.map(q => 
+      JSON.stringify({ lineNumber: q.lineNumber, errors: q.errors, content: q.content })
+    ).join('\n');
+    fs.writeFileSync(quarantinePath, quarantineContent + '\n', 'utf-8');
+  }
+  return results;
+}
+
+function scanVectorFallback(filePath) {
+  const results = {
+    path: filePath,
+    exists: false,
+    totalRecords: 0,
+    validRecords: 0,
+    orphanRecords: 0,
+    issues: [],
+  };
+  if (!fs.existsSync(filePath)) {
+    return results;
+  }
+  results.exists = true;
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    results.totalRecords++;
+    try {
+      const record = JSON.parse(line);
+      if (!record.id || !record.embedding) {
+        results.issues.push({
+          lineNumber: i + 1,
+          error: 'Missing id or embedding',
+        });
+      } else {
+        results.validRecords++;
+      }
+    } catch (e) {
+      results.issues.push({
+        lineNumber: i + 1,
+        error: `JSON parse error: ${e.message}`,
+      });
+    }
+  }
+  return results;
+}
+
+console.log('='.repeat(60));
+console.log('Memory Data Repair Tool');
+console.log('='.repeat(60));
+console.log(`Mode: ${isDryRun ? 'DRY RUN (no changes)' : 'FIX (will modify files)'}`);
+console.log(`Target: ${target}`);
+console.log(`Memory Root: ${MEMORY_ROOT}`);
+console.log('='.repeat(60));
+
+const archivePath = path.join(MEMORY_ROOT, 'sessions', 'archive', 'archive.jsonl');
+const activePath = path.join(MEMORY_ROOT, 'sessions', 'active', 'sessions.jsonl');
+const vectorFallbackPath = path.join(MEMORY_ROOT, 'vector', 'lancedb_events.jsonl');
+
+let totalIssues = 0;
+const report = {
+  archive: null,
+  active: null,
+  vector: null,
+};
+
+if (target === 'all' || target === 'archive') {
+  console.log('\n[Archive Layer]');
+  if (isDryRun) {
+    report.archive = scanJsonlFile(archivePath);
+  } else {
+    report.archive = repairJsonlFile(archivePath, false);
+  }
+  if (!report.archive.exists) {
+    console.log('  File does not exist');
+  } else {
+    console.log(`  Total lines: ${report.archive.totalLines}`);
+    console.log(`  Valid lines: ${report.archive.validLines}`);
+    console.log(`  Invalid lines: ${report.archive.invalidLines || report.archive.removedLines}`);
+    if (report.archive.issues && report.archive.issues.length > 0) {
+      console.log('  Issues found:');
+      report.archive.issues.slice(0, 5).forEach(issue => {
+        console.log(`    Line ${issue.lineNumber}: ${issue.errors.join(', ')}`);
+      });
+      if (report.archive.issues.length > 5) {
+        console.log(`    ... and ${report.archive.issues.length - 5} more`);
+      }
+    }
+    totalIssues += report.archive.invalidLines || report.archive.removedLines || 0;
+  }
+}
+
+if (target === 'all' || target === 'active') {
+  console.log('\n[Active Layer]');
+  if (isDryRun) {
+    report.active = scanJsonlFile(activePath);
+  } else {
+    report.active = repairJsonlFile(activePath, false);
+  }
+  if (!report.active.exists) {
+    console.log('  File does not exist');
+  } else {
+    console.log(`  Total lines: ${report.active.totalLines}`);
+    console.log(`  Valid lines: ${report.active.validLines}`);
+    console.log(`  Invalid lines: ${report.active.invalidLines || report.active.removedLines}`);
+    if (report.active.issues && report.active.issues.length > 0) {
+      console.log('  Issues found:');
+      report.active.issues.slice(0, 5).forEach(issue => {
+        console.log(`    Line ${issue.lineNumber}: ${issue.errors.join(', ')}`);
+      });
+      if (report.active.issues.length > 5) {
+        console.log(`    ... and ${report.active.issues.length - 5} more`);
+      }
+    }
+    totalIssues += report.active.invalidLines || report.active.removedLines || 0;
+  }
+}
+
+if (target === 'all' || target === 'vector') {
+  console.log('\n[Vector Fallback]');
+  report.vector = scanVectorFallback(vectorFallbackPath);
+  if (!report.vector.exists) {
+    console.log('  File does not exist');
+  } else {
+    console.log(`  Total records: ${report.vector.totalRecords}`);
+    console.log(`  Valid records: ${report.vector.validRecords}`);
+    console.log(`  Issues: ${report.vector.issues.length}`);
+    if (report.vector.issues.length > 0) {
+      console.log('  Issues found:');
+      report.vector.issues.slice(0, 5).forEach(issue => {
+        console.log(`    Line ${issue.lineNumber}: ${issue.error}`);
+      });
+    }
+    totalIssues += report.vector.issues.length;
+  }
+}
+
+console.log('\n' + '='.repeat(60));
+console.log('Summary');
+console.log('='.repeat(60));
+console.log(`Total issues found: ${totalIssues}`);
+
+if (isDryRun) {
+  if (totalIssues > 0) {
+    console.log('\nRun with --fix to repair these issues.');
+  } else {
+    console.log('\nNo issues found. Memory data is healthy.');
+  }
+} else {
+  if (totalIssues > 0) {
+    console.log('\nRepair completed. Invalid records have been quarantined.');
+    console.log('Check .quarantine.jsonl files for removed records.');
+  } else {
+    console.log('\nNo repairs needed. Memory data is healthy.');
+  }
+}
+
+process.exit(totalIssues > 0 && isDryRun ? 1 : 0);

package/scripts/uninstall.js

@@ -17,14 +17,20 @@ function findProjectRoot() {
 }
 
 function findOpenClawConfig() {
+  const explicitConfigPath = process.env.OPENCLAW_CONFIG_PATH || '';
+  const stateDir = process.env.OPENCLAW_STATE_DIR || '';
+  const basePath = process.env.OPENCLAW_BASE_PATH || '';
+  const homePath = process.env.USERPROFILE || process.env.HOME || '';
   const possiblePaths = [
+    explicitConfigPath,
+    stateDir ? path.join(stateDir, 'openclaw.json') : '',
+    basePath ? path.join(basePath, 'openclaw.json') : '',
     path.join(process.cwd(), 'openclaw.json'),
-    path.join(process.env.USERPROFILE || process.env.HOME || '', '.openclaw', 'openclaw.json'),
-    path.join(process.env.OPENCLAW_BASE_PATH || '', 'openclaw.json'),
+    homePath ? path.join(homePath, '.openclaw', 'openclaw.json') : '',
   ];
   
   for (const p of possiblePaths) {
-    if (fs.existsSync(p)) {
+    if (p && fs.existsSync(p)) {
       return p;
     }
   }
@@ -114,15 +120,20 @@ function removeFromConfig() {
     const content = fs.readFileSync(configPath, 'utf-8');
     const config = JSON.parse(content);
     
+    if (Array.isArray(config.plugins?.allow)) {
+      config.plugins.allow = config.plugins.allow.filter((item) => item !== PLUGIN_NAME);
+    }
     if (config.plugins?.entries?.[PLUGIN_NAME]) {
       delete config.plugins.entries[PLUGIN_NAME];
-      
       if (config.plugins.slots?.memory === PLUGIN_NAME) {
         delete config.plugins.slots.memory;
       }
       
       fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
       console.log(`Removed plugin from config: ${configPath}`);
+    } else if (Array.isArray(config.plugins?.allow)) {
+      fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+      console.log(`Removed plugin allowlist entry from config: ${configPath}`);
     } else {
       console.log('Plugin not found in config.');
     }
@@ -209,4 +220,10 @@ function main() {
   }
 }
 
-main();
+module.exports = {
+  uninstall,
+};
+
+if (require.main === module) {
+  main();
+}

package/skills/cortex-memory/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: cortex-memory
+description: Independent skill for Cortex Memory operations in OpenClaw. Use when users ask for cross-session memory continuity, prior decisions, preferences, relationship tracing, or memory maintenance. If the memory plugin is not installed, guide users to install and enable openclaw-cortex-memory first, then continue with normal memory workflows.
+homepage: https://github.com/deki18/openclaw-cortex-memory
+metadata: { "openclaw": { "os": ["darwin", "linux", "win32"], "primaryEnv": "EMBEDDING_API_KEY" } }
+---
+
+# Cortex Memory
+
+This is an independent skill, not a plugin-embedded skill.
+
+Use this runtime flow:
+
+1. Check whether plugin `openclaw-cortex-memory` is available.
+2. If missing or disabled, run the install bootstrap guide in `{baseDir}/references/agent-manual.md` with README-consistent install order.
+3. After plugin is enabled, run memory retrieval or write operations.
+
+After plugin is ready, use this default workflow:
+
+1. Retrieve candidate memory with `search_memory`.
+2. If the user asks about entity links or dependency paths, use `query_graph`.
+3. If `query_graph` returns `conflict_hint`, use `list_graph_conflicts` and ask user confirmation before `resolve_graph_conflict`.
+4. For graph status snapshots or projection consistency checks, use `export_graph_view` and `lint_memory_wiki`.
+5. Answer with retrieved evidence first, then add reasoning.
+6. If the turn introduces durable new information, persist it with `store_event`.
+7. For maintenance windows or session wrap-up, run `sync_memory` and optionally `reflect_memory`.
+
+If tool calls fail:
+
+1. Run `diagnostics`.
+2. Tell the user the plugin is unavailable or misconfigured.
+3. Continue with a normal answer without fabricating memory hits.
+
+Do not use this skill for:
+
+- Real-time web facts (weather, stock, breaking news).
+- One-off temporary context that should not be persisted.
+
+Use these local references when needed:
+
+- Install and bootstrap playbook: `{baseDir}/references/agent-manual.md`
+- System prompt template: `{baseDir}/references/system-prompt-template.md`
+- Tool details: `{baseDir}/references/tools.md`
+- Config and dependency setup: `{baseDir}/references/configuration.md`
+- Publish and validation checklist: `{baseDir}/references/publish-checklist.md`
+
+Use this script for a quick environment preflight:
+
+- `{baseDir}/scripts/smoke-check.ps1 -Json`

package/skills/cortex-memory/references/agent-manual.md

@@ -0,0 +1,115 @@
+# Cortex Memory Agent Manual
+
+## Goal
+
+Use Cortex Memory as a long-term memory layer in OpenClaw. This manual is for agents operating from the independent `cortex-memory` skill folder.
+
+## Phase 1: Plugin Availability Check
+
+Run:
+
+```bash
+openclaw plugins list
+openclaw plugins inspect openclaw-cortex-memory
+```
+
+If plugin exists and is enabled, continue to Phase 3.
+
+If plugin is missing or disabled, go to Phase 2.
+
+## Phase 2: Install and Enable Plugin
+
+Preferred install path (README default):
+
+```bash
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+```
+
+Fallback install path:
+
+```bash
+npm pack openclaw-cortex-memory@0.1.0-Alpha.30
+openclaw plugins install ./openclaw-cortex-memory-0.1.0-Alpha.30.tgz
+openclaw plugins enable openclaw-cortex-memory
+rm ./openclaw-cortex-memory-0.1.0-Alpha.30.tgz
+```
+
+Then verify:
+
+```bash
+openclaw plugins list
+openclaw plugins inspect openclaw-cortex-memory
+```
+
+If config is not ready, apply the baseline from `configuration.md`.
+
+If the user asks for "system prompt rules", use `{baseDir}/references/system-prompt-template.md`.
+
+## Phase 3: Runtime Workflow
+
+### Retrieval-first answers
+
+1. `search_memory` with the user query.
+2. `query_graph` when relationship/path reasoning is needed.
+3. If `query_graph` returns `conflict_hint`, run `list_graph_conflicts` and confirm with user before `resolve_graph_conflict`.
+4. Respond with evidence first, reasoning second.
+
+### Persistence
+
+Use `store_event` only for durable information:
+
+- stable preferences
+- project decisions
+- long-lived constraints
+
+Avoid persisting ephemeral chatter.
+
+### Maintenance
+
+- `sync_memory` for historical import
+- `reflect_memory` for rule extraction
+- `backfill_embeddings` for vector repair
+- `export_graph_view` for status-aware graph snapshots
+- `lint_memory_wiki` for projection consistency checks
+- `diagnostics` when anything looks inconsistent
+
+## Failure Handling
+
+If plugin tools are unavailable:
+
+1. Run `diagnostics`.
+2. Explain the issue clearly (plugin disabled, config incomplete, endpoint unavailable, or API key missing).
+3. Provide immediate next action with exact command.
+
+If install or enable flow reports a `memory-lancedb` config requirement, add this block under `plugins.entries` in `openclaw.json`:
+
+```json
+"memory-lancedb": {
+  "enabled": false,
+  "config": {
+    "embedding": {
+      "apiKey": "${MEMORY_LANCEDB_API_KEY}",
+      "model": "text-embedding-3-small"
+    },
+    "dbPath": "~/.openclaw/memory/lancedb",
+    "autoRecall": true,
+    "autoCapture": false,
+    "captureMaxChars": 500
+  }
+}
+```
+
+## Operator Commands Cheat Sheet
+
+```bash
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+openclaw plugins inspect openclaw-cortex-memory
+npm pack openclaw-cortex-memory@0.1.0-Alpha.30
+openclaw plugins install ./openclaw-cortex-memory-0.1.0-Alpha.30.tgz
+openclaw plugins enable openclaw-cortex-memory
+rm ./openclaw-cortex-memory-0.1.0-Alpha.30.tgz
+openclaw skills info cortex-memory
+openclaw skills check
+```

package/skills/cortex-memory/references/configuration.md

@@ -0,0 +1,92 @@
+# Configuration Reference
+
+## Minimum OpenClaw Config
+
+Use this as the baseline in `openclaw.json`.
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-cortex-memory"],
+    "slots": {
+      "memory": "none"
+    },
+    "entries": {
+      "openclaw-cortex-memory": {
+        "enabled": true,
+        "config": {
+          "autoSync": true,
+          "autoReflect": false,
+          "graphQualityMode": "warn",
+          "wikiProjection": {
+            "enabled": true,
+            "mode": "incremental",
+            "maxBatch": 100
+          },
+          "embedding": {
+            "provider": "api",
+            "model": "text-embedding-3-large",
+            "apiKey": "${EMBEDDING_API_KEY}",
+            "baseURL": "https://your-embedding-endpoint/v1",
+            "dimensions": 3072
+          },
+          "llm": {
+            "provider": "api",
+            "model": "gpt-4",
+            "apiKey": "${LLM_API_KEY}",
+            "baseURL": "https://your-llm-endpoint/v1"
+          },
+          "reranker": {
+            "provider": "api",
+            "model": "BAAI/bge-reranker-v2-m3",
+            "apiKey": "${RERANKER_API_KEY}",
+            "baseURL": "https://your-reranker-endpoint/v1/rerank"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Required Environment Variables
+
+- `EMBEDDING_API_KEY`
+- `LLM_API_KEY`
+- `RERANKER_API_KEY`
+
+## Required Endpoints
+
+- Embedding: OpenAI-compatible `/embeddings`
+- LLM: OpenAI-compatible `/chat/completions`
+- Reranker: `/rerank`
+
+## Troubleshooting: memory-lancedb Requirement
+
+If `openclaw plugins install/enable` reports a `memory-lancedb` config requirement, add this entry under `plugins.entries`:
+
+```json
+"memory-lancedb": {
+  "enabled": false,
+  "config": {
+    "embedding": {
+      "apiKey": "${MEMORY_LANCEDB_API_KEY}",
+      "model": "text-embedding-3-small"
+    },
+    "dbPath": "~/.openclaw/memory/lancedb",
+    "autoRecall": true,
+    "autoCapture": false,
+    "captureMaxChars": 500
+  }
+}
+```
+
+## Recommended Validation Commands
+
+```bash
+openclaw plugins list
+openclaw plugins inspect openclaw-cortex-memory
+openclaw skills list
+openclaw skills info cortex-memory
+openclaw skills check
+```

package/skills/cortex-memory/references/publish-checklist.md

@@ -0,0 +1,46 @@
+# ClawHub Publish Checklist
+
+## Preflight
+
+1. Confirm skill root contains `SKILL.md`.
+2. Confirm frontmatter includes:
+   - `name`
+   - `description`
+3. Confirm no secret values are hardcoded in skill files.
+
+## Local Validation
+
+```bash
+openclaw skills list
+openclaw skills info cortex-memory
+openclaw skills check
+```
+
+Optional plugin validation:
+
+```bash
+openclaw plugins list
+openclaw plugins inspect openclaw-cortex-memory
+```
+
+## Publish
+
+```bash
+clawhub login
+clawhub whoami
+clawhub skill publish ./skills/cortex-memory --slug cortex-memory --name "Cortex Memory" --version 0.1.0 --changelog "Initial ClawHub release" --tags latest
+```
+
+## Install Test (Clean Workspace)
+
+```bash
+openclaw skills install cortex-memory
+openclaw skills info cortex-memory
+```
+
+## Post Publish
+
+1. Start a new session.
+2. Trigger retrieval workflow with a memory-related prompt.
+3. Verify skill appears and is eligible in `openclaw skills list --eligible`.
+