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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-cortex-memory",
-  "version": "0.1.0-Alpha.3",
+  "version": "0.1.0-Alpha.30",
   "description": "Long-term memory system for OpenClaw AI Agent",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,9 +9,19 @@
   },
   "scripts": {
     "build": "tsc && node -e \"require('fs').copyFileSync('openclaw.plugin.json','dist/openclaw.plugin.json')\"",
+    "typecheck": "tsc --noEmit",
+    "check:version": "node scripts/check-version.js",
+    "test:compat": "node scripts/compat-regression.js",
+    "test:model": "node scripts/model-regression.js",
+    "test:graph": "node scripts/graph-eval.js",
+    "test:graph-quality": "node scripts/graph-quality-eval.js",
+    "test:graph-quality-zh": "node scripts/graph-quality-eval.js --gold eval/graph_quality_gold.zh.jsonl --pred eval/graph_quality_predictions.zh.sample.jsonl --thresholds eval/graph_quality_thresholds.json",
+    "test:lengthnorm": "node scripts/lengthnorm-regression.js",
+    "test:all": "npm run test:compat && npm run test:model && npm run test:graph && npm run test:graph-quality && npm run test:graph-quality-zh && npm run test:lengthnorm",
+    "release:check": "node scripts/release-pipeline.js",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/install.js"
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check:version && npm run build && npm run test:all"
   },
   "keywords": [
     "openclaw",
@@ -20,27 +30,30 @@
     "agent",
     "rag"
   ],
-  "author": "",
+  "author": "deki18",
   "license": "MIT",
   "dependencies": {
     "undici": "^6.21.0"
   },
+  "optionalDependencies": {
+    "@lancedb/lancedb": "^0.22.0"
+  },
   "devDependencies": {
     "@types/node": "^22.19.15",
     "typescript": "^5.7.2"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.3.8"
+    "openclaw": ">=2026.4.5"
   },
   "engines": {
     "node": ">=22.0.0"
   },
   "files": [
     "dist/",
-    "index.ts",
     "scripts/cli.js",
-    "scripts/install.js",
     "scripts/uninstall.js",
+    "scripts/repair-memory.js",
+    "schema/",
     "openclaw.plugin.json",
     "SKILL.md"
   ],
@@ -48,6 +61,39 @@
     "plugin": true,
     "requiresPython": false,
     "cli": "cortex-memory",
+    "requires": {
+      "credentials": true,
+      "network": true,
+      "env": [
+        "EMBEDDING_API_KEY",
+        "LLM_API_KEY",
+        "RERANKER_API_KEY"
+      ],
+      "config": [
+        "embedding.apiKey",
+        "llm.apiKey",
+        "reranker.apiKey",
+        "embedding.baseURL",
+        "llm.baseURL",
+        "reranker.baseURL"
+      ],
+      "externalEndpoints": [
+        "embedding API endpoint (OpenAI-compatible /embeddings)",
+        "LLM API endpoint (OpenAI-compatible /chat/completions)",
+        "reranker API endpoint (/rerank)"
+      ]
+    },
+    "build": {
+      "openclawVersion": "2026.4.5",
+      "pluginSdkVersion": "2026.4.5"
+    },
+    "install": {
+      "minHostVersion": ">=2026.4.5"
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.5",
+      "minGatewayVersion": "2026.4.5"
+    },
     "extensions": [
       "./dist/index.js"
     ]

package/schema/graph.schema.yaml

@@ -0,0 +1,175 @@
+{
+  "eventTypes": [
+    "decision",
+    "issue",
+    "fix",
+    "preference",
+    "plan",
+    "risk",
+    "insight",
+    "action_item",
+    "conversation_summary",
+    "constraint",
+    "requirement",
+    "milestone",
+    "blocker",
+    "dependency",
+    "assumption",
+    "retrospective",
+    "follow_up"
+  ],
+  "eventTypeAliases": {
+    "problem": "issue",
+    "error": "issue",
+    "bug": "issue",
+    "solution": "fix",
+    "workaround": "fix",
+    "todo": "action_item",
+    "next_step": "action_item",
+    "limitation": "constraint",
+    "guardrail": "constraint",
+    "spec": "requirement",
+    "acceptance_criteria": "requirement",
+    "deadline": "milestone",
+    "target": "milestone",
+    "roadblock": "blocker",
+    "stuck": "blocker",
+    "depends_on": "dependency",
+    "upstream": "dependency",
+    "hypothesis": "assumption",
+    "lesson": "retrospective",
+    "postmortem": "retrospective",
+    "followup": "follow_up",
+    "next_action": "follow_up"
+  },
+  "entityTypes": [
+    "Person",
+    "FamilyMember",
+    "Friend",
+    "Team",
+    "Project",
+    "Task",
+    "Plan",
+    "Milestone",
+    "Location",
+    "Event",
+    "Schedule",
+    "Habit",
+    "HealthItem",
+    "FinanceItem",
+    "Issue",
+    "Fix",
+    "Decision",
+    "Action",
+    "Risk",
+    "Blocker",
+    "Assumption",
+    "Concept",
+    "Resource",
+    "Document"
+  ],
+  "entityAliases": {
+    "OpenClaw": ["openclaw", "插件", "该项目", "本项目"],
+    "FamilyMember": ["家人", "家庭成员", "亲人"],
+    "Friend": ["朋友", "好友"],
+    "Location": ["地点", "位置", "住址", "地址"],
+    "Event": ["活动", "事情", "事项"],
+    "Schedule": ["日程", "安排", "计划表"],
+    "Habit": ["习惯", "作息"],
+    "HealthItem": ["健康", "体检", "药物", "锻炼"],
+    "FinanceItem": ["账单", "支出", "收入", "预算"],
+    "Person": ["我", "自己", "本人", "同事", "客户", "用户"],
+    "Project": ["项目", "工程"],
+    "Task": ["任务", "待办", "todo"],
+    "Milestone": ["里程碑", "节点"],
+    "Issue": ["问题", "故障", "报错"],
+    "Fix": ["修复", "解决方案"]
+  },
+  "relationTypes": [
+    "depends_on",
+    "blocks",
+    "related_to",
+    "causes",
+    "resolves",
+    "plans_to",
+    "scheduled_for",
+    "lives_in",
+    "cares_for",
+    "pays_for",
+    "supports",
+    "conflicts_with",
+    "belongs_to",
+    "owned_by",
+    "references",
+    "prefers",
+    "implements",
+    "requires"
+  ],
+  "relationTypeAliases": {
+    "dependency": "depends_on",
+    "blocked_by": "blocks",
+    "linked_to": "related_to",
+    "plan_to": "plans_to",
+    "schedule_for": "scheduled_for",
+    "located_in": "lives_in",
+    "care_for": "cares_for",
+    "pay_for": "pays_for",
+    "support": "supports",
+    "conflict_with": "conflicts_with",
+    "依赖于": "depends_on",
+    "依赖": "depends_on",
+    "取决于": "depends_on",
+    "阻塞": "blocks",
+    "卡住": "blocks",
+    "导致": "causes",
+    "引起": "causes",
+    "解决": "resolves",
+    "修复": "resolves",
+    "属于": "belongs_to",
+    "归属": "belongs_to",
+    "负责": "owned_by",
+    "由": "owned_by",
+    "参考": "references",
+    "引用": "references",
+    "偏好": "prefers",
+    "更喜欢": "prefers",
+    "实现": "implements",
+    "需要": "requires",
+    "计划做": "plans_to",
+    "打算": "plans_to",
+    "安排在": "scheduled_for",
+    "约在": "scheduled_for",
+    "住在": "lives_in",
+    "居住在": "lives_in",
+    "照顾": "cares_for",
+    "看护": "cares_for",
+    "支付": "pays_for",
+    "付款": "pays_for",
+    "支持": "supports",
+    "冲突": "conflicts_with",
+    "矛盾": "conflicts_with",
+    "相关": "related_to",
+    "有关": "related_to",
+    "belongs": "belongs_to",
+    "owner_of": "owned_by",
+    "refer_to": "references",
+    "preference_for": "prefers",
+    "implement": "implements",
+    "need": "requires"
+  },
+  "relationRules": [
+    { "type": "depends_on", "fromTypes": ["Task", "Plan", "Milestone"], "toTypes": ["Task", "Plan", "Milestone"], "allowSelfLoop": false },
+    { "type": "blocks", "fromTypes": ["Issue", "Task", "Risk"], "toTypes": ["Task", "Plan"], "allowSelfLoop": false },
+    { "type": "causes", "fromTypes": ["Issue", "Risk", "Assumption"], "toTypes": ["Issue", "Risk"], "allowSelfLoop": false },
+    { "type": "resolves", "fromTypes": ["Fix", "Decision", "Action"], "toTypes": ["Issue", "Blocker"], "allowSelfLoop": false },
+    { "type": "belongs_to", "fromTypes": ["Task", "Issue", "Fix", "Decision"], "toTypes": ["Project", "Plan", "Milestone"], "allowSelfLoop": false },
+    { "type": "owned_by", "fromTypes": ["Task", "Plan", "Project", "Issue"], "toTypes": ["Person", "Team"], "allowSelfLoop": false }
+  ],
+  "highValueRelationTypes": ["depends_on", "blocks", "resolves", "owned_by"],
+  "relatedToMaxRatio": 0.35,
+  "relatedToMaxAbsolute": 2,
+  "minRelationConfidence": 0.35,
+  "evidenceSpanRequired": true,
+  "endpointMentionRequired": true,
+  "defaultEntityType": "Concept"
+}

package/scripts/cli.js

@@ -2,16 +2,17 @@
 
 const fs = require('fs');
 const path = require('path');
-const { spawn } = require('child_process');
 
 const PLUGIN_NAME = 'openclaw-cortex-memory';
 
 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'),
     homePath ? path.join(homePath, '.openclaw', 'openclaw.json') : '',
@@ -53,7 +54,10 @@ function enablePlugin() {
   const configPath = findOpenClawConfig();
   
   if (!configPath) {
-    const defaultPath = path.join(process.env.USERPROFILE || process.env.HOME || '', '.openclaw', 'openclaw.json');
+    const defaultPath = process.env.OPENCLAW_CONFIG_PATH
+      || (process.env.OPENCLAW_STATE_DIR ? path.join(process.env.OPENCLAW_STATE_DIR, 'openclaw.json') : '')
+      || (process.env.OPENCLAW_BASE_PATH ? path.join(process.env.OPENCLAW_BASE_PATH, 'openclaw.json') : '')
+      || path.join(process.env.USERPROFILE || process.env.HOME || '', '.openclaw', 'openclaw.json');
     console.log(`No config file found. Creating: ${defaultPath}`);
     
     const config = {
@@ -170,21 +174,22 @@ function getStatus() {
 }
 
 function runUninstall(args) {
-  const uninstallScript = path.join(__dirname, 'uninstall.js');
-  
-  if (!fs.existsSync(uninstallScript)) {
+  const uninstallScriptPath = path.join(__dirname, 'uninstall.js');
+  if (!fs.existsSync(uninstallScriptPath)) {
     console.error('Uninstall script not found.');
     process.exit(1);
   }
-  
-  const child = spawn(process.execPath, [uninstallScript, 'uninstall', ...args], {
-    stdio: 'inherit',
-    cwd: process.cwd()
-  });
-  
-  child.on('exit', (code) => {
-    process.exit(code || 0);
-  });
+  try {
+    const uninstallModule = require(uninstallScriptPath);
+    if (!uninstallModule || typeof uninstallModule.uninstall !== 'function') {
+      console.error('Invalid uninstall script export.');
+      process.exit(1);
+    }
+    uninstallModule.uninstall(args);
+  } catch (error) {
+    console.error(`Failed to run uninstall: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
 }
 
 function showHelp() {

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);