openclaw-cortex-memory 0.1.0-Alpha.1

package/openclaw.plugin.json

@@ -0,0 +1,295 @@
+{
+  "id": "openclaw-cortex-memory",
+  "name": "Cortex Memory",
+  "version": "0.1.0-Alpha.1",
+  "description": "Long-term memory system with semantic, episodic, and procedural memory for AI Agents",
+  "main": "dist/index.js",
+  "author": "OpenClaw Community",
+  "license": "MIT",
+  "type": "memory",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deki18/openclaw-cortex-memory"
+  },
+  "capabilities": {
+    "tools": true,
+    "hooks": true,
+    "cli": true,
+    "channels": false,
+    "memory": true
+  },
+  "hooks": [
+    "message_received",
+    "session_end"
+  ],
+  "tools": [
+    {
+      "name": "search_memory",
+      "description": "Search long-term memory for relevant information",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search query"
+          },
+          "top_k": {
+            "type": "integer",
+            "description": "Number of results to return"
+          }
+        },
+        "required": ["query"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "store_event",
+      "description": "Store a new event in memory",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "summary": {
+            "type": "string",
+            "description": "Event summary"
+          },
+          "entities": {
+            "type": "array",
+            "description": "Involved entities",
+            "items": {
+              "type": "string"
+            }
+          },
+          "outcome": {
+            "type": "string",
+            "description": "Event outcome"
+          },
+          "relations": {
+            "type": "array",
+            "description": "Entity relationships",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": ["summary"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "query_graph",
+      "description": "Query memory graph for entity relationships",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "entity": {
+            "type": "string",
+            "description": "Entity name"
+          }
+        },
+        "required": ["entity"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "get_hot_context",
+      "description": "Get hot memory context for current session",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of hot context items"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "get_auto_context",
+      "description": "Get relevant memories based on recent messages",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "include_hot": {
+            "type": "boolean",
+            "description": "Include hot context"
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "reflect_memory",
+      "description": "Convert events into semantic knowledge",
+      "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "sync_memory",
+      "description": "Import historical session data into memory",
+      "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "delete_memory",
+      "description": "Delete a memory by ID",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "memory_id": {
+            "type": "string",
+            "description": "Memory ID"
+          }
+        },
+        "required": ["memory_id"],
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "diagnostics",
+      "description": "Check memory system status",
+      "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+        "additionalProperties": false
+      }
+    }
+  ],
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "description": "Enable or disable Cortex Memory plugin",
+        "default": true
+      },
+      "apiUrl": {
+        "type": "string",
+        "description": "URL of the memory service API",
+        "default": "http://127.0.0.1:8765"
+      },
+      "engineMode": {
+        "type": "string",
+        "description": "Memory engine mode",
+        "enum": ["ts"],
+        "default": "ts"
+      },
+      "dbPath": {
+        "type": "string",
+        "description": "Path to the memory database directory"
+      },
+      "autoSync": {
+        "type": "boolean",
+        "description": "Automatically sync memory on session end",
+        "default": true
+      },
+      "autoReflect": {
+        "type": "boolean",
+        "description": "Automatically trigger reflection periodically",
+        "default": false
+      },
+      "embedding": {
+        "type": "object",
+        "description": "Embedding model configuration",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "Embedding provider name"
+          },
+          "model": {
+            "type": "string",
+            "description": "Embedding model name"
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "Embedding API key"
+          },
+          "baseURL": {
+            "type": "string",
+            "description": "Embedding API base URL"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Embedding API base URL (camelCase alias)"
+          },
+          "dimensions": {
+            "type": "integer",
+            "description": "Embedding dimensions"
+          }
+        },
+        "additionalProperties": false
+      },
+      "llm": {
+        "type": "object",
+        "description": "LLM configuration",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "LLM provider name"
+          },
+          "model": {
+            "type": "string",
+            "description": "LLM model name"
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "LLM API key"
+          },
+          "baseURL": {
+            "type": "string",
+            "description": "LLM API base URL"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "LLM API base URL (camelCase alias)"
+          }
+        },
+        "additionalProperties": false
+      },
+      "reranker": {
+        "type": "object",
+        "description": "Reranker configuration",
+        "properties": {
+          "provider": {
+            "type": "string",
+            "description": "Reranker provider name"
+          },
+          "model": {
+            "type": "string",
+            "description": "Reranker model name"
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "Reranker API key"
+          },
+          "baseURL": {
+            "type": "string",
+            "description": "Reranker API base URL"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "Reranker API base URL (camelCase alias)"
+          }
+        },
+        "additionalProperties": false
+      },
+      "fallbackToBuiltin": {
+        "type": "boolean",
+        "description": "Fallback to OpenClaw builtin memory when Cortex Memory fails",
+        "default": true
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "openclaw-cortex-memory",
+  "version": "0.1.0-Alpha.1",
+  "description": "Long-term memory system for OpenClaw AI Agent",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cortex-memory": "scripts/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').copyFileSync('openclaw.plugin.json','dist/openclaw.plugin.json')\"",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/install.js"
+  },
+  "keywords": [
+    "openclaw",
+    "memory",
+    "ai",
+    "agent",
+    "rag"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "undici": "^6.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^5.7.2"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.8"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist/",
+    "index.ts",
+    "scripts/cli.js",
+    "scripts/install.js",
+    "scripts/uninstall.js",
+    "openclaw.plugin.json",
+    "SKILL.md"
+  ],
+  "openclaw": {
+    "plugin": true,
+    "requiresPython": false,
+    "cli": "cortex-memory",
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
+}

package/scripts/cli.js

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+
+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 basePath = process.env.OPENCLAW_BASE_PATH || '';
+  const homePath = process.env.USERPROFILE || process.env.HOME || '';
+  const possiblePaths = [
+    explicitConfigPath,
+    basePath ? path.join(basePath, 'openclaw.json') : '',
+    path.join(process.cwd(), 'openclaw.json'),
+    homePath ? path.join(homePath, '.openclaw', 'openclaw.json') : '',
+  ];
+  
+  for (const p of possiblePaths) {
+    if (p && fs.existsSync(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+function loadConfig(configPath) {
+  if (!configPath || !fs.existsSync(configPath)) {
+    return { plugins: {} };
+  }
+  
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch (e) {
+    console.error(`Error loading config: ${e.message}`);
+    return { plugins: {} };
+  }
+}
+
+function saveConfig(configPath, config) {
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  console.log(`Configuration saved to: ${configPath}`);
+}
+
+function enablePlugin() {
+  const configPath = findOpenClawConfig();
+  
+  if (!configPath) {
+    const defaultPath = path.join(process.env.USERPROFILE || process.env.HOME || '', '.openclaw', 'openclaw.json');
+    console.log(`No config file found. Creating: ${defaultPath}`);
+    
+    const config = {
+      plugins: {
+        allow: [PLUGIN_NAME],
+        slots: {
+          memory: PLUGIN_NAME
+        },
+        entries: {
+          [PLUGIN_NAME]: {
+            enabled: true
+          }
+        }
+      }
+    };
+    saveConfig(defaultPath, config);
+    console.log(`Plugin '${PLUGIN_NAME}' has been enabled.`);
+    return;
+  }
+  
+  const config = loadConfig(configPath);
+  
+  if (!config.plugins) {
+    config.plugins = {};
+  }
+  if (!Array.isArray(config.plugins.allow)) {
+    config.plugins.allow = [];
+  }
+  if (!config.plugins.allow.includes(PLUGIN_NAME)) {
+    config.plugins.allow.push(PLUGIN_NAME);
+  }
+  if (!config.plugins.entries) {
+    config.plugins.entries = {};
+  }
+  
+  if (config.plugins.entries[PLUGIN_NAME]?.enabled === true) {
+    console.log(`Plugin '${PLUGIN_NAME}' is already enabled.`);
+    return;
+  }
+  
+  config.plugins.entries[PLUGIN_NAME] = {
+    ...config.plugins.entries[PLUGIN_NAME],
+    enabled: true
+  };
+  
+  if (!config.plugins.slots) {
+    config.plugins.slots = {};
+  }
+  config.plugins.slots.memory = PLUGIN_NAME;
+  
+  saveConfig(configPath, config);
+  console.log(`Plugin '${PLUGIN_NAME}' has been enabled.`);
+  console.log('The plugin will be activated on the next OpenClaw restart or config reload.');
+}
+
+function disablePlugin() {
+  const configPath = findOpenClawConfig();
+  
+  if (!configPath) {
+    console.error('No OpenClaw configuration file found.');
+    console.error('Please create an openclaw.json file first.');
+    process.exit(1);
+  }
+  
+  const config = loadConfig(configPath);
+  
+  if (!config.plugins?.entries?.[PLUGIN_NAME] || config.plugins.entries[PLUGIN_NAME].enabled !== false) {
+    if (!config.plugins) {
+      config.plugins = {};
+    }
+    if (!config.plugins.entries) {
+      config.plugins.entries = {};
+    }
+    
+    config.plugins.entries[PLUGIN_NAME] = {
+      ...config.plugins.entries[PLUGIN_NAME],
+      enabled: false
+    };
+    
+    saveConfig(configPath, config);
+    console.log(`Plugin '${PLUGIN_NAME}' has been disabled.`);
+    console.log('The plugin will be deactivated on the next OpenClaw restart or config reload.');
+  } else {
+    console.log(`Plugin '${PLUGIN_NAME}' is already disabled.`);
+  }
+}
+
+function getStatus() {
+  const configPath = findOpenClawConfig();
+  
+  console.log('Cortex Memory Plugin Status');
+  console.log('='.repeat(40));
+  
+  if (!configPath) {
+    console.log('Config file: Not found');
+    console.log('Status: Enabled (default)');
+    console.log('\nNote: Plugin is enabled by default when no config exists.');
+    return;
+  }
+  
+  console.log(`Config file: ${configPath}`);
+  
+  const config = loadConfig(configPath);
+  const pluginConfig = config.plugins?.entries?.[PLUGIN_NAME];
+  
+  if (!pluginConfig) {
+    console.log('Status: Enabled (default)');
+  } else {
+    console.log(`Status: ${pluginConfig.enabled === false ? 'Disabled' : 'Enabled'}`);
+  }
+  
+  console.log('\nConfiguration:');
+  console.log(JSON.stringify(pluginConfig || { enabled: true }, null, 2));
+}
+
+function runUninstall(args) {
+  const uninstallScript = path.join(__dirname, 'uninstall.js');
+  
+  if (!fs.existsSync(uninstallScript)) {
+    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);
+  });
+}
+
+function showHelp() {
+  console.log(`
+Cortex Memory Plugin CLI
+
+Usage: cortex-memory <command> [options]
+
+Commands:
+  enable              Enable the Cortex Memory plugin
+  disable             Disable the Cortex Memory plugin (fallback to builtin memory)
+  status              Show the current plugin status
+  uninstall [options] Uninstall the plugin completely
+  help                Show this help message
+
+Uninstall Options:
+  --keep-data         Keep memory data files (LanceDB, episodic memory, etc.)
+  --keep-config       Keep plugin entry in openclaw.json
+
+Examples:
+  cortex-memory enable              Enable the plugin
+  cortex-memory disable             Disable the plugin
+  cortex-memory status              Check current status
+  cortex-memory uninstall           Full uninstall (removes everything)
+  cortex-memory uninstall --keep-data  Keep memory data files
+
+Configuration:
+  The plugin state is stored in openclaw.json under:
+  {
+    "plugins": {
+      "allow": ["openclaw-cortex-memory"],
+      "entries": {
+        "openclaw-cortex-memory": {
+          "enabled": true/false
+        }
+      }
+    }
+  }
+
+Fallback Behavior:
+  When disabled, the plugin will fall back to OpenClaw's builtin
+  memory system if fallbackToBuiltin is true (default).
+`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+  
+  switch (command) {
+    case 'enable':
+      enablePlugin();
+      break;
+    case 'disable':
+      disablePlugin();
+      break;
+    case 'status':
+      getStatus();
+      break;
+    case 'uninstall':
+      runUninstall(args.slice(1));
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+      showHelp();
+      break;
+    default:
+      console.error(`Unknown command: ${command}`);
+      showHelp();
+      process.exit(1);
+  }
+}
+
+main();

package/scripts/install.js

@@ -0,0 +1,27 @@
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const rootDir = path.resolve(__dirname, "..");
+
+console.log("[Cortex Memory] Setting up TypeScript runtime...\n");
+
+try {
+  execSync("npm run build", {
+    cwd: rootDir,
+    stdio: "inherit",
+  });
+
+  const srcManifest = path.join(rootDir, "openclaw.plugin.json");
+  const distManifest = path.join(rootDir, "dist", "openclaw.plugin.json");
+  if (fs.existsSync(srcManifest)) {
+    fs.copyFileSync(srcManifest, distManifest);
+    console.log("Plugin manifest copied to dist/");
+  }
+
+  console.log("\n[SUCCESS] TypeScript setup complete");
+} catch (error) {
+  console.error("\n[ERROR] TypeScript setup failed");
+  console.error(error?.stack || error?.message || String(error));
+  process.exit(1);
+}