@octamem/octamem-openclaw 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@octamem/octamem-openclaw",
-	"version": "1.0.3",
+	"version": "1.0.4",
 	"type": "module",
 	"description": "OctaMem personal memory plugin for OpenClaw",
 	"license": "MIT",

package/src/client.ts

@@ -1,152 +1,102 @@
 import { logRequest } from "./logger.ts"
 import type {
 	AddResult,
-	ChatContext,
-	LastQa,
+	MemoryData,
 	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
+/** Safely coerce any value to a string — handles objects, arrays, numbers, null, etc. */
+function asString(val: unknown): string {
+	if (val === null || val === undefined || val === "") return ""
+	if (typeof val === "string") return val
+	return JSON.stringify(val)
 }
 
-/**
- * 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")
+		if (!key) throw new Error("OctaMem API key missing")
 		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(" | ")
+	private headers() {
+		return {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${this.apiKey}`,
+		}
 	}
 
-	/**
-	 * 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> {
+	async search(query: string, previousContext: string): Promise<SearchResult> {
 		try {
-			const previousContext = this.contextStr(context)
 			const payload = { query, previousContext }
-			logRequest("POST /api/memory/search", payload)
+			logRequest("search", payload)
+
 			const res = await fetch(`${API_BASE}/search`, {
 				method: "POST",
-				headers: this.authHeaders(),
+				headers: this.headers(),
 				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}` }
+
+			const json = (await res.json().catch(() => null)) as Record<
+				string,
+				unknown
+			> | null
+
+			if (!res.ok || json?.success === false) {
+				const error =
+					(json?.message as string) ||
+					(json?.error as string) ||
+					"Search failed"
+				return { success: false, query, error }
 			}
-			if (data && data.success === false) {
-				return { success: false, query, error: apiMsg ?? "Request failed" }
+
+			const raw = (json?.data ?? {}) as Record<string, unknown>
+			const data: MemoryData = {
+				semantic_memory: asString(raw.semantic_memory),
+				episodic_memory: asString(raw.episodic_memory),
+				procedural_memory: asString(raw.procedural_memory),
 			}
-			return { success: true, data: data ?? undefined, query }
+
+			return { success: true, data, query }
 		} catch (e) {
-			return { success: false, query, error: e instanceof Error ? e.message : String(e) }
+			return { success: false, query, error: 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> {
+	async add(content: string, previousContext: string): 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 payload = { content, previousContext }
+			logRequest("add", payload)
+
 			const res = await fetch(`${API_BASE}/add`, {
 				method: "POST",
-				headers: this.authHeaders(),
+				headers: this.headers(),
 				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}` }
+			const json = (await res.json().catch(() => null)) as Record<
+				string,
+				unknown
+			> | null
+
+			if (!res.ok || json?.success === false) {
+				const message =
+					(json?.message as string) || (json?.error as string) || "Add failed"
+				return { success: false, message }
 			}
-			return { success: true, data: data ?? undefined }
+
+			return { success: true, message: (json?.message as string) || "Stored" }
 		} catch (e) {
-			return { success: false, error: e instanceof Error ? e.message : String(e) }
+			return { success: false, message: String(e) }
 		}
 	}
 }

package/src/config.ts

@@ -1,78 +1,29 @@
 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
-			}
-		}
-	}
+export function parseConfig(raw: any): OctaMemConfig {
+	const apiKey =
+		raw?.memories?.personal?.apiKey || process.env.OCTAMEM_PERSONAL_KEY || ""
 
 	return {
-		memories,
-		toolDescription: typeof o.toolDescription === "string" ? o.toolDescription : undefined,
-		addToolDescription: typeof o.addToolDescription === "string" ? o.addToolDescription : undefined,
+		memories: apiKey ? { personal: { apiKey } } : {},
 	}
 }
 
-/** 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"],
+						properties: {
+							apiKey: { type: "string" },
+						},
 					},
 				},
 			},
-			toolDescription: { type: "string" },
-			addToolDescription: { type: "string" },
 		},
 	},
 	parse: parseConfig,

package/src/context.ts

@@ -1,145 +1,180 @@
-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
+export const MAX_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*/
+/**
+ * Strips OpenClaw-injected wrappers from message text.
+ *
+ * OpenClaw wraps user prompts with:
+ *   1. A "Sender (untrusted metadata):" block containing a fenced ```json ... ``` section
+ *   2. A "[timestamp]" prefix like [Thu 2026-03-19 18:01 GMT+5:30]
+ *
+ * OpenClaw wraps assistant messages with:
+ *   3. [[tag]] markers like [[reply_to_current]]
+ *
+ * This function removes all three using plain string operations.
+ */
+export function stripOpenClawWrapper(text: string): string {
+	let s = text.trim()
+
+	// 1. Strip "Sender (untrusted metadata):\n```json\n{...}\n```" block
+	const senderMarker = "Sender (untrusted metadata):"
+	const senderIdx = s.indexOf(senderMarker)
+	if (senderIdx !== -1) {
+		const fenceOpen = s.indexOf("```", senderIdx + senderMarker.length)
+		if (fenceOpen !== -1) {
+			const fenceClose = s.indexOf("```", fenceOpen + 3)
+			if (fenceClose !== -1) {
+				s = s.slice(fenceClose + 3).trim()
+			}
+		}
+	}
+
+	// 2. Strip [timestamp] prefix — only if it starts with [ and closes within 80 chars
+	if (s.startsWith("[")) {
+		const close = s.indexOf("]")
+		if (close !== -1 && close < 80) {
+			s = s.slice(close + 1).trim()
+		}
+	}
+
+	// 3. Strip [[tag]] markers anywhere in text (e.g. [[reply_to_current]])
+	let safety = 10
+	while (s.includes("[[") && s.includes("]]") && safety-- > 0) {
+		const start = s.indexOf("[[")
+		const end = s.indexOf("]]", start)
+		if (end === -1) break
+		s = (s.slice(0, start) + s.slice(end + 2)).trim()
+	}
+
+	// 4. Strip leading stray ] that can remain after other stripping
+	if (s.startsWith("]")) {
+		s = s.slice(1).trim()
+	}
+
+	return s
+}
+
+const GREETINGS = new Set([
+	"hi",
+	"hello",
+	"hey",
+	"hola",
+	"howdy",
+	"yo",
+	"sup",
+	"greetings",
+	"good morning",
+	"good afternoon",
+	"good evening",
+	"good night",
+	"whats up",
+	"what's up",
+	"how are you",
+	"how's it going",
+])
+
+const SESSION_STARTUP_MARKERS = [
+	"a new session was started",
+	"session startup sequence",
+	"run your session startup",
+]
+
+function stripTrailingPunctuation(s: string): string {
+	let end = s.length
+	while (end > 0 && "!.,?;:' \t\n\"".includes(s[end - 1])) end--
+	return s.slice(0, end)
+}
+
+export function isGreeting(text: string): boolean {
+	const normalized = stripTrailingPunctuation(text.toLowerCase().trim())
+	if (!normalized) return true
+	if (GREETINGS.has(normalized)) return true
+	return false
+}
 
-/** 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")
-	)
+	const lower = text.trim().toLowerCase()
+	for (const marker of SESSION_STARTUP_MARKERS) {
+		if (lower.includes(marker)) return true
+	}
+	return false
 }
 
-/**
- * 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
+/** Returns true if this text should NOT be sent to OctaMem (greeting, startup, or empty). */
+export function shouldSkip(text: string): boolean {
+	if (!text || !text.trim()) return true
+	return isGreeting(text) || isSessionStartup(text)
+}
+
+/** Extracts raw text from an OpenClaw message object. */
+function getRawMessageText(msg: Record<string, unknown>): string {
+	if (typeof msg.content === "string") return msg.content.trim()
 	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(" ")
+			.trim()
 	}
 	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)
+/** Extracts clean text from an OpenClaw message, with metadata wrappers stripped. */
+export function getMessageText(msg: Record<string, unknown>): string {
+	return stripOpenClawWrapper(getRawMessageText(msg))
 }
 
 /**
- * Returns user/assistant turns (oldest first) with clean text only. Used to build previousContext.
+ * Collects user/assistant Q&A pairs from messages, skipping greetings and startup.
+ * Returns pairs in chronological order.
  */
-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>
+function collectPairs(messages: unknown[]): ChatContext {
+	const turns: { role: string; text: string }[] = []
+	for (const raw of messages) {
+		const m = raw 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 []
+		const text = getMessageText(m)
+		if (!text) continue
+		turns.push({ role, text })
 	}
-}
 
-/**
- * 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 = []
+	const pairs: 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].role !== "user") continue
+		if (shouldSkip(turns[i].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 })
+			pairs.push({ user: turns[i].text, assistant: next.text })
 			i++
 		} else {
-			ctx.push({ user: t.text, assistant: null })
+			pairs.push({ user: turns[i].text, assistant: null })
 		}
 	}
-	return ctx
+
+	return pairs
 }
 
 /**
- * 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).
+ * Builds the previousContext string from conversation messages.
+ * Format: "user: <query> | assistant: <answer> | user: <query2> | assistant: <answer2>"
+ * Max 3 pairs. Pass excludeLast=true when storing (to exclude the pair being stored).
  */
-export function getPreviousContextForApi(ctx: ChatContext, excludeLast: boolean): ChatContext {
-	const base = excludeLast ? ctx.slice(0, -1) : ctx
-	return base.slice(-PREVIOUS_CONTEXT_PAIRS)
+export function buildPreviousContext(
+	messages: unknown[],
+	excludeLast: boolean,
+): string {
+	const pairs = collectPairs(messages)
+	const base = excludeLast ? pairs.slice(0, -1) : pairs
+	const recent = base.slice(-MAX_CONTEXT_PAIRS)
+
+	if (recent.length === 0) return ""
+
+	return recent
+		.map((t) => `user: ${t.user} | assistant: ${t.assistant ?? ""}`)
+		.join(" | ")
 }

package/src/index.ts

@@ -3,327 +3,181 @@ 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). */
+	buildPreviousContext,
+	getMessageText,
+	shouldSkip,
+	stripOpenClawWrapper,
+} from "./context.ts"
+import { logLLMResponse } from "./logger.ts"
+import type { MemoryData } from "./types.ts"
+
 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}`
+function hasMemory(data: MemoryData): boolean {
+	return Boolean(
+		data.semantic_memory || data.episodic_memory || data.procedural_memory,
+	)
 }
 
-const MAX_MEMORY_SECTION_LEN = 1200
-
-/** Formats API memory response as readable text (used only for CLI/tool display). */
-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."
+function formatMemoryForLLM(data: MemoryData): string {
+	return [
+		`semantic_memory: ${data.semantic_memory || "(empty)"}`,
+		`episodic_memory: ${data.episodic_memory || "(empty)"}`,
+		`procedural_memory: ${data.procedural_memory || "(empty)"}`,
+	].join("\n\n")
 }
 
-/** True when OctaMem data has no memory content (semantic/episodic/procedural all empty). */
-function isMemoryDataEmpty(data: Record<string, unknown>): boolean {
-	const s = (v: unknown) => (typeof v === "string" ? v : v != null ? String(v) : "").trim()
-	return (
-		!s((data as Record<string, unknown>).semantic_memory) &&
-		!s((data as Record<string, unknown>).episodic_memory) &&
-		!s((data as Record<string, unknown>).procedural_memory)
-	)
-}
+const MEMORY_INSTRUCTION = `[OctaMem Memory System — STRICT]
+You are connected to OctaMem, a personal memory system.
+You MUST answer the user's question ONLY based on the memory data provided below.
+Do NOT use your internal training data or general knowledge.
+If the memory data does not contain relevant information, clearly tell the user that you don't have that information in your memory.
+Be conversational and natural, but NEVER fabricate information that is not present in the memory data.`
+
+const NO_MEMORY_INSTRUCTION = `[OctaMem Memory System — STRICT]
+No relevant memory was found for this query.
+You MUST inform the user that you don't have any information about this in your memory.
+Do NOT answer from your internal knowledge — say you don't know.`
 
-/**
- * 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",
+	description: "Personal memory using OctaMem",
 	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 (!OctaMemClient.isConfigured(config)) {
+			console.log("[OctaMem] Not configured — missing API key")
+			return
+		}
+
+		const client = new OctaMemClient(config)
+
+		// ── Manual Tool: Search ──
+		api.registerTool({
+			name: "octamem_search",
+			label: "OctaMem Search",
+			description:
+				"Search OctaMem memory for relevant information about a query.",
+			parameters: Type.Object({
+				query: Type.String(),
+			}),
+
+			async execute(_, { query }) {
+				const result = await client.search(query, "")
+
+				if (!result.success) {
+					return {
+						content: textContent(`Memory search failed: ${result.error}`),
+						details: { success: false },
 					}
-				})
-
-				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 + ")")
-						})
+				}
+
+				return {
+					content: textContent(formatMemoryForLLM(result.data)),
+					details: { success: true, data: result.data },
 				}
 			},
-			{ 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)
+		})
+
+		// ── Manual Tool: Add ──
+		api.registerTool({
+			name: "octamem_add",
+			label: "OctaMem Add",
+			description: "Store information into OctaMem memory.",
+			parameters: Type.Object({
+				content: Type.String(),
+			}),
+
+			async execute(_, { content }) {
+				const result = await client.add(content, "")
+
+				if (!result.success) {
 					return {
-						content: textContent(text),
-						details: { memoryType: "personal", data: raw },
+						content: textContent(`Failed to store: ${result.message}`),
+						details: { success: false },
 					}
-				},
+				}
+
+				return {
+					content: textContent("Stored successfully"),
+					details: { success: true },
+				}
 			},
-			{ 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
+		})
+
+		// ── Auto Search: runs before the LLM sees the user's message ──
+		api.on("before_prompt_build", async (event) => {
+			try {
+				const prompt = stripOpenClawWrapper(event.prompt ?? "")
+				if (shouldSkip(prompt)) return
+
+				const messages = event.messages ?? []
+				const previousContext = buildPreviousContext(messages, false)
+
+				const result = await client.search(prompt, previousContext)
+
+				if (!result.success) return
+
+				if (hasMemory(result.data)) {
+					const memory = formatMemoryForLLM(result.data)
 					return {
-						content: textContent(`Stored to personal memory: "${preview}"`),
-						details: { id: result.id, memoryType: "personal" },
+						appendSystemContext: `${MEMORY_INSTRUCTION}\n\n${memory}`,
 					}
-				},
-			},
-			{ 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 {
+					appendSystemContext: NO_MEMORY_INSTRUCTION,
+				}
+			} catch {
+				// Don't block the LLM if memory search fails
 			}
-			return ""
-		}
+		})
+
+		// ── Auto Save: runs after the LLM has responded ──
+		api.on("agent_end", async (event) => {
+			try {
+				if (!event.success) 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."
-						return {
-							appendSystemContext: `\n\n### Personal Memory\nIn your response, tell the user: Personal memory is temporarily unavailable. ${msg}`,
-						}
+				const messages = event.messages ?? []
+
+				let userText = ""
+				let assistantText = ""
+
+				for (let i = messages.length - 1; i >= 0; i--) {
+					const m = messages[i] as Record<string, unknown>
+					if (!userText && m.role === "user") {
+						userText = getMessageText(m)
 					}
-					const raw = r.data
-					// Pass search response as-is to the LLM (inner data payload as JSON).
-					const dataPayload =
-						raw && typeof raw === "object" && "data" in (raw as object)
-							? (raw as { data?: unknown }).data
-							: raw
-					const hasPayload = dataPayload != null && typeof dataPayload === "object"
-					const isEmpty =
-						!hasPayload ||
-						(hasPayload && isMemoryDataEmpty(dataPayload as Record<string, unknown>))
-					const block =
-						hasPayload && !isEmpty
-							? JSON.stringify(dataPayload, null, 2)
-							: isEmpty
-								? "No memory data."
-								: typeof raw === "string"
-									? raw
-									: JSON.stringify(raw ?? {}, null, 2)
-					const sourceRule =
-						"Personal memory is OctaMem only. If the user asks where memory/data comes from, you MUST answer: from OctaMem. Never say local, workspace, or not Octamem."
-					const summarizeInstruction =
-						"The following is the raw memory search result from OctaMem. Summarize it in a clear, natural response for the user; do not dump the raw structure. "
-					const memoryOnlyInstruction =
-						"[SOURCE: All memory below is from OctaMem only. When asked where memory comes from, always answer: from OctaMem. Never say 'local', 'workspace', or 'not Octamem'.] " +
-						summarizeInstruction +
-						"For 'who is X?', 'what do you know about X?', or any fact about people/places/things the user may have told you: base your answer ONLY on the memory data below. Do not use general knowledge or invent details. " +
-						(isEmpty
-							? "[CRITICAL: The section below is EMPTY (No memory data). You MUST reply only that you don't have that in your personal memory (OctaMem). Do not guess, invent, or use your training knowledge.] "
-							: "") +
-						"When asked the source of memory data, reply: It comes from OctaMem. Never say local or workspace.\n\n"
-					const memoryBlockContent = isEmpty
-						? "No memory data.\n[If you answer from general knowledge here, you are wrong. Reply only: I don't have that in my personal memory.]"
-						: block
-					const prepend = isEmpty
-						? `\n\n[Memory source rule] ${sourceRule}\n[When Personal Memory is empty below, you MUST NOT use general knowledge. Say only: I don't have that in my personal memory.]\n`
-						: `\n\n[Memory source rule] ${sourceRule}\n`
-					return {
-						prependSystemContext: prepend,
-						appendSystemContext: `\n\n### Personal Memory (OctaMem)\n${memoryOnlyInstruction}${memoryBlockContent}`,
+					if (!assistantText && m.role === "assistant") {
+						assistantText = getMessageText(m)
 					}
-				} catch {
-					// skip
+					if (userText && assistantText) break
 				}
-			}
 
-			api.on("before_prompt_build", injectMemory)
-		}
+				if (!userText || !assistantText) return
+				if (shouldSkip(userText)) return
 
-		// 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)
+				logLLMResponse(assistantText)
+
+				const content = `user: ${userText} | assistant: ${assistantText}`
+				const previousContext = buildPreviousContext(messages, true)
+
+				await client.add(content, previousContext)
 			} catch {
-				// skip
+				// Don't crash if memory save fails
 			}
 		})
 
-		api.registerService({ id: "octamem-openclaw", start: () => {}, stop: () => {} })
+		api.registerService({
+			id: "octamem-openclaw",
+			start: () => {},
+			stop: () => {},
+		})
 	},
 }

package/src/logger.ts

@@ -1,10 +1,9 @@
 import fs from "node:fs"
-import path from "node:path"
 import os from "node:os"
+import path from "node:path"
 
 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) {
@@ -13,11 +12,11 @@ function redactPayload(obj: Record<string, unknown>): Record<string, unknown> {
 	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 {
+/** Log an outgoing API request (endpoint + payload). */
+export function logRequest(
+	endpoint: string,
+	payload: Record<string, unknown>,
+): void {
 	try {
 		const ts = new Date().toISOString()
 		const safe = redactPayload(payload)
@@ -29,16 +28,11 @@ export function logRequest(endpoint: string, payload: Record<string, unknown>):
 	}
 }
 
-/**
- * Appends the API response to ~/.openclaw/octamem-api.log (same file as request log).
- */
-export function logResponse(endpoint: string, response: unknown): void {
+/** Log the LLM's response shown to the user. */
+export function logLLMResponse(assistantText: string): 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`
+		const block = `--- ${ts} llm-response ---\n${assistantText}\n`
 		fs.appendFileSync(LOG_PATH, block)
 	} catch {
 		// ignore log errors

package/src/openclaw-config.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs"
-import path from "node:path"
 import os from "node:os"
+import path from "node:path"
 
 const CONFIG_DIR = ".openclaw"
 const CONFIG_FILES = ["openclaw.json", "config.json"]
@@ -32,7 +32,9 @@ export function resolveOpenClawConfigPath(): string {
 /**
  * Reads and parses the OpenClaw config file. Returns empty object if missing or invalid.
  */
-export function readOpenClawConfig(configPath: string): Record<string, unknown> {
+export function readOpenClawConfig(
+	configPath: string,
+): Record<string, unknown> {
 	try {
 		const raw = fs.readFileSync(configPath, "utf-8")
 		const data = JSON.parse(raw)
@@ -52,27 +54,47 @@ export function writeOctaMemPluginConfig(
 	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>
+	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>
+	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>) }
-		: {}
+	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 }),
+			...(options.toolDescription !== undefined && {
+				toolDescription: options.toolDescription,
+			}),
+			...(options.addToolDescription !== undefined && {
+				addToolDescription: options.addToolDescription,
+			}),
 		},
 	}
 	plugins.entries = entries
@@ -80,10 +102,12 @@ export function writeOctaMemPluginConfig(
 
 	// So only OctaMem is used for memory: disable core memory tools (file-based).
 	const coreMemoryToolsToDeny = ["memory_search", "memory_get"]
-	const tools = (data.tools && typeof data.tools === "object"
-		? { ...(data.tools as Record<string, unknown>) }
-		: {}) as Record<string, unknown>
-	let deny = Array.isArray(tools.deny) ? [...(tools.deny as string[])] : []
+	const tools = (
+		data.tools && typeof data.tools === "object"
+			? { ...(data.tools as Record<string, unknown>) }
+			: {}
+	) as Record<string, unknown>
+	const deny = Array.isArray(tools.deny) ? [...(tools.deny as string[])] : []
 	for (const id of coreMemoryToolsToDeny) {
 		if (!deny.includes(id)) deny.push(id)
 	}

package/src/types.ts

@@ -1,35 +1,21 @@
-/**
- * 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
+	memories: { personal?: { apiKey: 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
+export type MemoryData = {
+	semantic_memory: string
+	episodic_memory: string
+	procedural_memory: string
 }
 
-/** Result of an add (store) request; message holds success or error text. */
-export type AddResult = {
-	success: boolean
-	id: string
-	message: string
-}
+export type SearchResult =
+	| { success: true; data: MemoryData; query: string }
+	| { success: false; error: string; query: string }
 
-/** Last user question and assistant reply; used when auto-saving a Q&A pair. */
-export type LastQa = { query: string; response: string }
+export type AddResult =
+	| { success: true; message: string }
+	| { success: false; message: string }