@octamem/octamem-openclaw 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OctaMem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @octamem/octamem-openclaw
+
+OctaMem personal memory plugin for [OpenClaw](https://openclaw.ai). Adds search/add tools and automatic memory recall and capture so the assistant can use and update your personal memory.
+
+## Requirements
+
+- OpenClaw `>=2026.1.29`
+- OctaMem API key (personal memory)
+
+## Install
+
+```bash
+npm install @octamem/octamem-openclaw
+```
+
+Or from the OpenClaw plugins list:
+
+```bash
+openclaw plugins install @octamem/octamem-openclaw
+```
+
+## Configure
+
+Get your API key from [platform.octamem.com](https://platform.octamem.com). Then set it:
+
+```bash
+openclaw octamem configure <your-api-key>
+```
+
+Or set `OCTAMEM_PERSONAL_KEY` and run:
+
+```bash
+openclaw octamem configure
+```
+
+Restart OpenClaw after configuring.
+
+## What it does
+
+- **Auto-recall**: Before each turn, relevant personal memory is fetched and injected so the LLM can answer from your notes.
+- **Auto-capture**: After each turn, the assistant’s reply is stored in your personal memory (plain text).
+- **Tools**: `octamem_get` (search) and `octamem_add` (add) for the agent to query or store memory when needed.
+- **CLI**: `openclaw octamem status | search <query> | details | add <content>`.
+
+## Config (optional)
+
+In OpenClaw plugin config you can set:
+
+- `memories.personal.apiKey` — API key (supports `${OCTAMEM_PERSONAL_KEY}`).
+- `toolDescription` — Override the description for the get-memory tool.
+
+## License
+
+MIT

package/biome.json

@@ -0,0 +1,77 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
+	"assist": {
+		"actions": {
+			"source": {
+				"organizeImports": "on",
+				"useSortedAttributes": "on",
+				"useSortedKeys": "off"
+			}
+		},
+		"enabled": true
+	},
+	"files": {
+		"includes": [
+			"**",
+			"!**/node_modules",
+			"!**/dist",
+			"!**/bun.lock",
+			"!**/*.lock"
+		]
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double",
+			"semicolons": "asNeeded"
+		}
+	},
+	"linter": {
+		"domains": {
+			"project": "none"
+		},
+		"enabled": true,
+		"rules": {
+			"correctness": {
+				"useYield": "warn",
+				"noUnusedVariables": {
+					"level": "warn",
+					"options": {
+						"ignoreRestSiblings": true
+					}
+				},
+				"noUnusedImports": "warn",
+				"useParseIntRadix": "off"
+			},
+			"recommended": true,
+			"style": {
+				"noDefaultExport": "off",
+				"noInferrableTypes": "error",
+				"noNonNullAssertion": "warn",
+				"noParameterAssign": "error",
+				"noUnusedTemplateLiteral": "error",
+				"noUselessElse": "error",
+				"useAsConstAssertion": "error",
+				"useDefaultParameterLast": "error",
+				"useEnumInitializers": "error",
+				"useNamingConvention": {
+					"level": "off",
+					"options": {
+						"strictCase": false
+					}
+				},
+				"useNumberNamespace": "error",
+				"useSelfClosingElements": "error",
+				"useSingleVarDeclarator": "error"
+			}
+		}
+	},
+	"vcs": {
+		"clientKind": "git",
+		"enabled": true,
+		"useIgnoreFile": true
+	}
+}

package/openclaw.plugin.json

@@ -0,0 +1,50 @@
+{
+	"id": "octamem-openclaw",
+	"kind": "memory",
+	"uiHints": {
+		"memories": {
+			"label": "Personal Memory",
+			"help": "Configure API key for personal memory"
+		},
+		"memories.personal": {
+			"label": "Personal Memory",
+			"help": "Your personal memory API key (read/write access)"
+		},
+		"memories.personal.apiKey": {
+			"label": "Personal API Key",
+			"sensitive": true,
+			"placeholder": "pk_personal_...",
+			"help": "API key for personal memory (or use ${OCTAMEM_PERSONAL_KEY})"
+		},
+		"toolDescription": {
+			"label": "Get tool description",
+			"help": "Custom description for the get/search memory tool (how the LLM sees it)"
+		},
+		"addToolDescription": {
+			"label": "Add tool description",
+			"help": "Custom description for the add/store memory tool (how the LLM sees it)"
+		}
+	},
+	"configSchema": {
+		"type": "object",
+		"additionalProperties": false,
+		"properties": {
+			"memories": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"personal": {
+						"type": "object",
+						"properties": {
+							"apiKey": { "type": "string" }
+						},
+						"required": ["apiKey"]
+					}
+				}
+			},
+			"toolDescription": { "type": "string" },
+			"addToolDescription": { "type": "string" }
+		},
+		"required": []
+	}
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@octamem/octamem-openclaw",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "OctaMem personal memory plugin for OpenClaw",
+	"license": "MIT",
+	"author": "OctaMem",
+	"keywords": [
+		"openclaw",
+		"plugin",
+		"memory",
+		"ai",
+		"octamem"
+	],
+	"dependencies": {
+		"@sinclair/typebox": "0.34.47"
+	},
+	"scripts": {
+		"build": "tsc --noEmit",
+		"check-types": "tsc --noEmit",
+		"lint": "bunx @biomejs/biome ci .",
+		"lint:fix": "bunx @biomejs/biome check --write ."
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.1.29"
+	},
+	"openclaw": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"openclaw": "^2026.3.2",
+		"typescript": "^5.9.3"
+	}
+}

package/src/client.ts

@@ -0,0 +1,152 @@
+import { logRequest } from "./logger.ts"
+import type {
+	AddResult,
+	ChatContext,
+	LastQa,
+	OctaMemConfig,
+	SearchResult,
+} from "./types.ts"
+
+/**
+ * OctaMem Memory API base URL.
+ * API key must be sent in a header (Authorization: Bearer <key> or X-API-Key), not in the body.
+ * - POST /search  — body: { query, previousContext? }
+ * - POST /add     — body: { content, previousContext? }
+ * - POST /details — body: {} or omitted
+ */
+const API_BASE = "http://platform.octamem.com/api/memory"
+
+type ApiBody = { success?: boolean; error?: string; message?: string; [k: string]: unknown }
+
+/** Prefer API message for user-facing error; no hard-coded error codes. */
+function apiErrorMessage(data: ApiBody | null): string | null {
+	if (!data || typeof data !== "object") return null
+	if (typeof data.message === "string" && data.message.length > 0) return data.message
+	if (typeof data.error === "string" && data.error.length > 0) return data.error
+	return null
+}
+
+/**
+ * Client for the OctaMem personal-memory API (search, add, details).
+ * Requires config.memories.personal.apiKey to be set.
+ */
+export class OctaMemClient {
+	private readonly apiKey: string
+
+	constructor(config: OctaMemConfig) {
+		const key = config.memories.personal?.apiKey
+		if (!key) throw new Error("Personal memory API key not configured")
+		this.apiKey = key
+	}
+
+	/** Headers for Memory API: key in Authorization Bearer (recommended). */
+	private authHeaders(): Record<string, string> {
+		return {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${this.apiKey}`,
+		}
+	}
+
+	/** Returns true if config has a valid personal memory API key. */
+	static isConfigured(config: OctaMemConfig): boolean {
+		return Boolean(config.memories.personal?.apiKey)
+	}
+
+	/** Serializes chat context for API previousContext field. */
+	private contextStr(ctx: ChatContext): string {
+		return ctx
+			.flatMap((t) => [
+				`user: ${t.user}`,
+				t.assistant ? `assistant: ${t.assistant}` : null,
+			])
+			.filter(Boolean)
+			.join(" | ")
+	}
+
+	/**
+	 * Searches personal memory; returns the raw API response for the LLM.
+	 * @param query - Search query text.
+	 * @param context - Recent user/assistant turns (previousContext sent to API).
+	 */
+	async search(query: string, context: ChatContext = []): Promise<SearchResult> {
+		try {
+			const previousContext = this.contextStr(context)
+			const payload = { query, previousContext }
+			logRequest("POST /api/memory/search", payload)
+			const res = await fetch(`${API_BASE}/search`, {
+				method: "POST",
+				headers: this.authHeaders(),
+				body: JSON.stringify(payload),
+			})
+			const data = (await res.json().catch(() => null)) as ApiBody | null
+			const apiMsg = apiErrorMessage(data)
+			if (!res.ok) {
+				return { success: false, query, error: apiMsg ?? `API ${res.status}` }
+			}
+			if (data && data.success === false) {
+				return { success: false, query, error: apiMsg ?? "Request failed" }
+			}
+			return { success: true, data: data ?? undefined, query }
+		} catch (e) {
+			return { success: false, query, error: e instanceof Error ? e.message : String(e) }
+		}
+	}
+
+	/**
+	 * Stores content in personal memory. If lastQa is provided, stores a Q&A pair instead of raw content.
+	 * @param content - Text to store (or ignored when lastQa is set).
+	 * @param metadata - Optional metadata (e.g. category, source).
+	 * @param context - Recent chat turns for API previousContext.
+	 * @param lastQa - If set, stores "User: ... Assistant: ..." instead of content.
+	 */
+	async add(
+		content: string,
+		metadata: Record<string, unknown> = {},
+		context: ChatContext = [],
+		lastQa?: LastQa,
+	): Promise<AddResult> {
+		try {
+			const body = lastQa
+				? `User: ${lastQa.query}\nAssistant: ${lastQa.response}`
+				: content
+			const previousContext = this.contextStr(context)
+			const payload = { content: body, previousContext }
+			logRequest("POST /api/memory/add", payload)
+			const res = await fetch(`${API_BASE}/add`, {
+				method: "POST",
+				headers: this.authHeaders(),
+				body: JSON.stringify(payload),
+			})
+			const data = (await res.json().catch(() => null)) as ApiBody | null
+			const apiMsg = apiErrorMessage(data)
+			if (!res.ok) {
+				return { success: false, id: "", message: apiMsg ?? `API ${res.status}` }
+			}
+			if (data && data.success === false) {
+				return { success: false, id: "", message: apiMsg ?? "Request failed" }
+			}
+			return { success: true, id: `mem_${Date.now()}`, message: "Memory stored successfully" }
+		} catch (e) {
+			return { success: false, id: "", message: e instanceof Error ? e.message : "Unknown error" }
+		}
+	}
+
+	/** Fetches account/details for the configured personal memory. */
+	async details(): Promise<{ success: boolean; data?: unknown; error?: string }> {
+		try {
+			const res = await fetch(`${API_BASE}/details`, {
+				method: "POST",
+				headers: this.authHeaders(),
+				body: "{}",
+			})
+			const data = (await res.json().catch(() => null)) as ApiBody | null
+			const apiMsg = apiErrorMessage(data)
+			if (!res.ok) {
+				return { success: false, error: apiMsg ?? `API ${res.status}` }
+			}
+			return { success: true, data: data ?? undefined }
+		} catch (e) {
+			return { success: false, error: e instanceof Error ? e.message : String(e) }
+		}
+	}
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+import type { OctaMemConfig } from "./types.ts"
+
+const ALLOWED_KEYS = ["memories", "toolDescription", "addToolDescription", "autoRecall", "autoCapture"]
+
+/**
+ * Replaces ${VAR} placeholders in a string with process.env[VAR].
+ * @throws If a referenced env var is not set.
+ */
+function resolveEnv(s: string): string {
+	return s.replace(/\$\{([^}]+)\}/g, (_, key: string) => {
+		const v = process.env[key]
+		if (!v) throw new Error(`Env ${key} not set`)
+		return v
+	})
+}
+
+/**
+ * Parses and validates raw plugin config into OctaMemConfig.
+ * Only known keys are allowed; personal memory apiKey supports ${ENV} substitution.
+ * @returns Normalized config with memories.personal set only if apiKey is valid.
+ */
+export function parseConfig(raw: unknown): OctaMemConfig {
+	const o = raw && typeof raw === "object" && !Array.isArray(raw)
+		? (raw as Record<string, unknown>)
+		: {}
+
+	if (Object.keys(o).length > 0) {
+		const bad = Object.keys(o).filter((k) => !ALLOWED_KEYS.includes(k))
+		if (bad.length) throw new Error(`Unknown config: ${bad.join(", ")}`)
+	}
+
+	const memories: OctaMemConfig["memories"] = {}
+	const personalRaw = o.memories && typeof o.memories === "object"
+		? (o.memories as Record<string, unknown>).personal
+		: undefined
+
+	if (personalRaw && typeof personalRaw === "object") {
+		const p = personalRaw as Record<string, unknown>
+		if (typeof p.apiKey === "string" && p.apiKey.length > 0) {
+			try {
+				memories.personal = {
+					apiKey: resolveEnv(p.apiKey),
+					description: typeof p.description === "string" ? p.description : undefined,
+				}
+			} catch {
+				// skip invalid personal config
+			}
+		}
+	}
+
+	return {
+		memories,
+		toolDescription: typeof o.toolDescription === "string" ? o.toolDescription : undefined,
+		addToolDescription: typeof o.addToolDescription === "string" ? o.addToolDescription : undefined,
+	}
+}
+
+/** OpenClaw config schema and parser for the OctaMem plugin. */
+export const configSchema = {
+	jsonSchema: {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			memories: {
+				type: "object",
+				properties: {
+					personal: {
+						type: "object",
+						properties: { apiKey: { type: "string" }, description: { type: "string" } },
+						required: ["apiKey"],
+					},
+				},
+			},
+			toolDescription: { type: "string" },
+			addToolDescription: { type: "string" },
+		},
+	},
+	parse: parseConfig,
+}

package/src/context.ts

@@ -0,0 +1,145 @@
+import fs from "node:fs"
+import path from "node:path"
+import type { ChatContext } from "./types.ts"
+
+/** Max number of user/assistant pairs sent as previousContext to the OctaMem API (search/add). */
+export const PREVIOUS_CONTEXT_PAIRS = 3
+
+const OCTAMEM_TAG = /<octamem-context>[\s\S]*?<\/octamem-context>\s*/g
+/** Sender (untrusted metadata) block: "Sender (untrusted metadata):" plus fenced block. */
+const SENDER_METADATA = /Sender\s*\(untrusted\s+metadata\)\s*:\s*```[\s\S]*?```\s*/gi
+/** Leading [timestamp] or [anything] prefix. */
+const BRACKET_PREFIX = /^\[[^\]]*\]\s*/
+/** Leading stray ] (e.g. from some assistant message formats). */
+const LEADING_BRACKET = /^\s*\]\s*/
+
+/** Session startup / system instruction text; exclude from previousContext and skip memory search. */
+export function isSessionStartup(text: string): boolean {
+	const t = text.trim().toLowerCase()
+	return (
+		t.startsWith("a new session was started") ||
+		t.includes("session startup sequence") ||
+		t.includes("run your session startup")
+	)
+}
+
+/**
+ * Extracts plain text from an OpenClaw message (string content or array of text parts).
+ */
+export function getMessageText(msg: Record<string, unknown>): string {
+	if (typeof msg.content === "string") return msg.content
+	if (Array.isArray(msg.content)) {
+		return (msg.content as Array<{ type?: string; text?: string }>)
+			.filter((p) => p.type === "text" && typeof p.text === "string")
+			.map((p) => p.text as string)
+			.join(" ")
+	}
+	return ""
+}
+
+/**
+ * Strips OpenClaw metadata from a raw string (e.g. prompt or message content).
+ */
+function stripMetadata(s: string): string {
+	return s
+		.replace(OCTAMEM_TAG, "")
+		.replace(SENDER_METADATA, "")
+		.replace(BRACKET_PREFIX, "")
+		.replace(LEADING_BRACKET, "")
+		.trim()
+}
+
+/**
+ * Returns only the user or assistant utterance: no metadata, no timestamps.
+ * Use for previousContext and for stored content (add).
+ */
+export function getCleanMessageText(msg: Record<string, unknown>): string {
+	return stripMetadata(getMessageText(msg))
+}
+
+/** Cleans a raw prompt string (e.g. for search query). */
+export function getCleanPrompt(prompt: string): string {
+	return stripMetadata(prompt)
+}
+
+/**
+ * Returns user/assistant turns (oldest first) with clean text only. Used to build previousContext.
+ */
+function getTurns(messages: unknown[]): { role: string; text: string }[] {
+	const out: { role: string; text: string }[] = []
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i] as Record<string, unknown>
+		const role = m?.role as string
+		if (role !== "user" && role !== "assistant") continue
+		const text = getCleanMessageText(m)
+		if (text.length < 2) continue
+		out.push({ role, text })
+	}
+	return out.reverse()
+}
+
+/**
+ * Loads message objects from the session JSONL file; returns [] on missing file or parse error.
+ */
+function loadSession(stateDir: string, sessionId: string): unknown[] {
+	try {
+		const file = path.join(stateDir, "agents", "main", "sessions", `${sessionId}.jsonl`)
+		return fs
+			.readFileSync(file, "utf-8")
+			.split("\n")
+			.filter((l) => l.trim())
+			.map((l) => JSON.parse(l) as Record<string, unknown>)
+			.filter((r) => r.type === "message" && r.message)
+			.map((r) => r.message)
+	} catch {
+		return []
+	}
+}
+
+/**
+ * Builds ChatContext (user/assistant pairs) from in-memory messages or by loading the session file.
+ * Used for auto-recall and post-response save to provide conversation context to the API.
+ * @param messages - Event messages if available.
+ * @param stateDir - OpenClaw state dir (for session file path).
+ * @param sessionId - Session id (for session file name).
+ */
+export function getRecentContext(
+	messages: unknown[] | undefined,
+	stateDir: string | undefined,
+	sessionId: string | undefined,
+): ChatContext {
+	const msgs =
+		messages?.length
+			? messages
+			: stateDir && sessionId
+				? loadSession(stateDir, sessionId)
+				: []
+	const turns = getTurns(msgs)
+	const ctx: ChatContext = []
+	for (let i = 0; i < turns.length; i++) {
+		const t = turns[i]
+		if (t.role !== "user") continue
+		if (isSessionStartup(t.text)) {
+			if (turns[i + 1]?.role === "assistant") i++
+			continue
+		}
+		const next = turns[i + 1]
+		if (next?.role === "assistant") {
+			ctx.push({ user: t.text, assistant: next.text })
+			i++
+		} else {
+			ctx.push({ user: t.text, assistant: null })
+		}
+	}
+	return ctx
+}
+
+/**
+ * Returns at most PREVIOUS_CONTEXT_PAIRS for the API previousContext field.
+ * @param ctx - Full chat context (oldest first).
+ * @param excludeLast - If true, omit the last pair (use when storing that pair as content).
+ */
+export function getPreviousContextForApi(ctx: ChatContext, excludeLast: boolean): ChatContext {
+	const base = excludeLast ? ctx.slice(0, -1) : ctx
+	return base.slice(-PREVIOUS_CONTEXT_PAIRS)
+}

package/src/index.ts

@@ -0,0 +1,284 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { OctaMemClient } from "./client.ts"
+import { configSchema, parseConfig } from "./config.ts"
+import {
+	resolveOpenClawConfigPath,
+	writeOctaMemPluginConfig,
+	type OctaMemPluginConfig,
+} from "./openclaw-config.ts"
+import { getCleanMessageText, getCleanPrompt, isSessionStartup, getPreviousContextForApi, getRecentContext } from "./context.ts"
+
+const TOOL_DESC =
+	"Get memories from OctaMem (personal memory)."
+const ADD_DESC =
+	"Save information to personal memory: preferences, facts, names, interests, context. Be proactive when the user shares something worth remembering."
+
+/** Builds the content array for an OpenClaw tool response (single text part). */
+function textContent(text: string) {
+	return [{ type: "text" as const, text }]
+}
+
+/** Message shown when memory API is unavailable. Explicit instruction so the LLM tells the user. */
+function memoryUnavailable(reason: string) {
+	return `Inform the user in your reply: Personal memory is temporarily unavailable. ${reason}`
+}
+
+const MAX_MEMORY_SECTION_LEN = 1200
+
+/** Formats API memory response as readable text for prependContext (no raw JSON). */
+function formatMemoryBlock(raw: unknown): string {
+	const data = raw && typeof raw === "object" && "data" in (raw as object)
+		? (raw as { data?: Record<string, unknown> }).data
+		: (raw as Record<string, unknown> | null)
+	if (!data || typeof data !== "object") return "No memory data."
+	const lines: string[] = []
+	const add = (label: string, value: unknown) => {
+		if (value == null || value === "") return
+		const s = typeof value === "string" ? value : String(value)
+		const trimmed = s.length > MAX_MEMORY_SECTION_LEN ? s.slice(0, MAX_MEMORY_SECTION_LEN) + "…" : s
+		lines.push(`${label}: ${trimmed}`)
+	}
+	add("Semantic", (data as Record<string, unknown>).semantic_memory)
+	add("Episodic", (data as Record<string, unknown>).episodic_memory)
+	add("Procedural", (data as Record<string, unknown>).procedural_memory)
+	return lines.length ? lines.join("\n\n") : "No memory data."
+}
+
+/**
+ * OpenClaw plugin: OctaMem personal memory (search, add, auto-recall, auto-capture).
+ * Registers tools octamem_get / octamem_add, CLI (octamem status/search/details/add), and lifecycle hooks.
+ */
+export default {
+	id: "octamem-openclaw",
+	name: "OctaMem",
+	description: "Personal memory for OpenClaw",
+	kind: "memory" as const,
+	configSchema,
+
+	/** Registers CLI (always), then tools and hooks when personal memory is configured. */
+	register(api: OpenClawPluginApi) {
+		const config = parseConfig(api.pluginConfig)
+		const configured = OctaMemClient.isConfigured(config)
+		const client = configured ? new OctaMemClient(config) : null
+		const stateDir = api.runtime.state.resolveStateDir()
+		const toolDesc = config.toolDescription ?? TOOL_DESC
+		const addToolDesc = config.addToolDescription ?? ADD_DESC
+
+		// CLI is always registered so users can run `openclaw octamem configure` without editing config.
+		api.registerCli(
+			({ program }) => {
+				const octamem = program.command("octamem").description("OctaMem memory commands")
+
+				octamem
+					.command("configure")
+					.description("Write OctaMem plugin config into OpenClaw config file")
+					.argument("[apiKey]", "Personal API key (or set OCTAMEM_PERSONAL_KEY)")
+					.option("--tool-desc-get <description>", "Custom description for the get/search tool")
+					.option("--tool-desc-add <description>", "Custom description for the add/store tool")
+					.action(async (apiKeyArg: string, opts: { toolDescGet?: string; toolDescAdd?: string }) => {
+						const apiKey =
+							(apiKeyArg && apiKeyArg.trim()) || process.env.OCTAMEM_PERSONAL_KEY || ""
+						if (!apiKey) {
+							console.log(
+								"Usage: openclaw octamem configure <apiKey>\n  Or set OCTAMEM_PERSONAL_KEY and run: openclaw octamem configure",
+							)
+							return
+						}
+						const configPath = resolveOpenClawConfigPath()
+						const written = writeOctaMemPluginConfig(configPath, {
+							apiKey: apiKey.trim(),
+							...(opts.toolDescGet !== undefined && { toolDescription: opts.toolDescGet }),
+							...(opts.toolDescAdd !== undefined && { addToolDescription: opts.toolDescAdd }),
+						})
+						console.log(`Config written to ${written}\nRestart OpenClaw to apply.`)
+					})
+
+				octamem.command("status").description("Show status").action(() => {
+					if (configured) {
+						console.log("\n# OctaMem Status\n\nPersonal memory: configured (read/write)\n")
+					} else {
+						console.log(
+							"\n# OctaMem Status\n\nNot configured. Run: openclaw octamem configure <apiKey>\n",
+						)
+					}
+				})
+
+				if (client) {
+					octamem
+						.command("search")
+						.description("Search personal memory")
+						.argument("<query>", "Search query")
+						.action(async (query: string) => {
+							const r = await client.search(query)
+							if (!r.success) return console.log("Error:", r.error ?? "Search failed")
+							const raw = r.data
+							console.log("\n# Search Results (personal)\n")
+							console.log(typeof raw === "string" ? raw : JSON.stringify(raw ?? {}, null, 2))
+						})
+					octamem.command("details").description("Memory details").action(async () => {
+						const r = await client.details()
+						if (!r.success) return console.log("Error:", r.error)
+						console.log("\n# Memory Details (personal)\n\n", JSON.stringify(r.data, null, 2))
+					})
+					octamem
+						.command("add")
+						.description("Add to personal memory")
+						.argument("<content>", "Content")
+						.action(async (content: string) => {
+							const r = await client.add(content)
+							if (!r.success) return console.log("Error:", r.message)
+							console.log("Stored (ID:", r.id + ")")
+						})
+				}
+			},
+			{ commands: ["octamem"] },
+		)
+
+		if (!client) return
+
+		api.registerTool(
+			{
+				name: "octamem_get",
+				label: "OctaMem Get",
+				description: toolDesc,
+				parameters: Type.Object({
+					query: Type.String({ description: "Search query" }),
+				}),
+				async execute(_, params) {
+					const result = await client.search(params.query)
+					if (!result.success) {
+						return { content: textContent(memoryUnavailable(result.error ?? "Search failed.")), details: undefined }
+					}
+					const raw = result.data
+					const text =
+						typeof raw === "string"
+							? raw
+							: JSON.stringify(raw === undefined || raw === null ? {} : raw, null, 2)
+					return {
+						content: textContent(text),
+						details: { memoryType: "personal", data: raw },
+					}
+				},
+			},
+			{ name: "octamem_get" },
+		)
+
+		api.registerTool(
+			{
+				name: "octamem_add",
+				label: "OctaMem Add",
+				description: addToolDesc,
+				parameters: Type.Object({
+					content: Type.String({ description: "Information to store" }),
+					category: Type.Optional(Type.String({ description: "Category: preference, fact, name, context, interest, reminder" })),
+				}),
+				async execute(_, params) {
+					const meta = params.category ? { category: params.category } : {}
+					const result = await client.add(params.content, meta)
+					if (!result.success) {
+						return { content: textContent(memoryUnavailable(result.message)), details: undefined }
+					}
+					const preview = params.content.length > 80 ? `${params.content.slice(0, 80)}...` : params.content
+					return {
+						content: textContent(`Stored to personal memory: "${preview}"`),
+						details: { id: result.id, memoryType: "personal" },
+					}
+				},
+			},
+			{ name: "octamem_add" },
+		)
+
+		let lastPrompt = ""
+		let lastTime = 0
+
+		/** Current turn prompt from event (before_prompt_build or before_agent_start). */
+		function getEventPrompt(event: { prompt?: string; messages?: unknown[] }): string {
+			if (typeof event.prompt === "string" && event.prompt.length > 0) return event.prompt
+			const msgs = event.messages ?? []
+			for (let i = msgs.length - 1; i >= 0; i--) {
+				const m = msgs[i] as Record<string, unknown>
+				if (m?.role === "user") return getCleanMessageText(m)
+			}
+			return ""
+		}
+
+		// Auto-recall and auto-capture are always on (part of the memory system).
+		{
+			const injectMemory = async (
+				event: { prompt?: string; messages?: unknown[] },
+				ctx: { sessionId?: string } | undefined,
+			) => {
+				const prompt = getEventPrompt(event)
+				if (!prompt || prompt.length < 5) return
+				const now = Date.now()
+				if (prompt === lastPrompt && now - lastTime < 2000) return
+				lastPrompt = prompt
+				lastTime = now
+				try {
+					const clean = getCleanPrompt(prompt)
+					if (isSessionStartup(clean)) return
+					// Use session file for context (same source as add) so previousContext matches add's flow.
+					const chatCtx =
+						stateDir && ctx?.sessionId
+							? getRecentContext(undefined, stateDir, ctx.sessionId)
+							: getRecentContext(event.messages, stateDir, ctx?.sessionId)
+					const lastPair = chatCtx[chatCtx.length - 1]
+					const excludeLast = lastPair?.user === clean && lastPair?.assistant === null
+					const prevCtx = getPreviousContextForApi(chatCtx, excludeLast)
+					const r = await client.search(clean, prevCtx)
+					if (!r.success) {
+						const msg = r.error ?? "Search failed."
+						// appendSystemContext: inject into system prompt so it is not stored with the user message (docs.openclaw.ai/plugin).
+						return { appendSystemContext: `\n\n### Personal Memory\nIn your response, tell the user: Personal memory is temporarily unavailable. ${msg}` } as { prependContext?: string }
+					}
+					const raw = r.data
+					const block =
+						typeof raw === "string"
+							? raw
+							: formatMemoryBlock(raw)
+					return { appendSystemContext: `\n\n### Personal Memory\n${block}` } as { prependContext?: string }
+				} catch {
+					// skip
+				}
+			}
+
+			api.on("before_prompt_build", injectMemory)
+		}
+
+		// Memory of OpenClaw: save every user query + agent/LLM response to personal memory.
+		api.on("agent_end", async (event, ctx) => {
+			if (!event.success) return
+			const msgs = event.messages ?? []
+			let userText = ""
+			for (let i = msgs.length - 1; i >= 0; i--) {
+				const m = msgs[i] as Record<string, unknown>
+				if (m.role === "user") {
+					userText = getCleanMessageText(m)
+					break
+				}
+			}
+			if (!userText || userText.length < 5) return
+			if (isSessionStartup(userText)) return
+			let assistantText = ""
+			for (let i = msgs.length - 1; i >= 0; i--) {
+				const m = msgs[i] as Record<string, unknown>
+				if (m.role === "assistant") {
+					assistantText = getCleanMessageText(m)
+					break
+				}
+			}
+			if (!assistantText) return
+			const chatCtx = getRecentContext(event.messages, stateDir, ctx?.sessionId)
+			const prevCtx = getPreviousContextForApi(chatCtx, true)
+			// Store only the assistant reply as plain text (no "User: ... Assistant: ..." wrapper).
+			try {
+				await client.add(assistantText, { source: "post_response" }, prevCtx)
+			} catch {
+				// skip
+			}
+		})
+
+		api.registerService({ id: "octamem-openclaw", start: () => {}, stop: () => {} })
+	},
+}

package/src/logger.ts

@@ -0,0 +1,46 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+
+const LOG_PATH = path.join(os.homedir(), ".openclaw", "octamem-api.log")
+
+/** Redact apiKey in payload for safe logging. */
+function redactPayload(obj: Record<string, unknown>): Record<string, unknown> {
+	const out = { ...obj }
+	if (typeof out.apiKey === "string" && out.apiKey.length > 0) {
+		out.apiKey = "<redacted>"
+	}
+	return out
+}
+
+/**
+ * Appends a formatted log line for an API request to ~/.openclaw/octamem-api.log.
+ * Payload is JSON-formatted; apiKey is redacted.
+ */
+export function logRequest(endpoint: string, payload: Record<string, unknown>): void {
+	try {
+		const ts = new Date().toISOString()
+		const safe = redactPayload(payload)
+		const body = JSON.stringify(safe, null, 2)
+		const block = `\n=== ${ts} ${endpoint} ===\n${body}\n`
+		fs.appendFileSync(LOG_PATH, block)
+	} catch {
+		// ignore log errors
+	}
+}
+
+/**
+ * Appends the API response to ~/.openclaw/octamem-api.log (same file as request log).
+ */
+export function logResponse(endpoint: string, response: unknown): void {
+	try {
+		const ts = new Date().toISOString()
+		const body = typeof response === "object" && response !== null
+			? JSON.stringify(response, null, 2)
+			: String(response)
+		const block = `--- ${ts} ${endpoint} response ---\n${body}\n`
+		fs.appendFileSync(LOG_PATH, block)
+	} catch {
+		// ignore log errors
+	}
+}

package/src/openclaw-config.ts

@@ -0,0 +1,85 @@
+import fs from "node:fs"
+import path from "node:path"
+import os from "node:os"
+
+const CONFIG_DIR = ".openclaw"
+const CONFIG_FILES = ["openclaw.json", "config.json"]
+
+export type OctaMemPluginConfig = {
+	apiKey: string
+	/** Override description for the get (search) tool. */
+	toolDescription?: string
+	/** Override description for the add (store) tool. */
+	addToolDescription?: string
+}
+
+/**
+ * Resolves the path to the OpenClaw config file.
+ * Uses OPENCLAW_CONFIG env if set, otherwise ~/.openclaw/openclaw.json or config.json.
+ */
+export function resolveOpenClawConfigPath(): string {
+	const fromEnv = process.env.OPENCLAW_CONFIG
+	if (fromEnv) return fromEnv
+	const home = os.homedir()
+	const dir = path.join(home, CONFIG_DIR)
+	for (const name of CONFIG_FILES) {
+		const p = path.join(dir, name)
+		if (fs.existsSync(p)) return p
+	}
+	return path.join(dir, CONFIG_FILES[0])
+}
+
+/**
+ * Reads and parses the OpenClaw config file. Returns empty object if missing or invalid.
+ */
+export function readOpenClawConfig(configPath: string): Record<string, unknown> {
+	try {
+		const raw = fs.readFileSync(configPath, "utf-8")
+		const data = JSON.parse(raw)
+		return data && typeof data === "object" && !Array.isArray(data) ? data : {}
+	} catch {
+		return {}
+	}
+}
+
+/**
+ * Writes OctaMem plugin config into the OpenClaw config file (merge then write).
+ * Ensures plugins.enabled, plugins.slots.memory, and plugins.entries["octamem-openclaw"].
+ * @returns Path to the config file written.
+ */
+export function writeOctaMemPluginConfig(
+	configPath: string,
+	options: OctaMemPluginConfig,
+): string {
+	const data = readOpenClawConfig(configPath)
+	const plugins = (data.plugins && typeof data.plugins === "object"
+		? { ...(data.plugins as Record<string, unknown>) }
+		: {}) as Record<string, unknown>
+
+	plugins.enabled = true
+	plugins.slots = { ...(plugins.slots as Record<string, unknown>), memory: "octamem-openclaw" }
+	const entries = (plugins.entries && typeof plugins.entries === "object"
+		? { ...(plugins.entries as Record<string, unknown>) }
+		: {}) as Record<string, unknown>
+
+	const existing = entries["octamem-openclaw"]
+	const existingConfig = existing && typeof existing === "object" && (existing as Record<string, unknown>).config && typeof (existing as Record<string, unknown>).config === "object"
+		? { ...((existing as Record<string, unknown>).config as Record<string, unknown>) }
+		: {}
+	entries["octamem-openclaw"] = {
+		enabled: true,
+		config: {
+			...existingConfig,
+			memories: { personal: { apiKey: options.apiKey } },
+			...(options.toolDescription !== undefined && { toolDescription: options.toolDescription }),
+			...(options.addToolDescription !== undefined && { addToolDescription: options.addToolDescription }),
+		},
+	}
+	plugins.entries = entries
+	data.plugins = plugins
+
+	const dir = path.dirname(configPath)
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
+	fs.writeFileSync(configPath, JSON.stringify(data, null, 2), "utf-8")
+	return configPath
+}

package/src/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Plugin configuration shape (from OpenClaw plugin config).
+ * Only personal memory is supported; apiKey may use ${ENV_VAR} substitution.
+ */
+export type OctaMemConfig = {
+	memories: { personal?: { apiKey: string; description?: string } }
+	/** Description for the get/search tool (user-facing). */
+	toolDescription?: string
+	/** Description for the add/store tool (user-facing). */
+	addToolDescription?: string
+}
+
+/** A single user/assistant turn in chat history. */
+export type ChatTurn = { user: string; assistant: string | null }
+
+/** Ordered list of chat turns, used as context for search/add API calls. */
+export type ChatContext = ChatTurn[]
+
+/** Result of a search request; data is the raw API response (passed through to LLM). */
+export type SearchResult = {
+	success: boolean
+	data?: unknown
+	query: string
+	error?: string
+}
+
+/** Result of an add (store) request; message holds success or error text. */
+export type AddResult = {
+	success: boolean
+	id: string
+	message: string
+}
+
+/** Last user question and assistant reply; used when auto-saving a Q&A pair. */
+export type LastQa = { query: string; response: string }

package/tsconfig.json

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