@usecortex_ai/openclaw-cortex-ai 0.0.1

package/README.md

@@ -0,0 +1,90 @@
+# Cortex AI — OpenClaw Plugin
+
+Long-term memory for OpenClaw powered by [Cortex AI](https://usecortex.ai). Automatically captures conversations, recalls relevant context with knowledge-graph connections, and injects them before every AI turn.
+
+## Install
+
+```bash
+openclaw plugins install @usecortex_ai/openclaw-cortex-ai
+```
+
+Restart OpenClaw after installing.
+
+## Configuration
+
+Two required values: your Cortex API key and tenant ID.
+
+```bash
+export CORTEX_OPENCLAW_API_KEY="your-api-key"
+export CORTEX_OPENCLAW_TENANT_ID="your-tenant-id"
+```
+
+Or configure directly in `openclaw.json`:
+
+```json5
+{
+  "plugins": {
+    "entries": {
+      "openclaw-cortex-ai": {
+        "enabled": true,
+        "config": {
+          "apiKey": "${CORTEX_OPENCLAW_API_KEY}",
+          "tenantId": "${CORTEX_OPENCLAW_TENANT_ID}"
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Key                | Type      | Default            | Description                                                                |
+| ------------------ | --------- | ------------------ | -------------------------------------------------------------------------- |
+| `subTenantId`      | `string`  | `"cortex-openclaw"`| Sub-tenant for data partitioning within your tenant                        |
+| `autoRecall`       | `boolean` | `true`             | Inject relevant memories before every AI turn                              |
+| `autoCapture`      | `boolean` | `true`             | Store conversation exchanges after every AI turn                           |
+| `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                      |
+| `debug`            | `boolean` | `false`            | Verbose debug logs                                                         |
+
+## How It Works
+
+- **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.
+
+## Slash Commands
+
+| Command                    | Description                                       |
+| -------------------------- | ------------------------------------------------- |
+| `/cortex-remember <text>`  | Save something to Cortex memory                   |
+| `/cortex-recall <query>`   | Search memories with relevance scores              |
+| `/cortex-list`             | List all stored user memories                      |
+| `/cortex-delete <id>`      | Delete a specific memory by its ID                 |
+| `/cortex-get <source_id>`  | Fetch the full content of a source                 |
+
+## AI Tools
+
+| Tool             | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `cortex_store`   | Save information to long-term memory                      |
+| `cortex_search`  | Search memories with graph-enriched results               |
+
+## CLI
+
+```bash
+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
+
+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

package/client.ts

@@ -0,0 +1,206 @@
+import { log } from "./log.ts"
+import type {
+	AddMemoryRequest,
+	AddMemoryResponse,
+	ConversationTurn,
+	DeleteMemoryResponse,
+	FetchContentRequest,
+	FetchContentResponse,
+	ListDataRequest,
+	ListMemoriesResponse,
+	ListSourcesResponse,
+	RecallRequest,
+	RecallResponse,
+} from "./types/cortex.ts"
+
+const API_BASE = "https://api.usecortex.ai"
+
+const INGEST_INSTRUCTIONS =
+	"Focus on extracting user preferences, habits, opinions, likes, dislikes, " +
+	"goals, and recurring themes. Capture any stated or implied personal context " +
+	"that would help personalise future interactions."
+
+export class CortexClient {
+	private apiKey: string
+	private tenantId: string
+	private subTenantId: string
+
+	constructor(apiKey: string, tenantId: string, subTenantId: string) {
+		this.apiKey = apiKey
+		this.tenantId = tenantId
+		this.subTenantId = subTenantId
+		log.info(`connected (tenant=${tenantId}, sub=${subTenantId})`)
+	}
+
+	private headers(): Record<string, string> {
+		return {
+			Authorization: `Bearer ${this.apiKey}`,
+			"Content-Type": "application/json",
+		}
+	}
+
+	private async post<T>(path: string, body: unknown): Promise<T> {
+		const url = `${API_BASE}${path}`
+		log.debug("POST", path, body)
+		const res = await fetch(url, {
+			method: "POST",
+			headers: this.headers(),
+			body: JSON.stringify(body),
+		})
+		if (!res.ok) {
+			const text = await res.text().catch(() => "")
+			throw new Error(`Cortex ${path} → ${res.status}: ${text}`)
+		}
+		return res.json() as Promise<T>
+	}
+
+	private async del<T>(path: string, params: Record<string, string>): Promise<T> {
+		const qs = new URLSearchParams(params).toString()
+		const url = `${API_BASE}${path}?${qs}`
+		log.debug("DELETE", path, params)
+		const res = await fetch(url, {
+			method: "DELETE",
+			headers: this.headers(),
+		})
+		if (!res.ok) {
+			const text = await res.text().catch(() => "")
+			throw new Error(`Cortex ${path} → ${res.status}: ${text}`)
+		}
+		return res.json() as Promise<T>
+	}
+
+	// --- Ingest ---
+
+	async ingestConversation(
+		turns: ConversationTurn[],
+		sourceId: string,
+		userName?: string,
+	): Promise<AddMemoryResponse> {
+		const payload: AddMemoryRequest = {
+			memories: [
+				{
+					user_assistant_pairs: turns,
+					infer: true,
+					source_id: sourceId,
+					user_name: userName ?? "User",
+					custom_instructions: INGEST_INSTRUCTIONS,
+				},
+			],
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			upsert: true,
+		}
+		return this.post<AddMemoryResponse>("/memories/add_memory", payload)
+	}
+
+	async ingestText(
+		text: string,
+		opts?: {
+			sourceId?: string
+			title?: string
+			infer?: boolean
+			isMarkdown?: boolean
+			customInstructions?: string
+		},
+	): Promise<AddMemoryResponse> {
+		const shouldInfer = opts?.infer ?? true
+		const payload: AddMemoryRequest = {
+			memories: [
+				{
+					text,
+					infer: shouldInfer,
+					is_markdown: opts?.isMarkdown ?? false,
+					...(shouldInfer && {
+						custom_instructions: opts?.customInstructions ?? INGEST_INSTRUCTIONS,
+					}),
+					...(opts?.sourceId && { source_id: opts.sourceId }),
+					...(opts?.title && { title: opts.title }),
+				},
+			],
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			upsert: true,
+		}
+		return this.post<AddMemoryResponse>("/memories/add_memory", payload)
+	}
+
+	// --- Recall ---
+
+	async recall(
+		query: string,
+		opts?: {
+			maxResults?: number
+			mode?: "fast" | "thinking"
+			graphContext?: boolean
+			recencyBias?: number
+		},
+	): Promise<RecallResponse> {
+		const payload: RecallRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			query,
+			max_results: opts?.maxResults ?? 10,
+			mode: opts?.mode ?? "thinking",
+			alpha: 0.8,
+			recency_bias: opts?.recencyBias ?? 0,
+			graph_context: opts?.graphContext ?? true,
+		}
+		return this.post<RecallResponse>("/recall/recall_preferences", payload)
+	}
+
+	// --- List ---
+
+	async listMemories(): Promise<ListMemoriesResponse> {
+		const payload: ListDataRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			kind: "memories",
+		}
+		return this.post<ListMemoriesResponse>("/list/data", payload)
+	}
+
+	async listSources(sourceIds?: string[]): Promise<ListSourcesResponse> {
+		const payload: ListDataRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			kind: "memories",
+			...(sourceIds && { source_ids: sourceIds }),
+		}
+		return this.post<ListSourcesResponse>("/list/data", payload)
+	}
+
+	// --- Delete ---
+
+	async deleteMemory(memoryId: string): Promise<DeleteMemoryResponse> {
+		return this.del<DeleteMemoryResponse>("/memories/delete_memory", {
+			tenant_id: this.tenantId,
+			memory_id: memoryId,
+			sub_tenant_id: this.subTenantId,
+		})
+	}
+
+	// --- Fetch Content ---
+
+	async fetchContent(
+		sourceId: string,
+		mode: "content" | "url" | "both" = "content",
+	): Promise<FetchContentResponse> {
+		const payload: FetchContentRequest = {
+			tenant_id: this.tenantId,
+			sub_tenant_id: this.subTenantId,
+			source_id: sourceId,
+			mode,
+		}
+		return this.post<FetchContentResponse>("/fetch/content", payload)
+	}
+
+	// --- Accessors ---
+
+	getTenantId(): string {
+		return this.tenantId
+	}
+
+	getSubTenantId(): string {
+		return this.subTenantId
+	}
+}

package/commands/cli.ts

@@ -0,0 +1,93 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { CortexClient } from "../client.ts"
+import type { CortexPluginConfig } from "../config.ts"
+
+export function registerCliCommands(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	cfg: CortexPluginConfig,
+): void {
+	api.registerCli(
+		({ program }: { program: any }) => {
+			const root = program
+				.command("cortex")
+				.description("Cortex AI memory commands")
+
+			root
+				.command("search")
+				.argument("<query>", "Search query")
+				.option("--limit <n>", "Max results", "10")
+				.action(async (query: string, opts: { limit: string }) => {
+					const limit = Number.parseInt(opts.limit, 10) || 10
+					const res = await client.recall(query, {
+						maxResults: limit,
+						mode: cfg.recallMode,
+						graphContext: 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 res = await 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 res = await 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 res = await 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(() => {
+					console.log(`Tenant:       ${client.getTenantId()}`)
+					console.log(`Sub-Tenant:   ${client.getSubTenantId()}`)
+					console.log(`Auto-Recall:  ${cfg.autoRecall}`)
+					console.log(`Auto-Capture: ${cfg.autoCapture}`)
+					console.log(`Recall Mode:  ${cfg.recallMode}`)
+					console.log(`Graph:        ${cfg.graphContext}`)
+					console.log(`Max Results:  ${cfg.maxRecallResults}`)
+				})
+		},
+		{ commands: ["cortex"] },
+	)
+}

package/commands/slash.ts

@@ -0,0 +1,138 @@
+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"
+
+function preview(text: string, max = 80): string {
+	return text.length > max ? `${text.slice(0, max)}…` : text
+}
+
+export function registerSlashCommands(
+	api: OpenClawPluginApi,
+	client: CortexClient,
+	cfg: CortexPluginConfig,
+	getSessionKey: () => string | undefined,
+): void {
+	api.registerCommand({
+		name: "cortex-remember",
+		description: "Save a piece of information to Cortex memory",
+		acceptsArgs: true,
+		requireAuth: true,
+		handler: async (ctx: { args?: string }) => {
+			const text = ctx.args?.trim()
+			if (!text) return { text: "Usage: /cortex-remember <text to store>" }
+
+			try {
+				const sk = getSessionKey()
+				const sourceId = sk ? toSourceId(sk) : undefined
+				await client.ingestText(text, { sourceId, title: "Manual Memory", infer: true })
+				return { text: `Saved: "${preview(text, 60)}"` }
+			} catch (err) {
+				log.error("/cortex-remember", err)
+				return { text: "Failed to save. Check logs." }
+			}
+		},
+	})
+
+	api.registerCommand({
+		name: "cortex-recall",
+		description: "Search your Cortex memories",
+		acceptsArgs: true,
+		requireAuth: true,
+		handler: async (ctx: { args?: string }) => {
+			const query = ctx.args?.trim()
+			if (!query) return { text: "Usage: /cortex-recall <query>" }
+
+			try {
+				const res = await client.recall(query, {
+					maxResults: cfg.maxRecallResults,
+					mode: cfg.recallMode,
+					graphContext: cfg.graphContext,
+				})
+
+				if (!res.chunks || res.chunks.length === 0) {
+					return { text: `No memories found for "${query}"` }
+				}
+
+				const lines = res.chunks.slice(0, 10).map((c, i) => {
+					const score = c.relevancy_score != null ? ` (${Math.round(c.relevancy_score * 100)}%)` : ""
+					const title = c.source_title ? ` [${c.source_title}]` : ""
+					return `${i + 1}.${title} ${preview(c.chunk_content, 120)}${score}`
+				})
+
+				return { text: `Found ${res.chunks.length} chunks:\n\n${lines.join("\n")}` }
+			} catch (err) {
+				log.error("/cortex-recall", err)
+				return { text: "Recall failed. Check logs." }
+			}
+		},
+	})
+
+	api.registerCommand({
+		name: "cortex-list",
+		description: "List all stored user memories",
+		acceptsArgs: false,
+		requireAuth: true,
+		handler: async () => {
+			try {
+				const res = await client.listMemories()
+				const memories = res.user_memories ?? []
+				if (memories.length === 0) return { text: "No memories stored yet." }
+
+				const lines = memories.map(
+					(m, i) => `${i + 1}. [${m.memory_id}] ${preview(m.memory_content, 100)}`,
+				)
+				return { text: `${memories.length} memories:\n\n${lines.join("\n")}` }
+			} catch (err) {
+				log.error("/cortex-list", err)
+				return { text: "Failed to list memories. Check logs." }
+			}
+		},
+	})
+
+	api.registerCommand({
+		name: "cortex-delete",
+		description: "Delete a specific memory by its ID",
+		acceptsArgs: true,
+		requireAuth: true,
+		handler: async (ctx: { args?: string }) => {
+			const memoryId = ctx.args?.trim()
+			if (!memoryId) return { text: "Usage: /cortex-delete <memory_id>" }
+
+			try {
+				const res = await client.deleteMemory(memoryId)
+				if (res.user_memory_deleted) {
+					return { text: `Deleted memory: ${memoryId}` }
+				}
+				return { text: `Memory ${memoryId} was not found or already deleted.` }
+			} catch (err) {
+				log.error("/cortex-delete", err)
+				return { text: "Delete failed. Check logs." }
+			}
+		},
+	})
+
+	api.registerCommand({
+		name: "cortex-get",
+		description: "Fetch the content of a specific source by its ID",
+		acceptsArgs: true,
+		requireAuth: true,
+		handler: async (ctx: { args?: string }) => {
+			const sourceId = ctx.args?.trim()
+			if (!sourceId) return { text: "Usage: /cortex-get <source_id>" }
+
+			try {
+				const res = await client.fetchContent(sourceId)
+				if (!res.success || res.error) {
+					return { text: `Could not fetch source ${sourceId}: ${res.error ?? "unknown error"}` }
+				}
+				const content = res.content ?? res.content_base64 ?? "(no text content)"
+				return { text: `Source: ${sourceId}\n\n${preview(content, 2000)}` }
+			} catch (err) {
+				log.error("/cortex-get", err)
+				return { text: "Fetch failed. Check logs." }
+			}
+		},
+	})
+}

package/config.ts

@@ -0,0 +1,95 @@
+export type CortexPluginConfig = {
+	apiKey: string
+	tenantId: string
+	subTenantId: string
+	autoRecall: boolean
+	autoCapture: boolean
+	maxRecallResults: number
+	recallMode: "fast" | "thinking"
+	graphContext: boolean
+	debug: boolean
+}
+
+const KNOWN_KEYS = new Set([
+	"apiKey",
+	"tenantId",
+	"subTenantId",
+	"autoRecall",
+	"autoCapture",
+	"maxRecallResults",
+	"recallMode",
+	"graphContext",
+	"debug",
+])
+
+const DEFAULT_SUB_TENANT = "cortex-openclaw"
+
+function envOrNull(name: string): string | undefined {
+	return typeof process !== "undefined" ? process.env[name] : undefined
+}
+
+function resolveEnvVars(value: string): string {
+	return value.replace(/\$\{([^}]+)\}/g, (_, name: string) => {
+		const val = envOrNull(name)
+		if (!val) throw new Error(`Environment variable ${name} is not set`)
+		return val
+	})
+}
+
+export function parseConfig(raw: unknown): CortexPluginConfig {
+	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(", ")}`)
+	}
+
+	const apiKey =
+		typeof cfg.apiKey === "string" && cfg.apiKey.length > 0
+			? resolveEnvVars(cfg.apiKey)
+			: envOrNull("CORTEX_OPENCLAW_API_KEY")
+
+	if (!apiKey) {
+		throw new Error(
+			"cortex-ai: apiKey is required — set it in plugin config or via CORTEX_OPENCLAW_API_KEY env var",
+		)
+	}
+
+	const tenantId =
+		typeof cfg.tenantId === "string" && cfg.tenantId.length > 0
+			? resolveEnvVars(cfg.tenantId)
+			: envOrNull("CORTEX_OPENCLAW_TENANT_ID")
+
+	if (!tenantId) {
+		throw new Error(
+			"cortex-ai: tenantId is required — set it in plugin config or via CORTEX_OPENCLAW_TENANT_ID env var",
+		)
+	}
+
+	const subTenantId =
+		typeof cfg.subTenantId === "string" && cfg.subTenantId.length > 0
+			? cfg.subTenantId
+			: DEFAULT_SUB_TENANT
+
+	return {
+		apiKey,
+		tenantId,
+		subTenantId,
+		autoRecall: (cfg.autoRecall as boolean) ?? true,
+		autoCapture: (cfg.autoCapture as boolean) ?? true,
+		maxRecallResults: (cfg.maxRecallResults as number) ?? 10,
+		recallMode:
+			cfg.recallMode === "thinking"
+				? ("thinking" as const)
+				: ("fast" as const),
+		graphContext: (cfg.graphContext as boolean) ?? true,
+		debug: (cfg.debug as boolean) ?? false,
+	}
+}
+
+export const cortexConfigSchema = {
+	parse: parseConfig,
+}