@usecortex_ai/openclaw-cortex-ai 0.1.1 → 0.1.2

package/commands/onboarding.ts

@@ -1,9 +1,24 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
 import * as readline from "node:readline"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { CortexClient } from "../client.ts"
 import type { CortexPluginConfig } from "../config.ts"
 import { log } from "../log.ts"
 
+// ── Defaults (used when config is not yet available) ──
+
+const DEFAULTS = {
+	subTenantId: "cortex-openclaw-plugin",
+	ignoreTerm: "cortex-ignore",
+	autoRecall: true,
+	autoCapture: true,
+	maxRecallResults: 10,
+	recallMode: "fast" as const,
+	graphContext: true,
+	debug: false,
+}
+
 // ── ANSI helpers ──
 
 const c = {
@@ -160,57 +175,71 @@ type WizardResult = {
 	debug?: boolean
 }
 
-function buildConfigJson(result: WizardResult): string {
+function buildConfigObj(result: WizardResult): Record<string, unknown> {
 	const obj: Record<string, unknown> = {}
 
-	if (result.apiKey && !result.apiKey.startsWith("$")) {
-		obj.apiKey = result.apiKey
-	}
-	if (result.tenantId && !result.tenantId.startsWith("$")) {
-		obj.tenantId = result.tenantId
-	}
-	if (result.subTenantId !== "cortex-openclaw-plugin") {
+	obj.apiKey = result.apiKey
+	obj.tenantId = result.tenantId
+
+	if (result.subTenantId !== DEFAULTS.subTenantId) {
 		obj.subTenantId = result.subTenantId
 	}
-	if (result.ignoreTerm !== "cortex-ignore") {
+	if (result.ignoreTerm !== DEFAULTS.ignoreTerm) {
 		obj.ignoreTerm = result.ignoreTerm
 	}
-	if (result.autoRecall !== undefined && result.autoRecall !== true) {
+	if (result.autoRecall !== undefined && result.autoRecall !== DEFAULTS.autoRecall) {
 		obj.autoRecall = result.autoRecall
 	}
-	if (result.autoCapture !== undefined && result.autoCapture !== true) {
+	if (result.autoCapture !== undefined && result.autoCapture !== DEFAULTS.autoCapture) {
 		obj.autoCapture = result.autoCapture
 	}
-	if (result.maxRecallResults !== undefined && result.maxRecallResults !== 10) {
+	if (result.maxRecallResults !== undefined && result.maxRecallResults !== DEFAULTS.maxRecallResults) {
 		obj.maxRecallResults = result.maxRecallResults
 	}
-	if (result.recallMode !== undefined && result.recallMode !== "fast") {
+	if (result.recallMode !== undefined && result.recallMode !== DEFAULTS.recallMode) {
 		obj.recallMode = result.recallMode
 	}
-	if (result.graphContext !== undefined && result.graphContext !== true) {
+	if (result.graphContext !== undefined && result.graphContext !== DEFAULTS.graphContext) {
 		obj.graphContext = result.graphContext
 	}
-	if (result.debug !== undefined && result.debug !== false) {
+	if (result.debug !== undefined && result.debug !== DEFAULTS.debug) {
 		obj.debug = result.debug
 	}
 
-	return JSON.stringify(obj, null, 2)
+	return obj
 }
 
-function buildEnvLines(result: WizardResult): string[] {
-	const lines: string[] = []
-	if (result.apiKey && !result.apiKey.startsWith("$")) {
-		lines.push(`CORTEX_OPENCLAW_API_KEY=${result.apiKey}`)
-	}
-	if (result.tenantId && !result.tenantId.startsWith("$")) {
-		lines.push(`CORTEX_OPENCLAW_TENANT_ID=${result.tenantId}`)
+// ── Persist to ~/.openclaw/openclaw.json ──
+
+const OPENCLAW_CONFIG_PATH = path.join(
+	process.env.HOME ?? process.env.USERPROFILE ?? "~",
+	".openclaw",
+	"openclaw.json",
+)
+
+function persistConfig(configObj: Record<string, unknown>): boolean {
+	try {
+		const raw = fs.readFileSync(OPENCLAW_CONFIG_PATH, "utf-8")
+		const root = JSON.parse(raw)
+
+		if (!root.plugins) root.plugins = {}
+		if (!root.plugins.entries) root.plugins.entries = {}
+		if (!root.plugins.entries["openclaw-cortex-ai"]) {
+			root.plugins.entries["openclaw-cortex-ai"] = { enabled: true }
+		}
+
+		root.plugins.entries["openclaw-cortex-ai"].config = configObj
+
+		fs.writeFileSync(OPENCLAW_CONFIG_PATH, JSON.stringify(root, null, 2) + "\n")
+		return true
+	} catch {
+		return false
 	}
-	return lines
 }
 
 // ── Wizards ──
 
-async function runBasicWizard(cfg: CortexPluginConfig): Promise<void> {
+async function runBasicWizard(cfg?: CortexPluginConfig): Promise<void> {
 	const rl = createRl()
 
 	try {
@@ -232,14 +261,15 @@ async function runBasicWizard(cfg: CortexPluginConfig): Promise<void> {
 		printSection("Customisation")
 
 		const subTenantId = await promptText(rl, "Sub-Tenant ID", {
-			default: cfg.subTenantId,
+			default: cfg?.subTenantId ?? DEFAULTS.subTenantId,
 		})
 
 		const ignoreTerm = await promptText(rl, "Ignore Term", {
-			default: cfg.ignoreTerm,
+			default: cfg?.ignoreTerm ?? DEFAULTS.ignoreTerm,
 		})
 
 		const result: WizardResult = { apiKey, tenantId, subTenantId, ignoreTerm }
+		const configObj = buildConfigObj(result)
 
 		// ── Summary ──
 
@@ -252,35 +282,35 @@ async function runBasicWizard(cfg: CortexPluginConfig): Promise<void> {
 		printSummaryRow("Ignore Term", ignoreTerm)
 		console.log(`  ${c.dim}└${"─".repeat(50)}${c.reset}`)
 
-		// ── Output config ──
+		// ── Persist config ──
 
-		const envLines = buildEnvLines(result)
-		if (envLines.length > 0) {
-			console.log()
-			console.log(`  ${c.yellow}${c.bold}Add to your .env file:${c.reset}`)
+		const saved = await promptBool(rl, `Write config to ${OPENCLAW_CONFIG_PATH}?`, true)
+
+		if (saved && persistConfig(configObj)) {
+			printSuccess("Config saved! Restart the gateway (`openclaw gateway restart`) to apply.")
+		} else if (saved) {
+			console.log(`  ${c.red}Failed to write config. Add manually:${c.reset}`)
 			console.log()
-			for (const line of envLines) {
-				console.log(`    ${c.green}${line}${c.reset}`)
+			for (const line of JSON.stringify(configObj, null, 2).split("\n")) {
+				console.log(`    ${c.cyan}${line}${c.reset}`)
 			}
-		}
-
-		const json = buildConfigJson(result)
-		if (json !== "{}") {
+		} else {
 			console.log()
-			console.log(`  ${c.yellow}${c.bold}Plugin config (openclaw.plugin.json / settings):${c.reset}`)
+			console.log(`  ${c.yellow}${c.bold}Add to openclaw.json plugins.entries.openclaw-cortex-ai.config:${c.reset}`)
 			console.log()
-			for (const line of json.split("\n")) {
+			for (const line of JSON.stringify(configObj, null, 2).split("\n")) {
 				console.log(`    ${c.cyan}${line}${c.reset}`)
 			}
 		}
 
-		printSuccess("Onboarding complete! Run `cortex onboard --advanced` to fine-tune all options.")
+		console.log()
+		console.log(`  ${c.dim}Run \`cortex onboard --advanced\` to fine-tune all options.${c.reset}`)
 	} finally {
 		rl.close()
 	}
 }
 
-async function runAdvancedWizard(cfg: CortexPluginConfig): Promise<void> {
+async function runAdvancedWizard(cfg?: CortexPluginConfig): Promise<void> {
 	const rl = createRl()
 
 	try {
@@ -300,30 +330,30 @@ async function runAdvancedWizard(cfg: CortexPluginConfig): Promise<void> {
 		})
 
 		const subTenantId = await promptText(rl, "Sub-Tenant ID", {
-			default: cfg.subTenantId,
+			default: cfg?.subTenantId ?? DEFAULTS.subTenantId,
 		})
 
 		printSection("Behaviour")
 
-		const autoRecall = await promptBool(rl, "Enable Auto-Recall?", cfg.autoRecall)
-		const autoCapture = await promptBool(rl, "Enable Auto-Capture?", cfg.autoCapture)
+		const autoRecall = await promptBool(rl, "Enable Auto-Recall?", cfg?.autoRecall ?? DEFAULTS.autoRecall)
+		const autoCapture = await promptBool(rl, "Enable Auto-Capture?", cfg?.autoCapture ?? DEFAULTS.autoCapture)
 		const ignoreTerm = await promptText(rl, "Ignore Term", {
-			default: cfg.ignoreTerm,
+			default: cfg?.ignoreTerm ?? DEFAULTS.ignoreTerm,
 		})
 
 		printSection("Recall Settings")
 
 		const maxRecallResults = await promptNumber(
-			rl, "Max Recall Results", cfg.maxRecallResults, 1, 50,
+			rl, "Max Recall Results", cfg?.maxRecallResults ?? DEFAULTS.maxRecallResults, 1, 50,
 		)
 		const recallMode = await promptChoice(
-			rl, "Recall Mode", ["fast", "thinking"], cfg.recallMode,
+			rl, "Recall Mode", ["fast", "thinking"], cfg?.recallMode ?? DEFAULTS.recallMode,
 		) as "fast" | "thinking"
-		const graphContext = await promptBool(rl, "Enable Graph Context?", cfg.graphContext)
+		const graphContext = await promptBool(rl, "Enable Graph Context?", cfg?.graphContext ?? DEFAULTS.graphContext)
 
 		printSection("Debug")
 
-		const debug = await promptBool(rl, "Enable Debug Logging?", cfg.debug)
+		const debug = await promptBool(rl, "Enable Debug Logging?", cfg?.debug ?? DEFAULTS.debug)
 
 		const result: WizardResult = {
 			apiKey,
@@ -355,29 +385,27 @@ async function runAdvancedWizard(cfg: CortexPluginConfig): Promise<void> {
 		printSummaryRow("Debug", String(debug))
 		console.log(`  ${c.dim}└${"─".repeat(50)}${c.reset}`)
 
-		// ── Output config ──
+		// ── Persist config ──
 
-		const envLines = buildEnvLines(result)
-		if (envLines.length > 0) {
-			console.log()
-			console.log(`  ${c.yellow}${c.bold}Add to your .env file:${c.reset}`)
+		const configObj = buildConfigObj(result)
+		const saved = await promptBool(rl, `Write config to ${OPENCLAW_CONFIG_PATH}?`, true)
+
+		if (saved && persistConfig(configObj)) {
+			printSuccess("Config saved! Restart the gateway (`openclaw gateway restart`) to apply.")
+		} else if (saved) {
+			console.log(`  ${c.red}Failed to write config. Add manually:${c.reset}`)
 			console.log()
-			for (const line of envLines) {
-				console.log(`    ${c.green}${line}${c.reset}`)
+			for (const line of JSON.stringify(configObj, null, 2).split("\n")) {
+				console.log(`    ${c.cyan}${line}${c.reset}`)
 			}
-		}
-
-		const json = buildConfigJson(result)
-		if (json !== "{}") {
+		} else {
 			console.log()
-			console.log(`  ${c.yellow}${c.bold}Plugin config (openclaw.plugin.json / settings):${c.reset}`)
+			console.log(`  ${c.yellow}${c.bold}Add to openclaw.json plugins.entries.openclaw-cortex-ai.config:${c.reset}`)
 			console.log()
-			for (const line of json.split("\n")) {
+			for (const line of JSON.stringify(configObj, null, 2).split("\n")) {
 				console.log(`    ${c.cyan}${line}${c.reset}`)
 			}
 		}
-
-		printSuccess("Onboarding complete! All options configured.")
 	} finally {
 		rl.close()
 	}
@@ -386,7 +414,7 @@ async function runAdvancedWizard(cfg: CortexPluginConfig): Promise<void> {
 // ── Registration (CLI + Slash) ──
 
 export function registerOnboardingCli(
-	cfg: CortexPluginConfig,
+	cfg?: CortexPluginConfig,
 ): (root: any) => void {
 	return (root: any) => {
 		root

package/config.ts

@@ -97,6 +97,32 @@ export function parseConfig(raw: unknown): CortexPluginConfig {
 	}
 }
 
+export function tryParseConfig(raw: unknown): CortexPluginConfig | null {
+	try {
+		return parseConfig(raw)
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Permissive schema parse — validates key names but does NOT require credentials.
+ * This lets the plugin load so the onboarding wizard can run.
+ */
+function parseConfigSoft(raw: unknown): Record<string, unknown> {
+	const cfg =
+		raw && typeof raw === "object" && !Array.isArray(raw)
+			? (raw as Record<string, unknown>)
+			: {}
+
+	const unknown = Object.keys(cfg).filter((k) => !KNOWN_KEYS.has(k))
+	if (unknown.length > 0) {
+		throw new Error(`cortex-ai: unrecognized config keys: ${unknown.join(", ")}`)
+	}
+
+	return cfg
+}
+
 export const cortexConfigSchema = {
-	parse: parseConfig,
+	parse: parseConfigSoft,
 }

package/index.ts

@@ -1,9 +1,9 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { CortexClient } from "./client.ts"
-import { registerCliCommands } from "./commands/cli.ts"
-import { registerOnboardingCli, registerOnboardingSlashCommands } from "./commands/onboarding.ts"
+import type { CortexPluginConfig } from "./config.ts"
+import { registerOnboardingCli as createOnboardingCliRegistrar, registerOnboardingSlashCommands } from "./commands/onboarding.ts"
 import { registerSlashCommands } from "./commands/slash.ts"
-import { cortexConfigSchema, parseConfig } from "./config.ts"
+import { cortexConfigSchema, tryParseConfig } from "./config.ts"
 import { createIngestionHook } from "./hooks/capture.ts"
 import { createRecallHook } from "./hooks/recall.ts"
 import { log } from "./log.ts"
@@ -13,6 +13,9 @@ import { registerListTool } from "./tools/list.ts"
 import { registerSearchTool } from "./tools/search.ts"
 import { registerStoreTool } from "./tools/store.ts"
 
+const NOT_CONFIGURED_MSG =
+	"[cortex-ai] Not configured. Run `openclaw cortex onboard` to set up credentials."
+
 export default {
 	id: "openclaw-cortex-ai",
 	name: "Cortex AI",
@@ -22,8 +25,33 @@ export default {
 	configSchema: cortexConfigSchema,
 
 	register(api: OpenClawPluginApi) {
-		const cfg = parseConfig(api.pluginConfig)
+		const cfg = tryParseConfig(api.pluginConfig)
+		const cliClient = cfg ? new CortexClient(cfg.apiKey, cfg.tenantId, cfg.subTenantId) : null
+
+		// Always register ALL CLI commands so they appear in help text.
+		// Non-onboard commands guard on credentials at runtime.
+		api.registerCli(
+			({ program }: { program: any }) => {
+				const root = program
+					.command("cortex")
+					.description("Cortex AI memory commands")
+
+				createOnboardingCliRegistrar(cfg ?? undefined)(root)
+				registerCortexCliCommands(root, cliClient, cfg)
+			},
+			{ commands: ["cortex"] },
+		)
 
+		if (!cfg) {
+			api.registerService({
+				id: "openclaw-cortex-ai",
+				start: () => console.log(NOT_CONFIGURED_MSG),
+				stop: () => {},
+			})
+			return
+		}
+
+		// Full plugin registration — credentials present
 		log.init(api.logger, cfg.debug)
 
 		const client = new CortexClient(cfg.apiKey, cfg.tenantId, cfg.subTenantId)
@@ -67,7 +95,6 @@ export default {
 
 		registerSlashCommands(api, client, cfg, getSessionId)
 		registerOnboardingSlashCommands(api, client, cfg)
-		registerCliCommands(api, client, cfg, registerOnboardingCli(cfg))
 
 		api.registerService({
 			id: "openclaw-cortex-ai",
@@ -76,3 +103,110 @@ export default {
 		})
 	},
 }
+
+/**
+ * Register all `cortex *` CLI subcommands.
+ * Commands other than `onboard` guard on valid credentials at runtime.
+ */
+function registerCortexCliCommands(
+	root: any,
+	client: CortexClient | null,
+	cfg: CortexPluginConfig | null,
+): void {
+	const requireCreds = (): { client: CortexClient; cfg: CortexPluginConfig } | null => {
+		if (client && cfg) return { client, cfg }
+		console.error(NOT_CONFIGURED_MSG)
+		return null
+	}
+
+	root
+		.command("search")
+		.argument("<query>", "Search query")
+		.option("--limit <n>", "Max results", "10")
+		.action(async (query: string, opts: { limit: string }) => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const limit = Number.parseInt(opts.limit, 10) || 10
+			const res = await ctx.client.recall(query, {
+				maxResults: limit,
+				mode: ctx.cfg.recallMode,
+				graphContext: ctx.cfg.graphContext,
+			})
+
+			if (!res.chunks || res.chunks.length === 0) {
+				console.log("No memories found.")
+				return
+			}
+
+			for (const chunk of res.chunks) {
+				const score = chunk.relevancy_score != null
+					? ` (${(chunk.relevancy_score * 100).toFixed(0)}%)`
+					: ""
+				const title = chunk.source_title ? `[${chunk.source_title}] ` : ""
+				console.log(`- ${title}${chunk.chunk_content.slice(0, 200)}${score}`)
+			}
+		})
+
+	root
+		.command("list")
+		.description("List all user memories")
+		.action(async () => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const res = await ctx.client.listMemories()
+			const memories = res.user_memories ?? []
+			if (memories.length === 0) {
+				console.log("No memories stored.")
+				return
+			}
+			for (const m of memories) {
+				console.log(`[${m.memory_id}] ${m.memory_content.slice(0, 150)}`)
+			}
+			console.log(`\nTotal: ${memories.length}`)
+		})
+
+	root
+		.command("delete")
+		.argument("<memory_id>", "Memory ID to delete")
+		.action(async (memoryId: string) => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const res = await ctx.client.deleteMemory(memoryId)
+			console.log(res.user_memory_deleted ? `Deleted: ${memoryId}` : `Not found: ${memoryId}`)
+		})
+
+	root
+		.command("get")
+		.argument("<source_id>", "Source ID to fetch")
+		.action(async (sourceId: string) => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			const res = await ctx.client.fetchContent(sourceId)
+			if (!res.success || res.error) {
+				console.error(`Error: ${res.error ?? "unknown"}`)
+				return
+			}
+			console.log(res.content ?? res.content_base64 ?? "(no text content)")
+		})
+
+	root
+		.command("status")
+		.description("Show plugin configuration")
+		.action(() => {
+			const ctx = requireCreds()
+			if (!ctx) return
+
+			console.log(`Tenant:       ${ctx.client.getTenantId()}`)
+			console.log(`Sub-Tenant:   ${ctx.client.getSubTenantId()}`)
+			console.log(`Auto-Recall:  ${ctx.cfg.autoRecall}`)
+			console.log(`Auto-Capture: ${ctx.cfg.autoCapture}`)
+			console.log(`Recall Mode:  ${ctx.cfg.recallMode}`)
+			console.log(`Graph:        ${ctx.cfg.graphContext}`)
+			console.log(`Max Results:  ${ctx.cfg.maxRecallResults}`)
+			console.log(`Ignore Term:  ${ctx.cfg.ignoreTerm}`)
+		})
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usecortex_ai/openclaw-cortex-ai",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "OpenClaw plugin for Cortex AI — the State-of-the-art agentic memory system with auto-capture, recall, and knowledge graph context for open-claw",
   "license": "MIT",