interface PluginLogger {
debug?: (message: string) => void;
info: (message: string) => void;
warn: (message: string) => void;
error: (message: string) => void;
}
interface PluginServiceContext {
config: Record<string, unknown>;
workspaceDir?: string;
stateDir: string;
logger: PluginLogger;
}
interface PluginCommandContext {
senderId?: string;
channel: string;
isAuthorizedSender: boolean;
args?: string;
commandBody: string;
config: Record<string, unknown>;
}
type PluginCommandResult = string | { text: string } | { text: string; format?: string };
interface BeforeAgentStartEvent {
prompt?: string;
}
interface BeforePromptBuildEvent {
prompt: string;
/** The user's request before history projection; newer hosts only. An empty string means no textual request. */
currentUserMessage?: string;
/** Stable across rebuilds and retries of one admitted request; newer hosts only. */
currentUserMessageId?: string;
messages: unknown[];
}
interface BeforePromptBuildResult {
systemPrompt?: string;
prependContext?: string;
prependSystemContext?: string;
appendSystemContext?: string;
}
// OpenClaw's PluginHookAfterToolCallEvent. A failed call reports its message in
// `error`. `params` is required upstream, but a host build that omits it must
// not throw here.
interface AfterToolCallEvent {
toolName: string;
params?: Record<string, unknown>;
toolCallId?: string;
result?: unknown;
error?: string;
}
function stripPrivateSpans(text: string): string {
const tags = /<private(?=[\s>]|$)[^>]*(?:>|$)|<\/private\s*>/gi;
let depth = 0;
let cursor = 0;
let result = "";
for (const match of text.matchAll(tags)) {
if (match[0].startsWith("</")) {
if (depth > 0 && --depth === 0) cursor = match.index! + match[0].length;
} else {
if (depth === 0) result += text.slice(cursor, match.index);
depth++;
}
}
return result + (depth === 0 ? text.slice(cursor) : "");
}
const CAPTURE_TOOL_NAMES = new Map([
["read", "Read"],
["write", "Write"],
["edit", "Edit"],
]);
interface AgentEndEvent {
messages?: Array<{
role: string;
content: string | Array<{ type: string; text?: string }>;
}>;
}
interface SessionStartEvent {
sessionId: string;
resumedFrom?: string;
}
interface AfterCompactionEvent {
messageCount: number;
tokenCount?: number;
compactedCount: number;
}
interface SessionEndEvent {
sessionId: string;
messageCount: number;
durationMs?: number;
}
interface MessageReceivedEvent {
from: string;
content: string;
timestamp?: number;
metadata?: Record<string, unknown>;
}
interface EventContext {
sessionKey?: string;
workspaceDir?: string;
agentId?: string;
}
interface MessageContext {
channelId: string;
accountId?: string;
conversationId?: string;
}
type EventCallback<T> = (event: T, ctx: EventContext) => void | Promise<void>;
type PromptBuildCallback = (event: BeforePromptBuildEvent, ctx: EventContext) => BeforePromptBuildResult | Promise<BeforePromptBuildResult | void> | void;
type MessageEventCallback<T> = (event: T, ctx: MessageContext) => void | Promise<void>;
interface OpenClawPluginApi {
id: string;
name: string;
version?: string;
source: string;
config: Record<string, unknown>;
pluginConfig?: Record<string, unknown>;
logger: PluginLogger;
registerService: (service: {
id: string;
start: (ctx: PluginServiceContext) => void | Promise<void>;
stop?: (ctx: PluginServiceContext) => void | Promise<void>;
}) => void;
registerCommand: (command: {
name: string;
description: string;
acceptsArgs?: boolean;
requireAuth?: boolean;
handler: (ctx: PluginCommandContext) => PluginCommandResult | Promise<PluginCommandResult>;
}) => void;
on: ((event: "before_prompt_build", callback: PromptBuildCallback) => void) &
((event: "before_agent_start", callback: EventCallback<BeforeAgentStartEvent>) => void) &
((event: "after_tool_call", callback: EventCallback<AfterToolCallEvent>) => void) &
((event: "agent_end", callback: EventCallback<AgentEndEvent>) => void) &
((event: "session_start", callback: EventCallback<SessionStartEvent>) => void) &
((event: "session_end", callback: EventCallback<SessionEndEvent>) => void) &
((event: "message_received", callback: MessageEventCallback<MessageReceivedEvent>) => void) &
((event: "after_compaction", callback: EventCallback<AfterCompactionEvent>) => void) &
((event: "gateway_start", callback: EventCallback<Record<string, never>>) => void);
runtime: {
/** The OpenClaw host version, e.g. "2026.11.2". */
version?: string;
channel: Record<string, Record<string, (...args: any[]) => Promise<any>>>;
};
}
// OpenClaw's validated hook set has before_agent_start through 2026.7.35 and
// drops it from 2026.8.1-beta.1 on, where registering it only produces an
// "unknown typed hook" warning. While a host has it, it carries the raw user
// prompt; before_prompt_build's `prompt` there may include rebuilt history.
const FIRST_OPENCLAW_VERSION_WITHOUT_BEFORE_AGENT_START = [2026, 8, 1] as const;
/** null when the host's version is unreadable (OpenClaw 2026.2.9 reports "unknown"). */
function openClawHostHasBeforeAgentStart(hostVersion: string | undefined): boolean | null {
const match = /^(\d+)\.(\d+)\.(\d+)/.exec(hostVersion ?? "");
if (!match) return null;
const hostParts = match.slice(1, 4).map(Number);
for (let i = 0; i < hostParts.length; i++) {
const boundary = FIRST_OPENCLAW_VERSION_WITHOUT_BEFORE_AGENT_START[i];
if (hostParts[i] !== boundary) return hostParts[i] < boundary;
}
return false;
}
// The worker refuses a native prompt ID longer than 256 characters or one that
// contains whitespace or control characters (SessionStore.saveNativeUserPrompt).
const WORKER_ACCEPTED_NATIVE_PROMPT_ID = /^[^\s\x00-\x1f\x7f]{1,256}$/;
interface ObservationSSEPayload {
id: number;
memory_session_id: string;
session_id: string;
type: string;
title: string | null;
subtitle: string | null;
text: string | null;
narrative: string | null;
facts: string | null;
concepts: string | null;
files_read: string | null;
files_modified: string | null;
project: string | null;
prompt_number: number;
created_at_epoch: number;
}
interface SSENewObservationEvent {
type: "new_observation";
observation: ObservationSSEPayload;
timestamp: number;
}
type ConnectionState = "disconnected" | "connected" | "reconnecting";
const DETAILED_FEED_TYPES = new Set(["security_alert", "security_note", "sensitive", "bugfix", "decision"]);
const COMPACT_FEED_MAX_CHARS = 900;
const DETAILED_FEED_MAX_CHARS = 2200;
const DETAILED_FACT_LIMIT = 5;
interface FeedEmojiConfig {
primary?: string;
claudeCode?: string;
claudeCodeLabel?: string;
default?: string;
agents?: Record<string, string>;
}
interface ClaudeMemPluginConfig {
syncMemoryFile?: boolean;
syncMemoryFileExclude?: string[];
project?: string;
workerPort?: number;
workerHost?: string;
observationFeed?: {
enabled?: boolean;
channel?: string;
to?: string;
botToken?: string;
emojis?: FeedEmojiConfig;
};
}
const MAX_SSE_BUFFER_SIZE = 1024 * 1024;
const DEFAULT_WORKER_PORT = 37777;
const DEFAULT_WORKER_HOST = "127.0.0.1";
// Stamped on every session post so OpenClaw memory is not stored as Claude Code's.
const PLATFORM_SOURCE = "openclaw";
const EMOJI_POOL = [
"๐ง","๐","๐","๐ป","๐งช","๐","๐ก๏ธ","โ๏ธ","๐ฆ","๐ฏ",
"๐ฎ","โก","๐","๐จ","๐","๐","๐ฌ","๐๏ธ","๐","๐ญ",
];
function poolEmojiForAgent(agentId: string): string {
let hash = 0;
for (let i = 0; i < agentId.length; i++) {
hash = ((hash << 5) - hash + agentId.charCodeAt(i)) | 0;
}
return EMOJI_POOL[Math.abs(hash) % EMOJI_POOL.length];
}
const DEFAULT_PRIMARY_EMOJI = "๐ฆ";
const DEFAULT_CLAUDE_CODE_EMOJI = "โจ๏ธ";
const DEFAULT_CLAUDE_CODE_LABEL = "Claude Code Session";
const DEFAULT_FALLBACK_EMOJI = "๐ฆ";
function buildGetSourceLabel(
emojiConfig: FeedEmojiConfig | undefined
): (project: string | null | undefined) => string {
const primary = emojiConfig?.primary ?? DEFAULT_PRIMARY_EMOJI;
const claudeCode = emojiConfig?.claudeCode ?? DEFAULT_CLAUDE_CODE_EMOJI;
const claudeCodeLabel = emojiConfig?.claudeCodeLabel ?? DEFAULT_CLAUDE_CODE_LABEL;
const fallback = emojiConfig?.default ?? DEFAULT_FALLBACK_EMOJI;
const pinnedAgents = emojiConfig?.agents ?? {};
return function getSourceLabel(project: string | null | undefined): string {
if (!project) return fallback;
if (project.startsWith("openclaw-")) {
const agentId = project.slice("openclaw-".length);
if (!agentId) return `${primary} openclaw`;
const emoji = pinnedAgents[agentId] || poolEmojiForAgent(agentId);
return `${emoji} ${agentId}`;
}
if (project === "openclaw") {
return `${primary} openclaw`;
}
const trimmedLabel = claudeCodeLabel.trim();
if (!trimmedLabel) {
return `${claudeCode} ${project}`;
}
return `${claudeCode} ${trimmedLabel} (${project})`;
};
}
let _workerHost = DEFAULT_WORKER_HOST;
function workerBaseUrl(port: number): string {
const host = _workerHost.includes(":") && !_workerHost.startsWith("[")
? `[${_workerHost}]` : _workerHost;
return `http://${host}:${port}`;
}
const CIRCUIT_BREAKER_THRESHOLD = 3;
const CIRCUIT_BREAKER_COOLDOWN_MS = 30_000;
// Covers both response headers and body reads; optional memory must not leave
// an OpenClaw hook waiting indefinitely on an unresponsive worker. 5 s is the
// bound the Hermes plugin, the other in-process host, already uses for the same
// worker endpoints (WRITE_TIMEOUT_S in hermes/claude-mem/client.py; its context
// reads use READ_TIMEOUT_S = 3 s), so context injection fits inside it too.
const WORKER_REQUEST_TIMEOUT_MS = 5_000;
type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
let _circuitState: CircuitState = "CLOSED";
let _circuitFailures = 0;
let _circuitOpenedAt = 0;
let _halfOpenProbeInFlight = false;
function circuitAllow(logger: PluginLogger): boolean {
if (_circuitState === "CLOSED") return true;
if (_circuitState === "OPEN") {
if (Date.now() - _circuitOpenedAt >= CIRCUIT_BREAKER_COOLDOWN_MS) {
_circuitState = "HALF_OPEN";
logger.info("[claude-mem] Circuit breaker: probing worker connection");
if (_halfOpenProbeInFlight) return false;
_halfOpenProbeInFlight = true;
return true;
}
return false;
}
if (_halfOpenProbeInFlight) return false;
_halfOpenProbeInFlight = true;
return true;
}
function circuitOnSuccess(logger: PluginLogger): void {
if (_circuitState !== "CLOSED") {
logger.info("[claude-mem] Worker connection restored โ circuit closed");
}
_circuitState = "CLOSED";
_circuitFailures = 0;
_halfOpenProbeInFlight = false;
}
function circuitOnFailure(logger: PluginLogger): void {
_halfOpenProbeInFlight = false;
_circuitFailures++;
if (
_circuitState === "HALF_OPEN" ||
(_circuitState === "CLOSED" && _circuitFailures >= CIRCUIT_BREAKER_THRESHOLD)
) {
_circuitState = "OPEN";
_circuitOpenedAt = Date.now();
logger.warn(
`[claude-mem] Worker unreachable โ disabling requests for ${CIRCUIT_BREAKER_COOLDOWN_MS / 1000}s`
);
}
}
function circuitReset(): void {
_circuitState = "CLOSED";
_circuitFailures = 0;
_circuitOpenedAt = 0;
_halfOpenProbeInFlight = false;
}
async function workerPost(
port: number,
path: string,
body: Record<string, unknown>,
logger: PluginLogger
): Promise<Record<string, unknown> | null> {
if (!circuitAllow(logger)) return null;
try {
const response = await fetch(`${workerBaseUrl(port)}${path}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal: AbortSignal.timeout(WORKER_REQUEST_TIMEOUT_MS),
});
if (!response.ok) {
await response.body?.cancel();
circuitOnFailure(logger);
logger.warn(`[claude-mem] Worker POST ${path} returned ${response.status}`);
return null;
}
const result = (await response.json()) as Record<string, unknown>;
circuitOnSuccess(logger);
return result;
} catch (error: unknown) {
const message = error instanceof Error ? error.message : String(error);
circuitOnFailure(logger);
if (_circuitState !== "OPEN") {
logger.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
}
return null;
}
}
function workerPostFireAndForget(
port: number,
path: string,
body: Record<string, unknown>,
logger: PluginLogger
): void {
if (!circuitAllow(logger)) return;
fetch(`${workerBaseUrl(port)}${path}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(body),
signal: AbortSignal.timeout(WORKER_REQUEST_TIMEOUT_MS),
}).then(async (response) => {
// This caller needs only the status, so release the unused response body.
await response.body?.cancel();
if (!response.ok) {
circuitOnFailure(logger);
logger.warn(`[claude-mem] Worker POST ${path} returned ${response.status}`);
return;
}
circuitOnSuccess(logger);
}).catch((error: unknown) => {
const message = error instanceof Error ? error.message : String(error);
circuitOnFailure(logger);
if (_circuitState !== "OPEN") {
logger.warn(`[claude-mem] Worker POST ${path} failed: ${message}`);
}
});
}
async function workerGetText(
port: number,
path: string,
logger: PluginLogger
): Promise<string | null> {
if (!circuitAllow(logger)) return null;
try {
const response = await fetch(`${workerBaseUrl(port)}${path}`, {
signal: AbortSignal.timeout(WORKER_REQUEST_TIMEOUT_MS),
});
if (!response.ok) {
await response.body?.cancel();
circuitOnFailure(logger);
logger.warn(`[claude-mem] Worker GET ${path} returned ${response.status}`);
return null;
}
const text = await response.text();
circuitOnSuccess(logger);
return text;
} catch (error: unknown) {
const message = error instanceof Error ? error.message : String(error);
circuitOnFailure(logger);
if (_circuitState !== "OPEN") {
logger.warn(`[claude-mem] Worker GET ${path} failed: ${message}`);
}
return null;
}
}
async function workerGetJson(
port: number,
path: string,
logger: PluginLogger
): Promise<Record<string, unknown> | null> {
const text = await workerGetText(port, path, logger);
if (!text) return null;
try {
return JSON.parse(text) as Record<string, unknown>;
} catch {
logger.warn(`[claude-mem] Worker GET ${path} returned non-JSON response`);
return null;
}
}
function formatObservationMessage(
observation: ObservationSSEPayload,
getSourceLabel: (project: string | null | undefined) => string,
): string {
const title = observation.title || "Untitled";
const source = getSourceLabel(observation.project);
const isDetailed = DETAILED_FEED_TYPES.has(observation.type);
const parts = [`${source}\n**${title}**`];
if (observation.subtitle) {
parts.push(truncateText(observation.subtitle, isDetailed ? 500 : 260));
}
if (!isDetailed) {
return truncateText(parts.join("\n"), COMPACT_FEED_MAX_CHARS);
}
if (observation.narrative) {
parts.push(`Narrative\n${truncateText(observation.narrative, 900)}`);
}
const facts = parseStringArray(observation.facts).slice(0, DETAILED_FACT_LIMIT);
if (facts.length > 0) {
parts.push(`Facts\n${facts.map((fact) => `- ${truncateText(fact, 320)}`).join("\n")}`);
}
const concepts = parseStringArray(observation.concepts).slice(0, 8);
if (concepts.length > 0) {
parts.push(`Concepts: ${concepts.join(", ")}`);
}
return truncateText(parts.join("\n\n"), DETAILED_FEED_MAX_CHARS);
}
function truncateText(value: string, maxChars: number): string {
if (value.length <= maxChars) return value;
const hardLimit = Math.max(0, maxChars - 3);
const truncated = value.slice(0, hardLimit);
const lastWhitespace = truncated.search(/\s+\S*$/);
const boundary = lastWhitespace > Math.floor(hardLimit * 0.65) ? lastWhitespace : hardLimit;
return `${truncated.slice(0, boundary).trimEnd()}...`;
}
function parseStringArray(value: string | null | undefined): string[] {
if (!value) return [];
try {
const parsed = JSON.parse(value);
return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === "string") : [];
} catch {
return [];
}
}
const CHANNEL_SEND_MAP: Record<string, { namespace: string; functionName: string }> = {
telegram: { namespace: "telegram", functionName: "sendMessageTelegram" },
whatsapp: { namespace: "whatsapp", functionName: "sendMessageWhatsApp" },
discord: { namespace: "discord", functionName: "sendMessageDiscord" },
slack: { namespace: "slack", functionName: "sendMessageSlack" },
signal: { namespace: "signal", functionName: "sendMessageSignal" },
imessage: { namespace: "imessage", functionName: "sendMessageIMessage" },
line: { namespace: "line", functionName: "sendMessageLine" },
};
async function sendDirectTelegram(
botToken: string,
chatId: string,
text: string,
logger: PluginLogger
): Promise<void> {
try {
const response = await fetch(`https://api.telegram.org/bot${botToken}/sendMessage`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
chat_id: chatId,
text,
parse_mode: "Markdown",
}),
});
if (!response.ok) {
const body = await response.text();
logger.warn(`[claude-mem] Direct Telegram send failed (${response.status}): ${body}`);
}
} catch (error: unknown) {
const message = error instanceof Error ? error.message : String(error);
logger.warn(`[claude-mem] Direct Telegram send error: ${message}`);
}
}
function sendToChannel(
api: OpenClawPluginApi,
channel: string,
to: string,
text: string,
botToken?: string
): Promise<void> {
if (botToken && channel === "telegram") {
return sendDirectTelegram(botToken, to, text, api.logger);
}
const mapping = CHANNEL_SEND_MAP[channel];
if (!mapping) {
api.logger.warn(`[claude-mem] Unsupported channel type: ${channel}`);
return Promise.resolve();
}
const channelApi = api.runtime.channel[mapping.namespace];
if (!channelApi) {
api.logger.warn(`[claude-mem] Channel "${channel}" not available in runtime`);
return Promise.resolve();
}
const senderFunction = channelApi[mapping.functionName];
if (!senderFunction) {
api.logger.warn(`[claude-mem] Channel "${channel}" has no ${mapping.functionName} function`);
return Promise.resolve();
}
const args: unknown[] = channel === "whatsapp"
? [to, text, { verbose: false }]
: [to, text];
return senderFunction(...args).catch((error: unknown) => {
const message = error instanceof Error ? error.message : String(error);
api.logger.error(`[claude-mem] Failed to send to ${channel}: ${message}`);
});
}
async function connectToSSEStream(
api: OpenClawPluginApi,
port: number,
channel: string,
to: string,
abortController: AbortController,
setConnectionState: (state: ConnectionState) => void,
getSourceLabel: (project: string | null | undefined) => string,
botToken?: string
): Promise<void> {
let backoffMs = 1000;
const maxBackoffMs = 30000;
while (!abortController.signal.aborted) {
try {
setConnectionState("reconnecting");
api.logger.info(`[claude-mem] Connecting to SSE stream at ${workerBaseUrl(port)}/stream`);
const response = await fetch(`${workerBaseUrl(port)}/stream`, {
signal: abortController.signal,
headers: { Accept: "text/event-stream" },
});
if (!response.ok) {
throw new Error(`SSE stream returned HTTP ${response.status}`);
}
if (!response.body) {
throw new Error("SSE stream response has no body");
}
setConnectionState("connected");
backoffMs = 1000;
api.logger.info("[claude-mem] Connected to SSE stream");
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
if (buffer.length > MAX_SSE_BUFFER_SIZE) {
api.logger.warn("[claude-mem] SSE buffer overflow, clearing buffer");
buffer = "";
}
const frames = buffer.split("\n\n");
buffer = frames.pop() || "";
for (const frame of frames) {
const dataLines = frame
.split("\n")
.filter((line) => line.startsWith("data:"))
.map((line) => line.slice(5).trim());
if (dataLines.length === 0) continue;
const jsonStr = dataLines.join("\n");
if (!jsonStr) continue;
try {
const parsed = JSON.parse(jsonStr);
if (parsed.type === "new_observation" && parsed.observation) {
const event = parsed as SSENewObservationEvent;
const message = formatObservationMessage(event.observation, getSourceLabel);
await sendToChannel(api, channel, to, message, botToken);
}
} catch (parseError: unknown) {
const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
api.logger.warn(`[claude-mem] Failed to parse SSE frame: ${errorMessage}`);
}
}
}
} catch (error: unknown) {
if (abortController.signal.aborted) {
break;
}
setConnectionState("reconnecting");
const errorMessage = error instanceof Error ? error.message : String(error);
api.logger.warn(`[claude-mem] SSE stream error: ${errorMessage}. Reconnecting in ${backoffMs / 1000}s`);
}
if (abortController.signal.aborted) break;
await new Promise((resolve) => setTimeout(resolve, backoffMs));
backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
}
setConnectionState("disconnected");
}
export default function claudeMemPlugin(api: OpenClawPluginApi): void {
const userConfig = (api.pluginConfig || {}) as ClaudeMemPluginConfig;
const workerPort = userConfig.workerPort || DEFAULT_WORKER_PORT;
_workerHost = userConfig.workerHost || DEFAULT_WORKER_HOST;
const baseProjectName = userConfig.project || "openclaw";
const getSourceLabel = buildGetSourceLabel(userConfig.observationFeed?.emojis);
function getProjectName(ctx: EventContext): string {
if (ctx.agentId) {
return `openclaw-${ctx.agentId}`;
}
return baseProjectName;
}
const sessionIds = new Map<string, string>();
const canonicalSessionKeys = new Map<string, string>();
const sessionAliasesByCanonicalKey = new Map<string, Set<string>>();
const recentPromptInits = new Map<string, number>();
const syncMemoryFile = userConfig.syncMemoryFile !== false;
const syncMemoryFileExclude = new Set(userConfig.syncMemoryFileExclude || []);
function getContentSessionId(sessionKey?: string): string {
const key = sessionKey || "default";
if (!sessionIds.has(key)) {
sessionIds.set(key, `openclaw-${key}-${Date.now()}`);
}
return sessionIds.get(key)!;
}
function shouldInjectContext(ctx?: EventContext): boolean {
if (!syncMemoryFile) return false;
const agentId = ctx?.agentId;
if (agentId && syncMemoryFileExclude.has(agentId)) return false;
return true;
}
type SessionTrackingContext = {
sessionKey?: string;
workspaceDir?: string;
channelId?: string;
conversationId?: string;
};
function getSessionAliases(ctx: SessionTrackingContext): string[] {
const aliases = new Set<string>();
for (const rawKey of [ctx.sessionKey, ctx.conversationId, ctx.channelId]) {
const key = typeof rawKey === "string" ? rawKey.trim() : "";
if (key) aliases.add(key);
}
if (aliases.size === 0) aliases.add("default");
return Array.from(aliases);
}
function rememberSessionContext(ctx: SessionTrackingContext): { canonicalKey: string; contentSessionId: string } {
const aliases = getSessionAliases(ctx);
let canonicalKey = aliases.find((alias) => canonicalSessionKeys.has(alias));
canonicalKey = canonicalKey ? canonicalSessionKeys.get(canonicalKey)! : aliases[0];
let aliasSet = sessionAliasesByCanonicalKey.get(canonicalKey);
if (!aliasSet) {
aliasSet = new Set([canonicalKey]);
sessionAliasesByCanonicalKey.set(canonicalKey, aliasSet);
}
for (const alias of aliases) {
aliasSet.add(alias);
canonicalSessionKeys.set(alias, canonicalKey);
}
const contentSessionId = getContentSessionId(canonicalKey);
for (const alias of aliasSet) {
sessionIds.set(alias, contentSessionId);
}
return { canonicalKey, contentSessionId };
}
function shouldSkipDuplicatePromptInit(contentSessionId: string, project: string, prompt: string): boolean {
const now = Date.now();
for (const [key, timestamp] of recentPromptInits) {
if (now - timestamp > 2000) recentPromptInits.delete(key);
}
const cacheKey = `${contentSessionId}::${project}::${prompt}`;
const lastSeenAt = recentPromptInits.get(cacheKey);
recentPromptInits.set(cacheKey, now);
return typeof lastSeenAt === "number" && now - lastSeenAt <= 2000;
}
function clearSessionContext(ctx: SessionTrackingContext): void {
const aliases = getSessionAliases(ctx);
const canonicalKey = aliases
.map((alias) => canonicalSessionKeys.get(alias))
.find(Boolean) || aliases[0];
const knownAliases = sessionAliasesByCanonicalKey.get(canonicalKey) || new Set([canonicalKey, ...aliases]);
for (const alias of knownAliases) {
canonicalSessionKeys.delete(alias);
sessionIds.delete(alias);
}
sessionAliasesByCanonicalKey.delete(canonicalKey);
sessionIds.delete(canonicalKey);
}
const CONTEXT_CACHE_TTL_MS = 60_000;
const contextCache = new Map<string, { text: string; fetchedAt: number }>();
async function getContextForPrompt(ctx?: EventContext): Promise<string | null> {
const projects = [baseProjectName];
const agentProject = ctx ? getProjectName(ctx) : null;
if (agentProject && agentProject !== baseProjectName) {
projects.push(agentProject);
}
const cacheKey = projects.join(",");
const cached = contextCache.get(cacheKey);
if (cached && Date.now() - cached.fetchedAt < CONTEXT_CACHE_TTL_MS) {
return cached.text;
}
const contextText = await workerGetText(
workerPort,
`/api/context/inject?projects=${encodeURIComponent(cacheKey)}`,
api.logger
);
if (contextText && contextText.trim().length > 0) {
const trimmed = contextText.trim();
contextCache.set(cacheKey, { text: trimmed, fetchedAt: Date.now() });
return trimmed;
}
return null;
}
// Centralized session-init POST. session_start, after_compaction, and the
// prompt hook (before_agent_start while the host has it, else before_prompt_build) each
// call this; the 2s dedup guard (shouldSkipDuplicatePromptInit) collapses the
// redundant inits a single user-message flow produces into one prompt record,
// while still ensuring a session is initialized even on flows that never
// reach the prompt hook. A native prompt ID lets the worker recognize a
// rebuilt or retried request as the prompt it already recorded.
async function initSessionOnce(ctx: EventContext, promptText: string, via: string, nativePromptId?: string): Promise<void> {
const { contentSessionId } = rememberSessionContext(ctx);
const projectName = getProjectName(ctx);
if (shouldSkipDuplicatePromptInit(contentSessionId, projectName, promptText)) {
api.logger.info(`[claude-mem] Skipping duplicate prompt init: contentSessionId=${contentSessionId} project=${projectName} via=${via}`);
return;
}
await workerPost(workerPort, "/api/sessions/init", {
contentSessionId,
project: projectName,
prompt: promptText,
platformSource: PLATFORM_SOURCE,
...(nativePromptId ? { nativePromptId } : {}),
}, api.logger);
api.logger.info(`[claude-mem] Session initialized via ${via}: contentSessionId=${contentSessionId} project=${projectName}`);
}
api.on("session_start", async (_event, ctx) => {
await initSessionOnce(ctx, "session start", "session_start");
});
api.on("message_received", async (event, ctx) => {
const { canonicalKey, contentSessionId } = rememberSessionContext(ctx);
api.logger.info(`[claude-mem] Message received โ prompt capture deferred to the agent prompt hook: session=${canonicalKey} contentSessionId=${contentSessionId} hasContent=${Boolean(event.content)}`);
});
api.on("after_compaction", async (_event, ctx) => {
await initSessionOnce(ctx, "after compaction", "after_compaction");
});
// Record each prompt from the cleanest source the host has: the raw prompt on
// before_agent_start while the host still has that hook (2026.2.9 through at
// least 2026.3.2 report their version as "unknown", and those all have it),
// otherwise the explicit request on before_prompt_build.
const hostHasBeforeAgentStart = openClawHostHasBeforeAgentStart(api.runtime?.version);
const recordPromptOnBeforeAgentStart = hostHasBeforeAgentStart !== false;
if (hostHasBeforeAgentStart === null) {
api.logger.info(`[claude-mem] OpenClaw host version "${api.runtime?.version ?? ""}" is unreadable; recording prompts on before_agent_start`);
}
if (recordPromptOnBeforeAgentStart) {
api.on("before_agent_start", async (event, ctx) => {
await initSessionOnce(ctx, event.prompt || "agent run", "before_agent_start");
});
}
api.on("before_prompt_build", async (event, ctx) => {
// A string currentUserMessage is the host's explicit request. Without text
// (image-only input or a continuation) there is no prompt to record, and
// OpenClaw says not to fall back to history. `prompt` may contain
// reconstructed history, so it is a prompt source only on a host that sends
// no currentUserMessage and has no before_agent_start.
const hasExplicitRequest = typeof event.currentUserMessage === "string";
const explicitRequestText = hasExplicitRequest ? event.currentUserMessage!.trim() : "";
const recordPrompt = hasExplicitRequest ? explicitRequestText.length > 0 : !recordPromptOnBeforeAgentStart;
const promptText = hasExplicitRequest ? event.currentUserMessage! : event.prompt || "agent run";
const nativePromptId = hasExplicitRequest && typeof event.currentUserMessageId === "string"
&& WORKER_ACCEPTED_NATIVE_PROMPT_ID.test(event.currentUserMessageId)
? event.currentUserMessageId
: undefined;
const [, contextText] = await Promise.all([
recordPrompt ? initSessionOnce(ctx, promptText, "before_prompt_build", nativePromptId) : Promise.resolve(),
shouldInjectContext(ctx) ? getContextForPrompt(ctx) : Promise.resolve(null),
]);
if (contextText) {
api.logger.info(`[claude-mem] Context injected via system prompt for agent=${ctx.agentId ?? "unknown"}`);
return { appendSystemContext: contextText };
}
});
api.on("after_tool_call", (event, ctx) => {
api.logger.info(`[claude-mem] after_tool_call fired: tool=${event.toolName ?? "unknown"} agent=${ctx.agentId ?? "none"} session=${ctx.sessionKey ?? "none"}`);
const toolName = event.toolName;
if (!toolName) return;
if (toolName.startsWith("memory_")) return;
const { canonicalKey, contentSessionId } = rememberSessionContext(ctx);
const failed = (typeof event.error === "string" && event.error.length > 0)
|| (event.result !== null && typeof event.result === "object"
&& (event.result as { isError?: unknown }).isError === true);
let toolResponseText = typeof event.result === "string" ? event.result : "";
const content = event.result && typeof event.result === "object"
? (event.result as { content?: Array<{ type: string; text?: string }> }).content
: undefined;
if (Array.isArray(content)) {
toolResponseText = content
.filter((block) => (block.type === "tool_result" || block.type === "text") && "text" in block)
.map((block) => String(block.text))
.join("\n");
}
// Ahead of any partial result, so the cap never cuts off why the call failed.
if (typeof event.error === "string" && event.error.length > 0) {
toolResponseText = [`Error: ${event.error}`, toolResponseText].filter(Boolean).join("\n");
}
toolResponseText = stripPrivateSpans(toolResponseText);
const MAX_TOOL_RESPONSE_LENGTH = 1000;
if (toolResponseText.length > MAX_TOOL_RESPONSE_LENGTH) {
toolResponseText = toolResponseText.slice(0, MAX_TOOL_RESPONSE_LENGTH);
}
// Fall back to the process cwd when the event carries no workspaceDir, so a
// missing ctx field never silently drops a captured observation.
const workspaceDir = ctx.workspaceDir || process.cwd();
if (!ctx.workspaceDir) {
api.logger.info(`[claude-mem] after_tool_call missing workspaceDir; using process.cwd(): session=${canonicalKey} tool=${toolName}`);
}
const params = event.params ?? {};
const toolInput = toolName === "read" && typeof params.path === "string"
&& !(typeof params.file_path === "string" && params.file_path.length > 0)
? { ...params, file_path: params.path }
: params;
workerPostFireAndForget(workerPort, "/api/sessions/observations", {
contentSessionId,
tool_name: CAPTURE_TOOL_NAMES.get(toolName) ?? toolName,
tool_input: toolInput,
// A failed file operation is evidence of an attempt, not a completed
// read/edit. Keep the shared worker's structured failure marker.
tool_response: failed ? { is_error: true, error: toolResponseText } : toolResponseText,
// The worker needs the native ID to retain and link the raw tool receipt.
...(typeof event.toolCallId === "string" && event.toolCallId ? { tool_use_id: event.toolCallId } : {}),
cwd: workspaceDir,
platformSource: PLATFORM_SOURCE,
}, api.logger);
});
api.on("agent_end", async (event, ctx) => {
const { contentSessionId } = rememberSessionContext(ctx);
let lastAssistantMessage = "";
if (Array.isArray(event.messages)) {
for (let i = event.messages.length - 1; i >= 0; i--) {
const message = event.messages[i];
if (message?.role === "assistant") {
if (typeof message.content === "string") {
lastAssistantMessage = message.content;
} else if (Array.isArray(message.content)) {
lastAssistantMessage = message.content
.filter((block) => block.type === "text")
.map((block) => block.text || "")
.join("\n");
}
break;
}
}
}
await workerPost(workerPort, "/api/sessions/summarize", {
contentSessionId,
last_assistant_message: lastAssistantMessage,
platformSource: PLATFORM_SOURCE,
}, api.logger);
});
api.on("session_end", async (_event, ctx) => {
clearSessionContext(ctx);
api.logger.info(`[claude-mem] Session tracking cleaned up`);
});
api.on("gateway_start", async () => {
circuitReset();
sessionIds.clear();
contextCache.clear();
recentPromptInits.clear();
canonicalSessionKeys.clear();
sessionAliasesByCanonicalKey.clear();
api.logger.info("[claude-mem] Gateway started โ session tracking reset");
});
let sseAbortController: AbortController | null = null;
let connectionState: ConnectionState = "disconnected";
let connectionPromise: Promise<void> | null = null;
api.registerService({
id: "claude-mem-observation-feed",
start: async (_ctx) => {
if (sseAbortController) {
sseAbortController.abort();
if (connectionPromise) {
await connectionPromise;
connectionPromise = null;
}
}
const feedConfig = userConfig.observationFeed;
if (!feedConfig?.enabled) {
api.logger.info("[claude-mem] Observation feed disabled");
return;
}
if (!feedConfig.channel || !feedConfig.to) {
api.logger.warn("[claude-mem] Observation feed misconfigured โ channel or target missing");
return;
}
api.logger.info(`[claude-mem] Observation feed starting โ channel: ${feedConfig.channel}, target: ${feedConfig.to}`);
sseAbortController = new AbortController();
connectionPromise = connectToSSEStream(
api,
workerPort,
feedConfig.channel,
feedConfig.to,
sseAbortController,
(state) => { connectionState = state; },
getSourceLabel,
feedConfig.botToken
);
},
stop: async (_ctx) => {
if (sseAbortController) {
sseAbortController.abort();
sseAbortController = null;
}
if (connectionPromise) {
await connectionPromise;
connectionPromise = null;
}
connectionState = "disconnected";
api.logger.info("[claude-mem] Observation feed stopped โ SSE connection closed");
},
});
// The worker's search, recent-context and timeline routes answer in the MCP
// tool shape ({ content: [{ type: "text", text }] }) with the rendered result.
function workerResultText(data: Record<string, unknown>): string {
const content = Array.isArray(data.content) ? data.content : [];
const text = content
.filter((block: any) => block?.type === "text" && typeof block.text === "string")
.map((block: any) => block.text)
.join("\n")
.trim();
return text || "No results found.";
}
function parseLimit(arg: string | undefined, fallback = 10): number {
const parsed = Number(arg);
if (!Number.isFinite(parsed)) return fallback;
return Math.max(1, Math.min(50, Math.trunc(parsed)));
}
api.registerCommand({
name: "claude_mem_feed",
description: "Show or toggle Claude-Mem observation feed status",
acceptsArgs: true,
handler: async (ctx) => {
const feedConfig = userConfig.observationFeed;
if (!feedConfig) {
return { text: "Observation feed not configured. Add observationFeed to your plugin config." };
}
const arg = ctx.args?.trim();
if (arg === "on") {
api.logger.info("[claude-mem] Feed enable requested via command");
return { text: "Feed enable requested. Update observationFeed.enabled in your plugin config to persist." };
}
if (arg === "off") {
api.logger.info("[claude-mem] Feed disable requested via command");
return { text: "Feed disable requested. Update observationFeed.enabled in your plugin config to persist." };
}
return { text: [
"Claude-Mem Observation Feed",
`Enabled: ${feedConfig.enabled ? "yes" : "no"}`,
`Channel: ${feedConfig.channel || "not set"}`,
`Target: ${feedConfig.to || "not set"}`,
`Connection: ${connectionState}`,
].join("\n") };
},
});
api.registerCommand({
name: "claude-mem-search",
description: "Search Claude-Mem observations by query",
acceptsArgs: true,
handler: async (ctx) => {
const raw = ctx.args?.trim() || "";
if (!raw) {
return "Usage: /claude-mem-search <query> [limit]";
}
const pieces = raw.split(/\s+/);
const maybeLimit = pieces[pieces.length - 1];
// A lone number is the query (a PR number, port or year), not a limit, as in /claude-mem-timeline.
const hasTrailingLimit = pieces.length >= 2 && /^\d+$/.test(maybeLimit);
const limit = hasTrailingLimit ? parseLimit(maybeLimit, 10) : 10;
const query = hasTrailingLimit ? pieces.slice(0, -1).join(" ") : raw;
const data = await workerGetJson(
workerPort,
`/api/search/observations?query=${encodeURIComponent(query)}&limit=${limit}`,
api.logger,
);
if (!data) {
return "Claude-Mem search failed (worker unavailable or invalid response).";
}
return [
`Claude-Mem Search: \"${query}\"`,
workerResultText(data),
].join("\n");
},
});
api.registerCommand({
name: "claude-mem-recent",
description: "Show recent Claude-Mem context for a project",
acceptsArgs: true,
handler: async (ctx) => {
const raw = ctx.args?.trim() || "";
const parts = raw ? raw.split(/\s+/) : [];
const maybeLimit = parts.length > 0 ? parts[parts.length - 1] : "";
const hasTrailingLimit = /^\d+$/.test(maybeLimit);
const limit = hasTrailingLimit ? parseLimit(maybeLimit, 3) : 3;
const project = hasTrailingLimit ? parts.slice(0, -1).join(" ") : raw;
const params = new URLSearchParams();
params.set("limit", String(limit));
if (project) params.set("project", project);
const data = await workerGetJson(
workerPort,
`/api/context/recent?${params.toString()}`,
api.logger,
);
if (!data) {
return "Claude-Mem recent context failed (worker unavailable or invalid response).";
}
return [
"Claude-Mem Recent Context",
`Project: ${project || "(auto)"}`,
workerResultText(data),
].join("\n");
},
});
api.registerCommand({
name: "claude-mem-timeline",
description: "Find best memory match and show nearby timeline events",
acceptsArgs: true,
handler: async (ctx) => {
const raw = ctx.args?.trim() || "";
if (!raw) {
return "Usage: /claude-mem-timeline <query> [depthBefore] [depthAfter]";
}
const parts = raw.split(/\s+/);
let depthAfter = 5;
let depthBefore = 5;
if (parts.length >= 2 && /^\d+$/.test(parts[parts.length - 1])) {
depthAfter = parseLimit(parts.pop(), 5);
}
if (parts.length >= 2 && /^\d+$/.test(parts[parts.length - 1])) {
depthBefore = parseLimit(parts.pop(), 5);
}
const query = parts.join(" ");
const params = new URLSearchParams({
query,
depth_before: String(depthBefore),
depth_after: String(depthAfter),
});
const data = await workerGetJson(
workerPort,
`/api/timeline/by-query?${params.toString()}`,
api.logger,
);
if (!data) {
return "Claude-Mem timeline lookup failed (worker unavailable or invalid response).";
}
return [
`Claude-Mem Timeline: \"${query}\"`,
workerResultText(data),
].join("\n");
},
});
api.registerCommand({
name: "claude_mem_status",
description: "Check Claude-Mem worker health and session status",
handler: async () => {
const healthText = await workerGetText(workerPort, "/api/health", api.logger);
if (!healthText) {
return { text: `Claude-Mem worker unreachable at port ${workerPort}` };
}
try {
const health = JSON.parse(healthText);
return { text: [
"Claude-Mem Worker Status",
`Status: ${health.status || "unknown"}`,
`Port: ${workerPort}`,
`Active sessions: ${sessionIds.size}`,
`Observation feed: ${connectionState}`,
].join("\n") };
} catch {
return { text: `Claude-Mem worker responded but returned unexpected data` };
}
},
});
api.logger.info(`[claude-mem] OpenClaw plugin loaded โ v1.0.0 (worker: ${_workerHost}:${workerPort})`);
}