@usecortex_ai/openclaw-cortex-ai 0.1.0 → 0.1.2

package/README.md

@@ -47,6 +47,7 @@ Or configure directly in `openclaw.json`:
 | `maxRecallResults` | `number`  | `10`                | Max memory chunks injected into context per turn                               |
 | `recallMode`       | `string`  | `"fast"`            | `"fast"` or `"thinking"` (deeper personalised recall with graph traversal) |
 | `graphContext`     | `boolean` | `true`              | Include knowledge graph relations in recalled context                          |
+| `ignoreTerm`       | `string`  | `"cortex-ignore"`    | Messages containing this term are excluded from recall & capture              |
 | `debug`            | `boolean` | `false`             | Verbose debug logs                                                             |
 
 ## How It Works
@@ -54,10 +55,28 @@ Or configure directly in `openclaw.json`:
 - **Auto-Recall** — Before every AI turn, queries Cortex (`/recall/recall_preferences`) for relevant memories and injects graph-enriched context (entity paths, chunk relations, extra context).
 - **Auto-Capture** — After every AI turn, the last user/assistant exchange is sent to Cortex (`/memories/add_memory`) as conversation pairs with `infer: true` and `upsert: true`. The session ID is used as `source_id` so Cortex groups exchanges per session and builds a knowledge graph automatically.
 
+## Interactive Onboarding
+
+Run the interactive CLI wizard to configure Cortex AI:
+
+```bash
+# Basic onboarding (API key, tenant ID, sub-tenant, ignore term)
+openclaw cortex onboard
+
+# Advanced onboarding (all options including recall mode, graph context, etc.)
+openclaw cortex onboard --advanced
+```
+
+The wizard guides you through configuration with colored prompts, validates inputs, and outputs:
+- `.env` file lines for credentials
+- Plugin config JSON for non-default settings
+- A summary table with masked sensitive values
+
 ## Slash Commands
 
 | Command                     | Description                           |
 | --------------------------- | ------------------------------------- |
+| `/cortex-onboard`          | Show current configuration status     |
 | `/cortex-remember <text>` | Save something to Cortex memory       |
 | `/cortex-recall <query>`  | Search memories with relevance scores |
 | `/cortex-list`            | List all stored user memories         |
@@ -74,11 +93,13 @@ Or configure directly in `openclaw.json`:
 ## CLI
 
 ```bash
-openclaw cortex search <query>     # Search memories
-	               # List all user memories
-openclaw cortex delete <id>        # Delete a memory
-openclaw cortex get <source_id>    # Fetch source content
-openclaw cortex status             # Show plugin configuration
+openclaw cortex onboard             # Interactive onboarding wizard
+openclaw cortex onboard --advanced  # Advanced onboarding wizard
+openclaw cortex search <query>      # Search memories
+openclaw cortex list                # List all user memories
+openclaw cortex delete <id>         # Delete a memory
+openclaw cortex get <source_id>     # Fetch source content
+openclaw cortex status              # Show plugin configuration
 ```
 
 ## Context Injection
@@ -86,5 +107,4 @@ openclaw cortex status             # Show plugin configuration
 Recalled context is injected inside `<cortex-context>` tags containing:
 
 - **Entity Paths** — Knowledge graph paths connecting entities relevant to the query
-- **
-      Context Chunks** — Retrieved memory chunks with source titles, graph relations, and linked extra context
+- **Context Chunks** — Retrieved memory chunks with source titles, graph relations, and linked extra context

package/commands/cli.ts

@@ -6,6 +6,7 @@ export function registerCliCommands(
 	api: OpenClawPluginApi,
 	client: CortexClient,
 	cfg: CortexPluginConfig,
+	onboardingRegistrar?: (root: any) => void,
 ): void {
 	api.registerCli(
 		({ program }: { program: any }) => {
@@ -86,7 +87,10 @@ export function registerCliCommands(
 					console.log(`Recall Mode:  ${cfg.recallMode}`)
 					console.log(`Graph:        ${cfg.graphContext}`)
 					console.log(`Max Results:  ${cfg.maxRecallResults}`)
+					console.log(`Ignore Term:  ${cfg.ignoreTerm}`)
 				})
+
+			if (onboardingRegistrar) onboardingRegistrar(root)
 		},
 		{ commands: ["cortex"] },
 	)

package/commands/onboarding.ts

@@ -0,0 +1,470 @@
+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 = {
+	reset: "\x1b[0m",
+	bold: "\x1b[1m",
+	dim: "\x1b[2m",
+	cyan: "\x1b[36m",
+	green: "\x1b[32m",
+	yellow: "\x1b[33m",
+	red: "\x1b[31m",
+	magenta: "\x1b[35m",
+	white: "\x1b[37m",
+	bgCyan: "\x1b[46m",
+	bgGreen: "\x1b[42m",
+	black: "\x1b[30m",
+}
+
+function mask(value: string, visible = 4): string {
+	if (value.length <= visible) return "****"
+	return `${"*".repeat(value.length - visible)}${value.slice(-visible)}`
+}
+
+// ── Prompt primitives ──
+
+function createRl(): readline.Interface {
+	return readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	})
+}
+
+function ask(rl: readline.Interface, question: string): Promise<string> {
+	return new Promise((resolve) => rl.question(question, resolve))
+}
+
+async function promptText(
+	rl: readline.Interface,
+	label: string,
+	opts?: { default?: string; required?: boolean; secret?: boolean },
+): Promise<string> {
+	const def = opts?.default
+	const hint = def ? `${c.dim} (${def})${c.reset}` : opts?.required ? `${c.red} *${c.reset}` : ""
+	const prefix = `  ${c.cyan}?${c.reset} ${c.bold}${label}${c.reset}${hint}${c.dim} ›${c.reset} `
+
+	while (true) {
+		const raw = await ask(rl, prefix)
+		const value = raw.trim()
+		if (value) return value
+		if (def) return def
+		if (opts?.required) {
+			console.log(`    ${c.red}This field is required.${c.reset}`)
+			continue
+		}
+		return ""
+	}
+}
+
+async function promptChoice(
+	rl: readline.Interface,
+	label: string,
+	choices: string[],
+	defaultChoice: string,
+): Promise<string> {
+	const tags = choices
+		.map((ch) => (ch === defaultChoice ? `${c.green}${c.bold}${ch}${c.reset}` : `${c.dim}${ch}${c.reset}`))
+		.join(`${c.dim} / ${c.reset}`)
+
+	const prefix = `  ${c.cyan}?${c.reset} ${c.bold}${label}${c.reset} ${tags}${c.dim} ›${c.reset} `
+
+	while (true) {
+		const raw = await ask(rl, prefix)
+		const value = raw.trim().toLowerCase()
+		if (!value) return defaultChoice
+		const match = choices.find((ch) => ch.toLowerCase() === value)
+		if (match) return match
+		console.log(`    ${c.yellow}Choose one of: ${choices.join(", ")}${c.reset}`)
+	}
+}
+
+async function promptBool(
+	rl: readline.Interface,
+	label: string,
+	defaultVal: boolean,
+): Promise<boolean> {
+	const hint = defaultVal
+		? `${c.dim} (${c.green}Y${c.reset}${c.dim}/n)${c.reset}`
+		: `${c.dim} (y/${c.green}N${c.reset}${c.dim})${c.reset}`
+	const prefix = `  ${c.cyan}?${c.reset} ${c.bold}${label}${c.reset}${hint}${c.dim} ›${c.reset} `
+
+	const raw = await ask(rl, prefix)
+	const value = raw.trim().toLowerCase()
+	if (!value) return defaultVal
+	return value === "y" || value === "yes" || value === "true"
+}
+
+async function promptNumber(
+	rl: readline.Interface,
+	label: string,
+	defaultVal: number,
+	min: number,
+	max: number,
+): Promise<number> {
+	const prefix = `  ${c.cyan}?${c.reset} ${c.bold}${label}${c.reset}${c.dim} (${defaultVal}) [${min}–${max}] ›${c.reset} `
+
+	while (true) {
+		const raw = await ask(rl, prefix)
+		const value = raw.trim()
+		if (!value) return defaultVal
+		const n = Number.parseInt(value, 10)
+		if (!Number.isNaN(n) && n >= min && n <= max) return n
+		console.log(`    ${c.yellow}Enter a number between ${min} and ${max}.${c.reset}`)
+	}
+}
+
+// ── Banner ──
+
+function printBanner(): void {
+	console.log()
+	console.log(`  ${c.bgCyan}${c.black}${c.bold}                              ${c.reset}`)
+	console.log(`  ${c.bgCyan}${c.black}${c.bold}    ◆  Cortex AI — Onboard    ${c.reset}`)
+	console.log(`  ${c.bgCyan}${c.black}${c.bold}                              ${c.reset}`)
+	console.log()
+}
+
+function printSection(title: string): void {
+	console.log()
+	console.log(`  ${c.magenta}${c.bold}── ${title} ${"─".repeat(Math.max(0, 40 - title.length))}${c.reset}`)
+	console.log()
+}
+
+function printSummaryRow(label: string, value: string, sensitive = false): void {
+	const display = sensitive ? mask(value) : value
+	console.log(`  ${c.dim}│${c.reset}  ${c.bold}${label.padEnd(18)}${c.reset} ${c.cyan}${display}${c.reset}`)
+}
+
+function printSuccess(msg: string): void {
+	console.log()
+	console.log(`  ${c.bgGreen}${c.black}${c.bold} ✓ ${c.reset} ${c.green}${msg}${c.reset}`)
+	console.log()
+}
+
+// ── Config output ──
+
+type WizardResult = {
+	apiKey: string
+	tenantId: string
+	subTenantId: string
+	ignoreTerm: string
+	autoRecall?: boolean
+	autoCapture?: boolean
+	maxRecallResults?: number
+	recallMode?: "fast" | "thinking"
+	graphContext?: boolean
+	debug?: boolean
+}
+
+function buildConfigObj(result: WizardResult): Record<string, unknown> {
+	const obj: Record<string, unknown> = {}
+
+	obj.apiKey = result.apiKey
+	obj.tenantId = result.tenantId
+
+	if (result.subTenantId !== DEFAULTS.subTenantId) {
+		obj.subTenantId = result.subTenantId
+	}
+	if (result.ignoreTerm !== DEFAULTS.ignoreTerm) {
+		obj.ignoreTerm = result.ignoreTerm
+	}
+	if (result.autoRecall !== undefined && result.autoRecall !== DEFAULTS.autoRecall) {
+		obj.autoRecall = result.autoRecall
+	}
+	if (result.autoCapture !== undefined && result.autoCapture !== DEFAULTS.autoCapture) {
+		obj.autoCapture = result.autoCapture
+	}
+	if (result.maxRecallResults !== undefined && result.maxRecallResults !== DEFAULTS.maxRecallResults) {
+		obj.maxRecallResults = result.maxRecallResults
+	}
+	if (result.recallMode !== undefined && result.recallMode !== DEFAULTS.recallMode) {
+		obj.recallMode = result.recallMode
+	}
+	if (result.graphContext !== undefined && result.graphContext !== DEFAULTS.graphContext) {
+		obj.graphContext = result.graphContext
+	}
+	if (result.debug !== undefined && result.debug !== DEFAULTS.debug) {
+		obj.debug = result.debug
+	}
+
+	return obj
+}
+
+// ── 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
+	}
+}
+
+// ── Wizards ──
+
+async function runBasicWizard(cfg?: CortexPluginConfig): Promise<void> {
+	const rl = createRl()
+
+	try {
+		printBanner()
+		console.log(`  ${c.dim}Configure the essential settings for Cortex AI.${c.reset}`)
+		console.log(`  ${c.dim}Press Enter to accept defaults shown in parentheses.${c.reset}`)
+
+		printSection("Credentials")
+
+		const apiKey = await promptText(rl, "API Key", {
+			required: true,
+			secret: true,
+		})
+
+		const tenantId = await promptText(rl, "Tenant ID", {
+			required: true,
+		})
+
+		printSection("Customisation")
+
+		const subTenantId = await promptText(rl, "Sub-Tenant ID", {
+			default: cfg?.subTenantId ?? DEFAULTS.subTenantId,
+		})
+
+		const ignoreTerm = await promptText(rl, "Ignore Term", {
+			default: cfg?.ignoreTerm ?? DEFAULTS.ignoreTerm,
+		})
+
+		const result: WizardResult = { apiKey, tenantId, subTenantId, ignoreTerm }
+		const configObj = buildConfigObj(result)
+
+		// ── Summary ──
+
+		printSection("Summary")
+
+		console.log(`  ${c.dim}┌${"─".repeat(50)}${c.reset}`)
+		printSummaryRow("API Key", apiKey, true)
+		printSummaryRow("Tenant ID", tenantId)
+		printSummaryRow("Sub-Tenant ID", subTenantId)
+		printSummaryRow("Ignore Term", ignoreTerm)
+		console.log(`  ${c.dim}└${"─".repeat(50)}${c.reset}`)
+
+		// ── Persist config ──
+
+		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 JSON.stringify(configObj, null, 2).split("\n")) {
+				console.log(`    ${c.cyan}${line}${c.reset}`)
+			}
+		} else {
+			console.log()
+			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.stringify(configObj, null, 2).split("\n")) {
+				console.log(`    ${c.cyan}${line}${c.reset}`)
+			}
+		}
+
+		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> {
+	const rl = createRl()
+
+	try {
+		printBanner()
+		console.log(`  ${c.dim}Full configuration wizard — customise every option.${c.reset}`)
+		console.log(`  ${c.dim}Press Enter to accept defaults shown in parentheses.${c.reset}`)
+
+		printSection("Credentials")
+
+		const apiKey = await promptText(rl, "API Key", {
+			required: true,
+			secret: true,
+		})
+
+		const tenantId = await promptText(rl, "Tenant ID", {
+			required: true,
+		})
+
+		const subTenantId = await promptText(rl, "Sub-Tenant ID", {
+			default: cfg?.subTenantId ?? DEFAULTS.subTenantId,
+		})
+
+		printSection("Behaviour")
+
+		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 ?? DEFAULTS.ignoreTerm,
+		})
+
+		printSection("Recall Settings")
+
+		const maxRecallResults = await promptNumber(
+			rl, "Max Recall Results", cfg?.maxRecallResults ?? DEFAULTS.maxRecallResults, 1, 50,
+		)
+		const recallMode = await promptChoice(
+			rl, "Recall Mode", ["fast", "thinking"], cfg?.recallMode ?? DEFAULTS.recallMode,
+		) as "fast" | "thinking"
+		const graphContext = await promptBool(rl, "Enable Graph Context?", cfg?.graphContext ?? DEFAULTS.graphContext)
+
+		printSection("Debug")
+
+		const debug = await promptBool(rl, "Enable Debug Logging?", cfg?.debug ?? DEFAULTS.debug)
+
+		const result: WizardResult = {
+			apiKey,
+			tenantId,
+			subTenantId,
+			ignoreTerm,
+			autoRecall,
+			autoCapture,
+			maxRecallResults,
+			recallMode,
+			graphContext,
+			debug,
+		}
+
+		// ── Summary ──
+
+		printSection("Summary")
+
+		console.log(`  ${c.dim}┌${"─".repeat(50)}${c.reset}`)
+		printSummaryRow("API Key", apiKey, true)
+		printSummaryRow("Tenant ID", tenantId)
+		printSummaryRow("Sub-Tenant ID", subTenantId)
+		printSummaryRow("Auto-Recall", String(autoRecall))
+		printSummaryRow("Auto-Capture", String(autoCapture))
+		printSummaryRow("Ignore Term", ignoreTerm)
+		printSummaryRow("Max Results", String(maxRecallResults))
+		printSummaryRow("Recall Mode", recallMode)
+		printSummaryRow("Graph Context", String(graphContext))
+		printSummaryRow("Debug", String(debug))
+		console.log(`  ${c.dim}└${"─".repeat(50)}${c.reset}`)
+
+		// ── Persist config ──
+
+		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 JSON.stringify(configObj, null, 2).split("\n")) {
+				console.log(`    ${c.cyan}${line}${c.reset}`)
+			}
+		} else {
+			console.log()
+			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.stringify(configObj, null, 2).split("\n")) {
+				console.log(`    ${c.cyan}${line}${c.reset}`)
+			}
+		}
+	} finally {
+		rl.close()
+	}
+}
+
+// ── Registration (CLI + Slash) ──
+
+export function registerOnboardingCli(
+	cfg?: CortexPluginConfig,
+): (root: any) => void {
+	return (root: any) => {
+		root
+			.command("onboard")
+			.description("Interactive Cortex AI onboarding wizard")
+			.option("--advanced", "Configure all options (credentials, behaviour, recall, debug)")
+			.action(async (opts: { advanced?: boolean }) => {
+				if (opts.advanced) {
+					await runAdvancedWizard(cfg)
+				} else {
+					await runBasicWizard(cfg)
+				}
+			})
+	}
+}
+
+export function registerOnboardingSlashCommands(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	cfg: CortexPluginConfig,
+): void {
+	api.registerCommand({
+		name: "cortex-onboard",
+		description: "Show Cortex plugin config status (run `cortex onboard` in CLI for interactive wizard)",
+		acceptsArgs: false,
+		requireAuth: false,
+		handler: async () => {
+			try {
+				const lines: string[] = [
+					"=== Cortex AI — Current Config ===",
+					"",
+					`  API Key:       ${cfg.apiKey ? `${mask(cfg.apiKey)} ✓` : "NOT SET ✗"}`,
+					`  Tenant ID:     ${cfg.tenantId ? `${mask(cfg.tenantId, 8)} ✓` : "NOT SET ✗"}`,
+					`  Sub-Tenant:    ${client.getSubTenantId()}`,
+					`  Ignore Term:   ${cfg.ignoreTerm}`,
+					`  Auto-Recall:   ${cfg.autoRecall}`,
+					`  Auto-Capture:  ${cfg.autoCapture}`,
+					`  Recall Mode:   ${cfg.recallMode}`,
+					`  Graph Context: ${cfg.graphContext}`,
+					`  Max Results:   ${cfg.maxRecallResults}`,
+					`  Debug:         ${cfg.debug}`,
+					"",
+					"Tip: Run `cortex onboard` in the CLI for an interactive configuration wizard,",
+					"     or `cortex onboard --advanced` for all options.",
+				]
+				return { text: lines.join("\n") }
+			} catch (err) {
+				log.error("/cortex-onboard", err)
+				return { text: "Failed to show status. Check logs." }
+			}
+		},
+	})
+}

package/config.ts

@@ -7,6 +7,7 @@ export type CortexPluginConfig = {
 	maxRecallResults: number
 	recallMode: "fast" | "thinking"
 	graphContext: boolean
+	ignoreTerm: string
 	debug: boolean
 }
 
@@ -19,10 +20,12 @@ const KNOWN_KEYS = new Set([
 	"maxRecallResults",
 	"recallMode",
 	"graphContext",
+	"ignoreTerm",
 	"debug",
 ])
 
 const DEFAULT_SUB_TENANT = "cortex-openclaw-plugin"
+const DEFAULT_IGNORE_TERM = "cortex-ignore"
 
 function envOrNull(name: string): string | undefined {
 	return typeof process !== "undefined" ? process.env[name] : undefined
@@ -86,10 +89,40 @@ export function parseConfig(raw: unknown): CortexPluginConfig {
 				? ("thinking" as const)
 				: ("fast" as const),
 		graphContext: (cfg.graphContext as boolean) ?? true,
+		ignoreTerm:
+			typeof cfg.ignoreTerm === "string" && cfg.ignoreTerm.length > 0
+				? cfg.ignoreTerm
+				: DEFAULT_IGNORE_TERM,
 		debug: (cfg.debug as boolean) ?? false,
 	}
 }
 
+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/hooks/capture.ts

@@ -1,7 +1,7 @@
 import type { CortexClient } from "../client.ts"
 import type { CortexPluginConfig } from "../config.ts"
 import { log } from "../log.ts"
-import { extractAllTurns } from "../messages.ts"
+import { extractAllTurns, filterIgnoredTurns } from "../messages.ts"
 import { toHookSourceId } from "../session.ts"
 import type { ConversationTurn } from "../types/cortex.ts"
 
@@ -13,7 +13,7 @@ function removeInjectedBlocks(text: string): string {
 
 export function createIngestionHook(
 	client: CortexClient,
-	_cfg: CortexPluginConfig,
+	cfg: CortexPluginConfig,
 ) {
 	return async (event: Record<string, unknown>, sessionId: string | undefined) => {
 		try {
@@ -33,7 +33,12 @@ export function createIngestionHook(
 				return
 			}
 
-			const allTurns = extractAllTurns(event.messages)
+			const rawTurns = extractAllTurns(event.messages)
+			const allTurns = filterIgnoredTurns(rawTurns, cfg.ignoreTerm)
+
+			if (rawTurns.length > 0 && allTurns.length < rawTurns.length) {
+				log.debug(`[capture] filtered ${rawTurns.length - allTurns.length} turns containing ignore term "${cfg.ignoreTerm}"`)
+			}
 
 			if (allTurns.length === 0) {
 				log.debug(`[capture] skipped — no user-assistant turns found in ${event.messages.length} messages`)

package/hooks/recall.ts

@@ -2,6 +2,7 @@ import type { CortexClient } from "../client.ts"
 import type { CortexPluginConfig } from "../config.ts"
 import { buildRecalledContext, envelopeForInjection } from "../context.ts"
 import { log } from "../log.ts"
+import { containsIgnoreTerm } from "../messages.ts"
 
 export function createRecallHook(
 	client: CortexClient,
@@ -11,6 +12,11 @@ export function createRecallHook(
 		const prompt = event.prompt as string | undefined
 		if (!prompt || prompt.length < 5) return
 
+		if (containsIgnoreTerm(prompt, cfg.ignoreTerm)) {
+			log.debug(`recall skipped — prompt contains ignore term "${cfg.ignoreTerm}"`)
+			return
+		}
+
 		log.debug(`recall query (${prompt.length} chars)`)
 
 		try {

package/index.ts

@@ -1,8 +1,9 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { CortexClient } from "./client.ts"
-import { registerCliCommands } from "./commands/cli.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"
@@ -12,17 +13,45 @@ 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",
 	description:
-		"Long-term memory for OpenClaw powered by Cortex AI — auto-capture, recall, and graph-enriched context",
+		"State-of-the-art agentic memory for OpenClaw powered by Cortex AI — auto-capture, recall, and graph-enriched context",
 	kind: "memory" as const,
 	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)
@@ -65,7 +94,7 @@ export default {
 		}
 
 		registerSlashCommands(api, client, cfg, getSessionId)
-		registerCliCommands(api, client, cfg)
+		registerOnboardingSlashCommands(api, client, cfg)
 
 		api.registerService({
 			id: "openclaw-cortex-ai",
@@ -74,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/messages.ts

@@ -1,5 +1,20 @@
 import type { ConversationTurn } from "./types/cortex.ts"
 
+export function containsIgnoreTerm(text: string, ignoreTerm: string): boolean {
+	return text.toLowerCase().includes(ignoreTerm.toLowerCase())
+}
+
+export function filterIgnoredTurns(
+	turns: ConversationTurn[],
+	ignoreTerm: string,
+): ConversationTurn[] {
+	return turns.filter(
+		(t) =>
+			!containsIgnoreTerm(t.user, ignoreTerm) &&
+			!containsIgnoreTerm(t.assistant, ignoreTerm),
+	)
+}
+
 export function textFromMessage(msg: Record<string, unknown>): string {
 	const content = msg.content
 	if (typeof content === "string") return content

package/openclaw.plugin.json

@@ -43,6 +43,11 @@
 			"help": "Include knowledge graph relations in recalled context (default: true)",
 			"advanced": true
 		},
+		"ignoreTerm": {
+			"label": "Ignore Term",
+			"placeholder": "cortex-ignore",
+			"help": "Messages containing this term will be excluded from recall and capture (default: cortex-ignore)"
+		},
 		"debug": {
 			"label": "Debug Logging",
 			"help": "Enable verbose debug logs for API calls and responses",
@@ -61,6 +66,7 @@
 			"maxRecallResults": { "type": "number", "minimum": 1, "maximum": 50 },
 			"recallMode": { "type": "string", "enum": ["fast", "thinking"] },
 			"graphContext": { "type": "boolean" },
+			"ignoreTerm": { "type": "string" },
 			"debug": { "type": "boolean" }
 		},
 		"required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usecortex_ai/openclaw-cortex-ai",
-  "version": "0.1.0",
+  "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",

package/tools/search.ts

@@ -17,7 +17,7 @@ export function registerSearchTool(
 			name: "cortex_search",
 			label: "Cortex Search",
 			description:
-				"Search through Cortex long-term memories. Returns relevant chunks with graph-enriched context.",
+				"Search through Cortex AI memories. Returns relevant chunks with graph-enriched context.",
 			parameters: Type.Object({
 				query: Type.String({ description: "Search query" }),
 				limit: Type.Optional(

package/tools/store.ts

@@ -3,7 +3,7 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { CortexClient } from "../client.ts"
 import type { CortexPluginConfig } from "../config.ts"
 import { log } from "../log.ts"
-import { extractAllTurns } from "../messages.ts"
+import { extractAllTurns, filterIgnoredTurns } from "../messages.ts"
 import { toToolSourceId } from "../session.ts"
 import type { ConversationTurn } from "../types/cortex.ts"
 
@@ -16,7 +16,7 @@ function removeInjectedBlocks(text: string): string {
 export function registerStoreTool(
 	api: OpenClawPluginApi,
 	client: CortexClient,
-	_cfg: CortexPluginConfig,
+	cfg: CortexPluginConfig,
 	getSessionId: () => string | undefined,
 	getMessages: () => unknown[],
 ): void {
@@ -25,7 +25,7 @@ export function registerStoreTool(
 			name: "cortex_store",
 			label: "Cortex Store",
 			description:
-				"Save the full conversation history to Cortex long-term memory. Use this to persist facts, preferences, or decisions the user wants remembered. The complete chat history will be sent for context-rich storage.",
+				"Save the full conversation history to Cortex AI memory. Use this to persist facts, preferences, or decisions the user wants remembered. The complete chat history will be sent for context-rich storage.",
 			parameters: Type.Object({
 				text: Type.String({
 					description: "A brief summary or note about what is being saved",
@@ -46,14 +46,15 @@ export function registerStoreTool(
 
 				log.debug(`[store] tool called — sid=${sid ?? "none"} msgs=${messages.length} text="${params.text.slice(0, 50)}"`)
 
-				const allTurns = extractAllTurns(messages)
-				const recentTurns = allTurns.slice(-MAX_STORE_TURNS)
+				const rawTurns = extractAllTurns(messages)
+				const filteredTurns = filterIgnoredTurns(rawTurns, cfg.ignoreTerm)
+				const recentTurns = filteredTurns.slice(-MAX_STORE_TURNS)
 				const turns: ConversationTurn[] = recentTurns.map((t) => ({
 					user: removeInjectedBlocks(t.user),
 					assistant: removeInjectedBlocks(t.assistant),
 				}))
 
-				log.debug(`[store] extracted ${allTurns.length} total turns, using last ${turns.length} (MAX_STORE_TURNS=${MAX_STORE_TURNS})`)
+				log.debug(`[store] extracted ${rawTurns.length} total turns, ${rawTurns.length - filteredTurns.length} ignored, using last ${turns.length} (MAX_STORE_TURNS=${MAX_STORE_TURNS})`)
 
 				if (turns.length > 0 && sourceId) {
 					const now = new Date()