@usecortex_ai/openclaw-cortex-ai 0.0.1 → 0.1.0

package/.github/workflows/publish.yaml

@@ -0,0 +1,40 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    name: Publish package to npm
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build package
+        # If you have a build step, otherwise remove this
+        run: npm run build
+        continue-on-error: true
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          # Only publish if this is not a pre-release and version has changed
+          if [ "$(npm view . version)" != "$(node -p "require('./package.json').version")" ]; then
+            npm publish --access public
+          else
+            echo "Version already published, skipping."
+          fi

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+State-of-the-art agentic 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
 
@@ -39,44 +39,43 @@ Or configure directly in `openclaw.json`:
 
 ### 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                                                         |
+| 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                 |
+| 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               |
+| Tool              | Description                                 |
+| ----------------- | ------------------------------------------- |
+| `cortex_store`  | Save information to memory                  |
+| `cortex_search` | Search memories with graph-enriched results |
 
 ## CLI
 
 ```bash
 openclaw cortex search <query>     # Search memories
-openclaw cortex list               # List all user 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
@@ -87,4 +86,5 @@ 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/client.ts

@@ -18,7 +18,9 @@ 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."
+	"that would help personalise future interactions. Capture important personal details like " +
+	"name, age, email ids, phone numbers, etc. along with the original name and context " +
+	"so that it can be used to personalise future interactions."
 
 export class CortexClient {
 	private apiKey: string
@@ -74,7 +76,10 @@ export class CortexClient {
 	async ingestConversation(
 		turns: ConversationTurn[],
 		sourceId: string,
-		userName?: string,
+		opts?: {
+			userName?: string
+			metadata?: Record<string, unknown>
+		},
 	): Promise<AddMemoryResponse> {
 		const payload: AddMemoryRequest = {
 			memories: [
@@ -82,8 +87,11 @@ export class CortexClient {
 					user_assistant_pairs: turns,
 					infer: true,
 					source_id: sourceId,
-					user_name: userName ?? "User",
+					user_name: opts?.userName ?? "User",
 					custom_instructions: INGEST_INSTRUCTIONS,
+					...(opts?.metadata && {
+						document_metadata: JSON.stringify(opts.metadata),
+					}),
 				},
 			],
 			tenant_id: this.tenantId,

package/commands/slash.ts

@@ -2,7 +2,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 { toSourceId } from "../session.ts"
+import { toToolSourceId } from "../session.ts"
 
 function preview(text: string, max = 80): string {
 	return text.length > max ? `${text.slice(0, max)}…` : text
@@ -12,7 +12,7 @@ export function registerSlashCommands(
 	api: OpenClawPluginApi,
 	client: CortexClient,
 	cfg: CortexPluginConfig,
-	getSessionKey: () => string | undefined,
+	getSessionId: () => string | undefined,
 ): void {
 	api.registerCommand({
 		name: "cortex-remember",
@@ -24,8 +24,8 @@ export function registerSlashCommands(
 			if (!text) return { text: "Usage: /cortex-remember <text to store>" }
 
 			try {
-				const sk = getSessionKey()
-				const sourceId = sk ? toSourceId(sk) : undefined
+				const sid = getSessionId()
+				const sourceId = sid ? toToolSourceId(sid) : undefined
 				await client.ingestText(text, { sourceId, title: "Manual Memory", infer: true })
 				return { text: `Saved: "${preview(text, 60)}"` }
 			} catch (err) {

package/config.ts

@@ -22,7 +22,7 @@ const KNOWN_KEYS = new Set([
 	"debug",
 ])
 
-const DEFAULT_SUB_TENANT = "cortex-openclaw"
+const DEFAULT_SUB_TENANT = "cortex-openclaw-plugin"
 
 function envOrNull(name: string): string | undefined {
 	return typeof process !== "undefined" ? process.env[name] : undefined

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 } 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()
@@ -52,34 +14,83 @@ function removeInjectedBlocks(text: string): string {
 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
+	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 allTurns = extractAllTurns(event.messages)
 
-		log.debug(`ingesting turn (u=${userClean.length}c, a=${assistantClean.length}c) → ${sourceId}`)
+			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/index.ts

@@ -6,6 +6,9 @@ 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"
 
@@ -20,32 +23,48 @@ export default {
 	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)
+		registerSlashCommands(api, client, cfg, getSessionId)
 		registerCliCommands(api, client, cfg)
 
 		api.registerService({

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,73 @@
+import type { ConversationTurn } from "./types/cortex.ts"
+
+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/package.json

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

@@ -3,23 +3,32 @@ 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"
+import { extractAllTurns } from "../messages.ts"
+import { toToolSourceId } from "../session.ts"
+import type { ConversationTurn } from "../types/cortex.ts"
+
+const MAX_STORE_TURNS = 10
+
+function removeInjectedBlocks(text: string): string {
+	return text.replace(/<cortex-context>[\s\S]*?<\/cortex-context>\s*/g, "").trim()
+}
 
 export function registerStoreTool(
 	api: OpenClawPluginApi,
 	client: CortexClient,
 	_cfg: CortexPluginConfig,
-	getSessionKey: () => string | undefined,
+	getSessionId: () => string | undefined,
+	getMessages: () => unknown[],
 ): 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.",
+				"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.",
 			parameters: Type.Object({
 				text: Type.String({
-					description: "The information to store in memory",
+					description: "A brief summary or note about what is being saved",
 				}),
 				title: Type.Optional(
 					Type.String({
@@ -31,10 +40,59 @@ export function registerStoreTool(
 				_toolCallId: string,
 				params: { text: string; title?: string },
 			) {
-				const sk = getSessionKey()
-				const sourceId = sk ? toSourceId(sk) : undefined
+				const sid = getSessionId()
+				const sourceId = sid ? toToolSourceId(sid) : undefined
+				const messages = getMessages()
+
+				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 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})`)
+
+				if (turns.length > 0 && sourceId) {
+					const now = new Date()
+					const readableTime = now.toLocaleString("en-US", {
+						weekday: "short",
+						year: "numeric",
+						month: "short",
+						day: "numeric",
+						hour: "2-digit",
+						minute: "2-digit",
+						timeZoneName: "short",
+					})
 
-				log.debug(`store tool: "${params.text.slice(0, 50)}" - \nsourceId: ${sourceId}`)
+					const annotatedTurns = turns.map((t, i) => ({
+						user: i === 0 ? `[Temporal details: ${readableTime}]\n\n${t.user}` : t.user,
+						assistant: t.assistant,
+					}))
+
+					log.debug(`[store] ingesting ${annotatedTurns.length} conversation turns -> ${sourceId}`)
+
+					await client.ingestConversation(annotatedTurns, sourceId, {
+						metadata: {
+							captured_at: now.toISOString(),
+							source: "openclaw_tool",
+							note: params.text,
+						},
+					})
+
+					return {
+						content: [
+							{
+								type: "text" as const,
+								text: `Saved ${annotatedTurns.length} conversation turns to Cortex (${sourceId}). Note: "${params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text}"`,
+							},
+						],
+					}
+				}
+
+				log.debug("[store] no conversation turns found, falling back to text ingestion")
 
 				await client.ingestText(params.text, {
 					sourceId,
@@ -42,16 +100,11 @@ export function registerStoreTool(
 					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}"`,
+							text: `Saved to Cortex: "${params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text}"`,
 						},
 					],
 				}

package/types/cortex.ts

@@ -13,6 +13,8 @@ export type MemoryPayload = {
 	source_id?: string
 	title?: string
 	expiry_time?: number
+	document_metadata?: string
+	tenant_metadata?: string
 }
 
 export type AddMemoryRequest = {