@usecortex_ai/openclaw-cortex-ai 0.0.1 → 0.1.1

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"
+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,6 +89,10 @@ 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,
 	}
 }

package/hooks/capture.ts

@@ -1,49 +1,11 @@
 import type { CortexClient } from "../client.ts"
 import type { CortexPluginConfig } from "../config.ts"
 import { log } from "../log.ts"
-import { toSourceId } from "../session.ts"
+import { extractAllTurns, filterIgnoredTurns } from "../messages.ts"
+import { toHookSourceId } from "../session.ts"
 import type { ConversationTurn } from "../types/cortex.ts"
 
-function textFromMessage(msg: Record<string, unknown>): string {
-	const content = msg.content
-	if (typeof content === "string") return content
-	if (Array.isArray(content)) {
-		return content
-			.filter(
-				(b) =>
-					b &&
-					typeof b === "object" &&
-					(b as Record<string, unknown>).type === "text",
-			)
-			.map((b) => (b as Record<string, unknown>).text as string)
-			.join("\n")
-	}
-	return ""
-}
-
-function getLatestTurn(messages: unknown[]): ConversationTurn | null {
-	let userIdx = -1
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const m = messages[i]
-		if (m && typeof m === "object" && (m as Record<string, unknown>).role === "user") {
-			userIdx = i
-			break
-		}
-	}
-	if (userIdx < 0) return null
-
-	const userText = textFromMessage(messages[userIdx] as Record<string, unknown>)
-	if (!userText) return null
-
-	for (let i = userIdx + 1; i < messages.length; i++) {
-		const m = messages[i]
-		if (m && typeof m === "object" && (m as Record<string, unknown>).role === "assistant") {
-			const aText = textFromMessage(m as Record<string, unknown>)
-			if (aText) return { user: userText, assistant: aText }
-		}
-	}
-	return null
-}
+const MAX_HOOK_TURNS = -1
 
 function removeInjectedBlocks(text: string): string {
 	return text.replace(/<cortex-context>[\s\S]*?<\/cortex-context>\s*/g, "").trim()
@@ -51,35 +13,89 @@ function removeInjectedBlocks(text: string): string {
 
 export function createIngestionHook(
 	client: CortexClient,
-	_cfg: CortexPluginConfig,
-	getSessionKey: () => string | undefined,
+	cfg: CortexPluginConfig,
 ) {
-	return async (event: Record<string, unknown>) => {
-		if (!event.success || !Array.isArray(event.messages) || event.messages.length === 0) return
+	return async (event: Record<string, unknown>, sessionId: string | undefined) => {
+		try {
+			log.debug(`[capture] hook fired — success=${event.success} msgs=${Array.isArray(event.messages) ? event.messages.length : "N/A"} sid=${sessionId ?? "none"}`)
 
-		const turn = getLatestTurn(event.messages)
-		if (!turn) return
+			if (!event.success) {
+				log.debug("[capture] skipped — event.success is falsy")
+				return
+			}
+			if (!Array.isArray(event.messages) || event.messages.length === 0) {
+				log.debug("[capture] skipped — no messages in event")
+				return
+			}
 
-		const userClean = removeInjectedBlocks(turn.user)
-		const assistantClean = removeInjectedBlocks(turn.assistant)
-		if (userClean.length < 5 || assistantClean.length < 5) return
+			if (!sessionId) {
+				log.debug("[capture] skipped — no session id available")
+				return
+			}
 
-		const sk = getSessionKey()
-		const sourceId = sk ? toSourceId(sk) : undefined
-		if (!sourceId) {
-			log.debug("ingestion skipped — no session key")
-			return
-		}
+			const rawTurns = extractAllTurns(event.messages)
+			const allTurns = filterIgnoredTurns(rawTurns, cfg.ignoreTerm)
 
-		log.debug(`ingesting turn (u=${userClean.length}c, a=${assistantClean.length}c) → ${sourceId}`)
+			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`)
+				const roles = event.messages
+					.slice(-5)
+					.map((m) => (m && typeof m === "object" ? (m as Record<string, unknown>).role : "?"))
+				log.debug(`[capture] last 5 message roles: ${JSON.stringify(roles)}`)
+				return
+			}
+
+			const recentTurns = MAX_HOOK_TURNS === -1 ? allTurns : allTurns.slice(-MAX_HOOK_TURNS) 
+			const turns: ConversationTurn[] = recentTurns.map((t) => ({
+				user: removeInjectedBlocks(t.user),
+				assistant: removeInjectedBlocks(t.assistant),
+			})).filter((t) => t.user.length >= 5 && t.assistant.length >= 5)
+
+			if (turns.length === 0) {
+				log.debug("[capture] skipped — all turns too short after cleaning")
+				return
+			}
+
+			const sourceId = toHookSourceId(sessionId)
+
+			const now = new Date()
+			const timestamp = now.toISOString()
+			const readableTime = now.toLocaleString("en-US", {
+				weekday: "short",
+				year: "numeric",
+				month: "short",
+				day: "numeric",
+				hour: "2-digit",
+				minute: "2-digit",
+				timeZoneName: "short",
+			})
+
+			const annotatedTurns = turns.map((t, i) => ({
+				user: i === 0 ? `[Temporal details: ${readableTime}]\n\n${t.user}` : t.user,
+				assistant: t.assistant,
+			}))
+
+			log.debug(`[capture] ingesting ${annotatedTurns.length} turns (of ${allTurns.length} total) @ ${timestamp} -> ${sourceId}`)
 
-		try {
 			await client.ingestConversation(
-				[{ user: userClean, assistant: assistantClean }],
+				annotatedTurns,
 				sourceId,
+				{
+					metadata: {
+						captured_at: timestamp,
+						source: "openclaw_hook",
+						turn_count: annotatedTurns.length,
+					},
+				},
 			)
+
+			log.debug("[capture] ingestion succeeded")
 		} catch (err) {
-			log.error("ingestion failed", err)
+			log.error("[capture] hook error", err)
 		}
 	}
 }

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,11 +1,15 @@
 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 { registerSlashCommands } from "./commands/slash.ts"
 import { cortexConfigSchema, parseConfig } from "./config.ts"
 import { createIngestionHook } from "./hooks/capture.ts"
 import { createRecallHook } from "./hooks/recall.ts"
 import { log } from "./log.ts"
+import { registerDeleteTool } from "./tools/delete.ts"
+import { registerGetTool } from "./tools/get.ts"
+import { registerListTool } from "./tools/list.ts"
 import { registerSearchTool } from "./tools/search.ts"
 import { registerStoreTool } from "./tools/store.ts"
 
@@ -13,40 +17,57 @@ 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)
 
-		log.setDebug(cfg.debug)
+		log.init(api.logger, cfg.debug)
 
 		const client = new CortexClient(cfg.apiKey, cfg.tenantId, cfg.subTenantId)
 
-		let activeSessionKey: string | undefined
-		const getSessionKey = () => activeSessionKey
+		let activeSessionId: string | undefined
+		let conversationMessages: unknown[] = []
+		const getSessionId = () => activeSessionId
+		const getMessages = () => conversationMessages
 
 		registerSearchTool(api, client, cfg)
-		registerStoreTool(api, client, cfg, getSessionKey)
+		registerStoreTool(api, client, cfg, getSessionId, getMessages)
+		registerListTool(api, client, cfg)
+		registerDeleteTool(api, client, cfg)
+		registerGetTool(api, client, cfg)
 
 		if (cfg.autoRecall) {
 			const onRecall = createRecallHook(client, cfg)
 			api.on(
 				"before_agent_start",
 				(event: Record<string, unknown>, ctx: Record<string, unknown>) => {
-					if (ctx.sessionKey) activeSessionKey = ctx.sessionKey as string
+					if (ctx.sessionId) activeSessionId = ctx.sessionId as string
+					if (Array.isArray(event.messages)) conversationMessages = event.messages
+					log.debug(`[session] before_agent_start — sid=${activeSessionId ?? "none"} msgs=${conversationMessages.length}`)
 					return onRecall(event)
 				},
 			)
 		}
 
 		if (cfg.autoCapture) {
-			api.on("agent_end", createIngestionHook(client, cfg, getSessionKey))
+			const captureHandler = createIngestionHook(client, cfg)
+			api.on(
+				"agent_end",
+				(event: Record<string, unknown>, ctx: Record<string, unknown>) => {
+					if (ctx.sessionId) activeSessionId = ctx.sessionId as string
+					if (Array.isArray(event.messages)) conversationMessages = event.messages
+					log.debug(`[session] agent_end — sid=${activeSessionId ?? "none"} msgs=${conversationMessages.length} ctxKeys=${Object.keys(ctx).join(",")}`)
+					return captureHandler(event, activeSessionId)
+				},
+			)
 		}
 
-		registerSlashCommands(api, client, cfg, getSessionKey)
-		registerCliCommands(api, client, cfg)
+		registerSlashCommands(api, client, cfg, getSessionId)
+		registerOnboardingSlashCommands(api, client, cfg)
+		registerCliCommands(api, client, cfg, registerOnboardingCli(cfg))
 
 		api.registerService({
 			id: "openclaw-cortex-ai",

package/log.ts

@@ -1,25 +1,48 @@
+export type LoggerBackend = {
+	info(msg: string): void
+	warn(msg: string): void
+	error(msg: string): void
+	debug?(msg: string): void
+}
+
 const TAG = "[cortex-ai]"
 
+let _backend: LoggerBackend | null = null
 let _debug = false
 
 export const log = {
+	init(backend: LoggerBackend, debug: boolean) {
+		_backend = backend
+		_debug = debug
+	},
+
 	setDebug(enabled: boolean) {
 		_debug = enabled
 	},
 
 	info(...args: unknown[]) {
-		console.log(TAG, ...args)
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend) _backend.info(msg)
+		else console.log(msg)
 	},
 
 	warn(...args: unknown[]) {
-		console.warn(TAG, ...args)
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend) _backend.warn(msg)
+		else console.warn(msg)
 	},
 
 	error(...args: unknown[]) {
-		console.error(TAG, ...args)
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend) _backend.error(msg)
+		else console.error(msg)
 	},
 
 	debug(...args: unknown[]) {
-		if (_debug) console.debug(TAG, ...args)
+		if (!_debug) return
+		const msg = `${TAG} ${args.map(String).join(" ")}`
+		if (_backend?.debug) _backend.debug(msg)
+		else if (_backend) _backend.info(msg)
+		else console.debug(msg)
 	},
 }

package/messages.ts

@@ -0,0 +1,88 @@
+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
+	if (Array.isArray(content)) {
+		return content
+			.filter(
+				(b) =>
+					b &&
+					typeof b === "object" &&
+					(b as Record<string, unknown>).type === "text",
+			)
+			.map((b) => (b as Record<string, unknown>).text as string)
+			.filter(Boolean)
+			.join("\n")
+	}
+	return ""
+}
+
+export function extractAllTurns(messages: unknown[]): ConversationTurn[] {
+	const turns: ConversationTurn[] = []
+	let currentUserText: string | null = null
+	let currentAssistantText: string | null = null
+
+	for (const msg of messages) {
+		if (!msg || typeof msg !== "object") continue
+		const m = msg as Record<string, unknown>
+		const text = textFromMessage(m)
+
+		if (m.role === "user") {
+			if (!text) continue
+			if (currentUserText && currentAssistantText) {
+				turns.push({ user: currentUserText, assistant: currentAssistantText })
+			}
+			currentUserText = text
+			currentAssistantText = "no-message"
+		} else if (m.role === "assistant") {
+			if (!text) continue
+			currentAssistantText = text
+		}
+	}
+
+	if (currentUserText && currentAssistantText) {
+		turns.push({ user: currentUserText, assistant: currentAssistantText })
+	}
+
+	return turns
+}
+
+export function getLatestTurn(messages: unknown[]): ConversationTurn | null {
+	let userIdx = -1
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i]
+		if (m && typeof m === "object" && (m as Record<string, unknown>).role === "user") {
+			userIdx = i
+			break
+		}
+	}
+	if (userIdx < 0) return null
+
+	const userText = textFromMessage(messages[userIdx] as Record<string, unknown>)
+	if (!userText) return null
+
+	for (let i = userIdx + 1; i < messages.length; i++) {
+		const m = messages[i]
+		if (m && typeof m === "object" && (m as Record<string, unknown>).role === "assistant") {
+			const aText = textFromMessage(m as Record<string, unknown>)
+			if (aText) return { user: userText, assistant: aText }
+		}
+	}
+	return null
+}

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.0.1",
+  "version": "0.1.1",
   "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/session.ts

@@ -1,3 +1,11 @@
-export function toSourceId(sessionKey: string): string {
-	return `openclaw_cortex_sess_${sessionKey.replace(/\W+/g, "_")}`
+export function toSourceId(sessionId: string): string {
+	return `sess_${sessionId}`
+}
+
+export function toHookSourceId(sessionId: string): string {
+	return `hook_${sessionId}`
+}
+
+export function toToolSourceId(sessionId: string): string {
+	return `tool_${sessionId}`
 }

package/tools/delete.ts

@@ -0,0 +1,54 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { CortexClient } from "../client.ts"
+import type { CortexPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+
+export function registerDeleteTool(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	_cfg: CortexPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "cortex_delete_memory",
+			label: "Cortex Delete Memory",
+			description:
+				"Delete a specific memory from Cortex by its memory ID. Use this when the user explicitly asks you to forget something or remove a specific piece of stored information. Always confirm the memory ID before deleting.",
+			parameters: Type.Object({
+				memory_id: Type.String({
+					description: "The unique ID of the memory to delete",
+				}),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { memory_id: string },
+			) {
+				log.debug(`delete tool: memory_id=${params.memory_id}`)
+
+				const res = await client.deleteMemory(params.memory_id)
+
+				if (res.user_memory_deleted) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Successfully deleted memory: ${params.memory_id}`,
+							},
+						],
+					}
+				}
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Memory ${params.memory_id} was not found or has already been deleted.`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "cortex_delete_memory" },
+	)
+}

package/tools/get.ts

@@ -0,0 +1,57 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { CortexClient } from "../client.ts"
+import type { CortexPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+
+export function registerGetTool(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	_cfg: CortexPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "cortex_get_content",
+			label: "Cortex Get Content",
+			description:
+				"Fetch the full content of a specific source from Cortex by its source ID. Use this to retrieve the complete text of a memory source when you need more details than what's shown in search results.",
+			parameters: Type.Object({
+				source_id: Type.String({
+					description: "The unique source ID to fetch content for",
+				}),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { source_id: string },
+			) {
+				log.debug(`get tool: source_id=${params.source_id}`)
+
+				const res = await client.fetchContent(params.source_id)
+
+				if (!res.success || res.error) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Failed to fetch source ${params.source_id}: ${res.error ?? "unknown error"}`,
+							},
+						],
+					}
+				}
+
+				const content = res.content ?? res.content_base64 ?? "(no text content available)"
+				const preview = content.length > 3000 ? `${content.slice(0, 3000)}…\n\n[Content truncated, showing first 3000 characters]` : content
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Source: ${params.source_id}\n\n${preview}`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "cortex_get_content" },
+	)
+}

package/tools/list.ts

@@ -0,0 +1,56 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { CortexClient } from "../client.ts"
+import type { CortexPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+
+export function registerListTool(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	_cfg: CortexPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "cortex_list_memories",
+			label: "Cortex List Memories",
+			description:
+				"List all user memories stored in Cortex. Returns memory IDs and content summaries. Use this when the user asks what you remember about them or wants to see their stored information.",
+			parameters: Type.Object({}),
+			async execute(_toolCallId: string, _params: Record<string, never>) {
+				log.debug("list tool: fetching all memories")
+
+				const res = await client.listMemories()
+				const memories = res.user_memories ?? []
+
+				if (memories.length === 0) {
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: "No memories stored yet.",
+							},
+						],
+					}
+				}
+
+				const lines = memories.map((m, i) => {
+					const preview =
+						m.memory_content.length > 100
+							? `${m.memory_content.slice(0, 100)}…`
+							: m.memory_content
+					return `${i + 1}. [ID: ${m.memory_id}]\n   ${preview}`
+				})
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Found ${memories.length} memories:\n\n${lines.join("\n\n")}`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "cortex_list_memories" },
+	)
+}

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(