@usecortex_ai/openclaw-cortex-ai 0.0.1

package/context.ts

@@ -0,0 +1,191 @@
+import type {
+	PathTriplet,
+	RecallResponse,
+	ScoredPath,
+	VectorChunk,
+} from "./types/cortex.ts"
+
+function formatTriplet(triplet: PathTriplet): string {
+	const src = triplet.source?.name ?? "?"
+	const rel = triplet.relation
+	const predicate =
+		rel?.raw_predicate ?? rel?.canonical_predicate ?? "related to"
+	const tgt = triplet.target?.name ?? "?"
+	const ctx = rel?.context ? ` [${rel.context}]` : ""
+	return `  (${src}) —[${predicate}]→ (${tgt})${ctx}`
+}
+
+export function buildRecalledContext(
+	response: RecallResponse,
+	opts?: {
+		maxGroupOccurrences?: number
+		minEvidenceScore?: number
+	},
+): string {
+	const minScore = opts?.minEvidenceScore ?? 0.4
+
+	const chunks = response.chunks ?? []
+	const graphCtx = response.graph_context ?? {
+		query_paths: [],
+		chunk_relations: [],
+		chunk_id_to_group_ids: {},
+	}
+	const extraContextMap = response.additional_context ?? {}
+
+	const rawRelations: ScoredPath[] = graphCtx.chunk_relations ?? []
+	const relationIndex: Record<string, ScoredPath> = {}
+
+	for (let idx = 0; idx < rawRelations.length; idx++) {
+		const relation = rawRelations[idx]!
+		if ((relation.relevancy_score ?? 0) < minScore) continue
+		const groupId = relation.group_id ?? `p_${idx}`
+		relationIndex[groupId] = relation
+	}
+
+	const chunkToGroupIds = graphCtx.chunk_id_to_group_ids ?? {}
+	const consumedExtraIds = new Set<string>()
+	const chunkSections: string[] = []
+
+	for (let i = 0; i < chunks.length; i++) {
+		const chunk = chunks[i]!
+		const lines: string[] = []
+
+		lines.push(`Chunk ${i + 1}`)
+
+		const meta = chunk.document_metadata ?? {}
+		const title =
+			chunk.source_title || (meta as Record<string, string>).title
+		if (title) {
+			lines.push(`Source: ${title}`)
+		}
+
+		lines.push(chunk.chunk_content ?? "")
+
+		const chunkUuid = chunk.chunk_uuid
+		const linkedGroupIds = chunkToGroupIds[chunkUuid] ?? []
+
+		const matchedRelations: ScoredPath[] = []
+
+		for (const gid of linkedGroupIds) {
+			if (relationIndex[gid]) {
+				matchedRelations.push(relationIndex[gid]!)
+			}
+		}
+
+		if (matchedRelations.length === 0) {
+			for (const rel of Object.values(relationIndex)) {
+				const triplets = rel.triplets ?? []
+				const hasChunk = triplets.some(
+					(t) => t.relation?.chunk_id === chunkUuid,
+				)
+				if (hasChunk) {
+					matchedRelations.push(rel)
+				}
+			}
+		}
+
+		const relationLines: string[] = []
+		for (const rel of matchedRelations) {
+			const triplets = rel.triplets ?? []
+			if (triplets.length > 0) {
+				for (const triplet of triplets) {
+					relationLines.push(formatTriplet(triplet))
+				}
+			} else if (rel.combined_context) {
+				relationLines.push(`  ${rel.combined_context}`)
+			}
+		}
+
+		if (relationLines.length > 0) {
+			lines.push("Graph Relations:")
+			lines.push(...relationLines)
+		}
+
+		const extraIds = chunk.extra_context_ids ?? []
+		if (extraIds.length > 0 && Object.keys(extraContextMap).length > 0) {
+			const extraLines: string[] = []
+			for (const ctxId of extraIds) {
+				if (consumedExtraIds.has(ctxId)) continue
+				const extraChunk = extraContextMap[ctxId]
+				if (extraChunk) {
+					consumedExtraIds.add(ctxId)
+					const extraContent = extraChunk.chunk_content ?? ""
+					const extraTitle = extraChunk.source_title ?? ""
+					if (extraTitle) {
+						extraLines.push(
+							`  Related Context (${extraTitle}): ${extraContent}`,
+						)
+					} else {
+						extraLines.push(`  Related Context: ${extraContent}`)
+					}
+				}
+			}
+			if (extraLines.length > 0) {
+				lines.push("Extra Context:")
+				lines.push(...extraLines)
+			}
+		}
+
+		chunkSections.push(lines.join("\n"))
+	}
+
+	const entityPathLines: string[] = []
+	const rawPaths: ScoredPath[] = graphCtx.query_paths ?? []
+	for (const path of rawPaths) {
+		if (path.combined_context) {
+			entityPathLines.push(path.combined_context)
+		} else {
+			const triplets = path.triplets ?? []
+			const segments: string[] = []
+			for (const pt of triplets) {
+				const s = pt.source?.name
+				const rel = pt.relation
+				const p =
+					rel?.raw_predicate ??
+					rel?.canonical_predicate ??
+					"related to"
+				const t = pt.target?.name
+				segments.push(`(${s} -> ${p} -> ${t})`)
+			}
+			if (segments.length > 0) {
+				entityPathLines.push(segments.join(" -> "))
+			}
+		}
+	}
+
+	const output: string[] = []
+
+	if (entityPathLines.length > 0) {
+		output.push("=== ENTITY PATHS ===")
+		output.push(entityPathLines.join("\n"))
+		output.push("")
+	}
+
+	if (chunkSections.length > 0) {
+		output.push("=== CONTEXT ===")
+		output.push(chunkSections.join("\n\n---\n\n"))
+	}
+
+	return output.join("\n")
+}
+
+export function envelopeForInjection(contextBody: string): string {
+	if (!contextBody.trim()) return ""
+
+	const lines = [
+		"<cortex-context>",
+		"[MEMORIES AND PAST CONVERSATIONS — retrieved by Cortex AI]",
+		"",
+		"Below are memories and knowledge-graph connections that may be relevant",
+		"to the current conversation. Integrate them naturally when they add value.",
+		"If a memory contradicts something the user just said, prefer the user's",
+		"latest statement. Never quote these verbatim or reveal that you are",
+		"reading from a memory store.",
+		"",
+		contextBody,
+		"",
+		"[END OF MEMORY CONTEXT]",
+		"</cortex-context>",
+	]
+	return lines.join("\n")
+}

package/hooks/capture.ts

@@ -0,0 +1,85 @@
+import type { CortexClient } from "../client.ts"
+import type { CortexPluginConfig } from "../config.ts"
+import { log } from "../log.ts"
+import { toSourceId } 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
+}
+
+function removeInjectedBlocks(text: string): string {
+	return text.replace(/<cortex-context>[\s\S]*?<\/cortex-context>\s*/g, "").trim()
+}
+
+export function createIngestionHook(
+	client: CortexClient,
+	_cfg: CortexPluginConfig,
+	getSessionKey: () => string | undefined,
+) {
+	return async (event: Record<string, unknown>) => {
+		if (!event.success || !Array.isArray(event.messages) || event.messages.length === 0) return
+
+		const turn = getLatestTurn(event.messages)
+		if (!turn) return
+
+		const userClean = removeInjectedBlocks(turn.user)
+		const assistantClean = removeInjectedBlocks(turn.assistant)
+		if (userClean.length < 5 || assistantClean.length < 5) return
+
+		const sk = getSessionKey()
+		const sourceId = sk ? toSourceId(sk) : undefined
+		if (!sourceId) {
+			log.debug("ingestion skipped — no session key")
+			return
+		}
+
+		log.debug(`ingesting turn (u=${userClean.length}c, a=${assistantClean.length}c) → ${sourceId}`)
+
+		try {
+			await client.ingestConversation(
+				[{ user: userClean, assistant: assistantClean }],
+				sourceId,
+			)
+		} catch (err) {
+			log.error("ingestion failed", err)
+		}
+	}
+}

package/hooks/recall.ts

@@ -0,0 +1,40 @@
+import type { CortexClient } from "../client.ts"
+import type { CortexPluginConfig } from "../config.ts"
+import { buildRecalledContext, envelopeForInjection } from "../context.ts"
+import { log } from "../log.ts"
+
+export function createRecallHook(
+	client: CortexClient,
+	cfg: CortexPluginConfig,
+) {
+	return async (event: Record<string, unknown>) => {
+		const prompt = event.prompt as string | undefined
+		if (!prompt || prompt.length < 5) return
+
+		log.debug(`recall query (${prompt.length} chars)`)
+
+		try {
+			const response = await client.recall(prompt, {
+				maxResults: cfg.maxRecallResults,
+				mode: cfg.recallMode,
+				graphContext: cfg.graphContext,
+			})
+
+			if (!response.chunks || response.chunks.length === 0) {
+				log.debug("no memories matched")
+				return
+			}
+
+			const body = buildRecalledContext(response)
+			if (!body.trim()) return
+
+			const envelope = envelopeForInjection(body)
+
+			log.debug(`injecting ${response.chunks.length} chunks (${envelope.length} chars)`)
+			return { prependContext: envelope }
+		} catch (err) {
+			log.error("recall failed", err)
+			return
+		}
+	}
+}

package/index.ts

@@ -0,0 +1,57 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { CortexClient } from "./client.ts"
+import { registerCliCommands } from "./commands/cli.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 { registerSearchTool } from "./tools/search.ts"
+import { registerStoreTool } from "./tools/store.ts"
+
+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",
+	kind: "memory" as const,
+	configSchema: cortexConfigSchema,
+
+	register(api: OpenClawPluginApi) {
+		const cfg = parseConfig(api.pluginConfig)
+
+		log.setDebug(cfg.debug)
+
+		const client = new CortexClient(cfg.apiKey, cfg.tenantId, cfg.subTenantId)
+
+		let activeSessionKey: string | undefined
+		const getSessionKey = () => activeSessionKey
+
+		registerSearchTool(api, client, cfg)
+		registerStoreTool(api, client, cfg, getSessionKey)
+
+		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
+					return onRecall(event)
+				},
+			)
+		}
+
+		if (cfg.autoCapture) {
+			api.on("agent_end", createIngestionHook(client, cfg, getSessionKey))
+		}
+
+		registerSlashCommands(api, client, cfg, getSessionKey)
+		registerCliCommands(api, client, cfg)
+
+		api.registerService({
+			id: "openclaw-cortex-ai",
+			start: () => log.info("plugin started"),
+			stop: () => log.info("plugin stopped"),
+		})
+	},
+}

package/log.ts

@@ -0,0 +1,25 @@
+const TAG = "[cortex-ai]"
+
+let _debug = false
+
+export const log = {
+	setDebug(enabled: boolean) {
+		_debug = enabled
+	},
+
+	info(...args: unknown[]) {
+		console.log(TAG, ...args)
+	},
+
+	warn(...args: unknown[]) {
+		console.warn(TAG, ...args)
+	},
+
+	error(...args: unknown[]) {
+		console.error(TAG, ...args)
+	},
+
+	debug(...args: unknown[]) {
+		if (_debug) console.debug(TAG, ...args)
+	},
+}

package/openclaw.plugin.json

@@ -0,0 +1,68 @@
+{
+	"id": "openclaw-cortex-ai",
+	"kind": "memory",
+	"uiHints": {
+		"apiKey": {
+			"label": "Cortex API Key",
+			"sensitive": true,
+			"placeholder": "your-cortex-api-key",
+			"help": "Your API key from Cortex (or use ${CORTEX_OPENCLAW_API_KEY})"
+		},
+		"tenantId": {
+			"label": "Tenant ID",
+			"placeholder": "tenant-01",
+			"help": "Your Cortex tenant identifier (or use ${CORTEX_OPENCLAW_TENANT_ID})"
+		},
+		"subTenantId": {
+			"label": "Sub-Tenant ID",
+			"placeholder": "cortex-openclaw",
+			"help": "Sub-tenant for data partitioning (default: cortex-openclaw)",
+			"advanced": true
+		},
+		"autoRecall": {
+			"label": "Auto-Recall",
+			"help": "Inject relevant memories before every AI turn (default: true)"
+		},
+		"autoCapture": {
+			"label": "Auto-Capture",
+			"help": "Automatically store conversation exchanges after every AI turn (default: true)"
+		},
+		"maxRecallResults": {
+			"label": "Max Recall Results",
+			"placeholder": "10",
+			"help": "Maximum memory chunks injected into context per turn",
+			"advanced": true
+		},
+		"recallMode": {
+			"label": "Recall Mode",
+			"help": "'fast' (default) or 'thinking' (personalised recall with deeper graph traversal)",
+			"advanced": true
+		},
+		"graphContext": {
+			"label": "Graph Context",
+			"help": "Include knowledge graph relations in recalled context (default: true)",
+			"advanced": true
+		},
+		"debug": {
+			"label": "Debug Logging",
+			"help": "Enable verbose debug logs for API calls and responses",
+			"advanced": true
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"apiKey": { "type": "string" },
+			"tenantId": { "type": "string" },
+			"subTenantId": { "type": "string" },
+			"autoRecall": { "type": "boolean" },
+			"autoCapture": { "type": "boolean" },
+			"maxRecallResults": { "type": "number", "minimum": 1, "maximum": 50 },
+			"recallMode": { "type": "string", "enum": ["fast", "thinking"] },
+			"graphContext": { "type": "boolean" },
+			"debug": { "type": "boolean" }
+		},
+		"required": []
+	}
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@usecortex_ai/openclaw-cortex-ai",
+  "version": "0.0.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",
+  "dependencies": {
+    "@sinclair/typebox": "0.34.47"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.1.29"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/session.ts

@@ -0,0 +1,3 @@
+export function toSourceId(sessionKey: string): string {
+	return `openclaw_cortex_sess_${sessionKey.replace(/\W+/g, "_")}`
+}

package/tools/search.ts

@@ -0,0 +1,64 @@
+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 { buildRecalledContext } from "../context.ts"
+import { log } from "../log.ts"
+import type { VectorChunk } from "../types/cortex.ts"
+
+
+export function registerSearchTool(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	cfg: CortexPluginConfig,
+): void {
+	api.registerTool(
+		{
+			name: "cortex_search",
+			label: "Cortex Search",
+			description:
+				"Search through Cortex long-term memories. Returns relevant chunks with graph-enriched context.",
+			parameters: Type.Object({
+				query: Type.String({ description: "Search query" }),
+				limit: Type.Optional(
+					Type.Number({ description: "Max results (default: 10)" }),
+				),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { query: string; limit?: number },
+			) {
+				const limit = params.limit ?? cfg.maxRecallResults
+				log.debug(`search tool: "${params.query}" limit=${limit}`)
+
+				const res = await client.recall(params.query, {
+					maxResults: limit,
+					mode: cfg.recallMode,
+					graphContext: cfg.graphContext,
+				})
+
+				if (!res.chunks || res.chunks.length === 0) {
+					return {
+						content: [{ type: "text" as const, text: "No relevant memories found." }],
+					}
+				}
+
+				const contextStr = buildRecalledContext(res)
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Found ${res.chunks.length} \n\n---\nFull context:\n${contextStr}`,
+						},
+					],
+					details: {
+						count: res.chunks.length,
+						hasGraphContext: !!res.graph_context,
+					},
+				}
+			},
+		},
+		{ name: "cortex_search" },
+	)
+}

package/tools/store.ts

@@ -0,0 +1,62 @@
+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"
+import { toSourceId } from "../session.ts"
+
+export function registerStoreTool(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	_cfg: CortexPluginConfig,
+	getSessionKey: () => string | undefined,
+): void {
+	api.registerTool(
+		{
+			name: "cortex_store",
+			label: "Cortex Store",
+			description:
+				"Save important information to Cortex long-term memory. Use this to persist facts, preferences, or decisions the user wants remembered.",
+			parameters: Type.Object({
+				text: Type.String({
+					description: "The information to store in memory",
+				}),
+				title: Type.Optional(
+					Type.String({
+						description: "Optional title for the memory entry",
+					}),
+				),
+			}),
+			async execute(
+				_toolCallId: string,
+				params: { text: string; title?: string },
+			) {
+				const sk = getSessionKey()
+				const sourceId = sk ? toSourceId(sk) : undefined
+
+				log.debug(`store tool: "${params.text.slice(0, 50)}" - \nsourceId: ${sourceId}`)
+
+				await client.ingestText(params.text, {
+					sourceId,
+					title: params.title ?? "Agent Memory",
+					infer: true,
+				})
+
+				const preview =
+					params.text.length > 80
+						? `${params.text.slice(0, 80)}…`
+						: params.text
+
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: `Saved to Cortex: "${preview}"`,
+						},
+					],
+				}
+			},
+		},
+		{ name: "cortex_store" },
+	)
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": [
+    "*.ts",
+    "tools/*.ts",
+    "hooks/*.ts",
+    "commands/*.ts",
+    "types/*.ts"
+  ],
+  "exclude": ["node_modules", "dist", "ignore"]
+}