#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
import type { Plugin } from "@opencode-ai/plugin";
import { execFileSync } from "node:child_process";
import { readFileSync, realpathSync } from "node:fs";
import { homedir } from "node:os";
import { basename, dirname, join, resolve } from "node:path";
const API = process.env.AGENTMEMORY_URL || "http://localhost:3111";
// OpenCode reports tool names in lowercase ("read", "edit", ...); matching is
// case-insensitive at the call site so a future casing change cannot silently
// kill file enrichment again.
const FILE_TOOLS = new Set(["read", "write", "edit", "glob", "grep"]);
const FILE_KEYS = ["filePath", "file_path", "path", "file", "pattern"];
const MAX_STASHED_FILES = 20;
const DEBUG = process.env.OPENCODE_AGENTMEMORY_DEBUG === "1";
function usableSecret(value: unknown): string {
const trimmed = typeof value === "string" ? value.trim() : "";
if (!trimmed || (trimmed.startsWith("${") && trimmed.endsWith("}"))) return "";
return trimmed;
}
function readAgentmemoryFile(name: string): string {
try {
return readFileSync(join(homedir(), ".agentmemory", name), "utf-8");
} catch {
return "";
}
}
function envFileSecret(): string {
let found = "";
for (const line of readAgentmemoryFile(".env").split("\n")) {
const trimmed = line.trim();
if (trimmed.startsWith("#")) continue;
const eq = trimmed.indexOf("=");
if (eq === -1) continue;
if (trimmed.slice(0, eq).replace(/^export\s+/, "").trim() !== "AGENTMEMORY_SECRET") continue;
let value = trimmed.slice(eq + 1).trim();
const quote = value[0];
const close = quote === '"' || quote === "'" ? value.indexOf(quote, 1) : -1;
if (close > 0) value = value.slice(1, close);
else if (value.includes(" #")) value = value.slice(0, value.indexOf(" #"));
found = usableSecret(value);
}
return found;
}
function isLoopbackUrl(url: string): boolean {
try {
const host = new URL(url).hostname.replace(/^\[|\]$/g, "").toLowerCase();
return host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/.test(host);
} catch {
return false;
}
}
function resolveSecret(url: string, explicit: string | undefined): string {
const configured = usableSecret(explicit);
if (configured) return configured;
if (!isLoopbackUrl(url)) return "";
return envFileSecret() || usableSecret(readAgentmemoryFile("secret"));
}
const SECRET = resolveSecret(API, process.env.AGENTMEMORY_SECRET);
function authHeaders(): Record<string, string> {
const headers: Record<string, string> = { "Content-Type": "application/json" };
if (SECRET) headers["Authorization"] = `Bearer ${SECRET}`;
return headers;
}
async function post(path: string, body: Record<string, unknown>, timeoutMs = 5000): Promise<void> {
try {
await fetch(`${API}/agentmemory${path}`, {
method: "POST",
headers: authHeaders(),
body: JSON.stringify(body),
signal: AbortSignal.timeout(timeoutMs),
});
} catch (e) {
if (DEBUG) console.error(`[agentmemory] POST ${path} failed:`, (e as Error).message);
}
}
async function postJson(path: string, body: Record<string, unknown>): Promise<unknown | null> {
try {
const res = await fetch(`${API}/agentmemory${path}`, {
method: "POST",
headers: authHeaders(),
body: JSON.stringify(body),
signal: AbortSignal.timeout(5000),
});
return res.ok ? await res.json() : null;
} catch (e) {
if (DEBUG) console.error(`[agentmemory] POST ${path} failed:`, (e as Error).message);
return null;
}
}
async function observe(
sessionId: string,
hookType: string,
data: Record<string, unknown>,
): Promise<void> {
const proj = projectFor(sessionId);
await post("/observe", {
hookType,
sessionId,
project: proj.name,
cwd: proj.cwd,
timestamp: new Date().toISOString(),
data,
});
}
let activeSessionId: string | null = null;
let pendingConfig: Record<string, unknown> | null = null;
// Default scope resolved at plugin init (same resolution order as the hooks'
// resolveProject: env override, git repository basename, cwd basename). In a
// long-lived OpenCode process serving multiple directories these defaults are
// only a fallback — attribution is per-session via sessionProjects, resolved
// from each session's own directory at session.created. Module-level-only
// state recorded home-directory sessions under whatever repo loaded first.
let defaultProjectName: string | null = null;
let defaultProjectCwd: string | null = null;
const sessionProjects = new Map<string, { name: string; cwd: string }>();
function projectFor(sessionId: string): { name: string | null; cwd: string | null } {
const p = sessionProjects.get(sessionId);
return p ?? { name: defaultProjectName, cwd: defaultProjectCwd };
}
const projectNameCache = new Map<string, string>();
function resolveProjectName(dir: string): string {
const explicit = process.env.AGENTMEMORY_PROJECT_NAME?.trim();
if (explicit) return explicit;
const cached = projectNameCache.get(dir);
if (cached !== undefined) return cached;
try {
const [top, gitDir, commonDir] = execFileSync(
"git",
["rev-parse", "--show-toplevel", "--git-dir", "--git-common-dir"],
{
cwd: dir,
stdio: ["ignore", "pipe", "ignore"],
encoding: "utf8",
},
)
.trim()
.split(/\r?\n/);
if (top) {
const name = basename(repositoryRoot(dir, top, gitDir, commonDir));
projectNameCache.set(dir, name);
return name;
}
} catch {
// not a git repo, fall through
}
const fallback = basename(dir) || dir;
projectNameCache.set(dir, fallback);
return fallback;
}
function repositoryRoot(dir: string, top: string, gitDir?: string, commonDir?: string): string {
if (!gitDir || !commonDir) return top;
const physical = realpathSync(dir);
const common = resolve(physical, commonDir);
if (resolve(physical, gitDir) === common || basename(common) !== ".git") return top;
return dirname(common);
}
const stashedFiles = new Map<string, Set<string>>();
const seenSubtaskIds = new Map<string, Set<string>>();
const seenToolCallIds = new Map<string, Set<string>>();
const contextInjectedSessions = new Set<string>();
// cache the context returned by POST /session/start so the chat
// system-transform hook can inject it without a second /context fetch.
// Auto-injection now happens at session.created (immediately) AND at
// the first prompt_submit (fallback for older OpenCode builds that
// don't implement experimental.chat.system.transform).
const startContextCache = new Map<string, string>();
function stashFor(sid: string): Set<string> {
let s = stashedFiles.get(sid);
if (!s) { s = new Set<string>(); stashedFiles.set(sid, s); }
return s;
}
function subtaskSetFor(sid: string): Set<string> {
let s = seenSubtaskIds.get(sid);
if (!s) { s = new Set<string>(); seenSubtaskIds.set(sid, s); }
return s;
}
function toolCallSetFor(sid: string): Set<string> {
let s = seenToolCallIds.get(sid);
if (!s) { s = new Set<string>(); seenToolCallIds.set(sid, s); }
return s;
}
function pruneSessionMaps(sid: string): void {
stashedFiles.delete(sid);
seenSubtaskIds.delete(sid);
seenToolCallIds.delete(sid);
sessionProjects.delete(sid);
}
function safeSlice(v: unknown, max: number): string {
if (typeof v === "string") return v.slice(0, max);
if (v == null) return "";
try { return JSON.stringify(v).slice(0, max); } catch { return ""; }
}
const AGENTMEMORY_INSTRUCTIONS = `<agentmemory-instructions>
You have access to agentmemory for persistent cross-session memory. Use these tools proactively.
CORE TOOLS:
memory_save — Save an insight, decision, or fact to long-term memory.
Required: content (text), concepts (2-5 comma-separated keywords), type (pattern/preference/architecture/bug/workflow/fact)
Optional: files (comma-separated paths)
Use when: user says "remember this", after discovering a bug, after making an architectural decision, after learning a project convention.
memory_recall — Search past observations by keywords.
Use when: user says "recall", "what did we do", "do you remember", or needs context from past sessions.
memory_smart_search — Hybrid semantic+keyword search with progressive disclosure.
Use when: you need the most relevant past context, fuzzy/conceptual searches, or recall doesn't find what you need.
memory_sessions — List recent sessions with status and observation counts.
Use when: user asks about session/past history, "what did we work on".
memory_file_history — Get past observations about specific files (across all sessions).
Use when: you're about to edit a file and want to know its history, common pitfalls, or past edits.
memory_lesson_save — Save a lesson learned (what worked, what to avoid).
Use when: you discover a pattern that could help future sessions avoid mistakes.
memory_lesson_recall — Search lessons by query. Returns lessons sorted by confidence.
Use when: before making a decision, check if past lessons apply.
memory_governance_delete — Delete specific memories. Requires explicit user confirmation.
Use when: user says "forget this", "delete that memory".
memory_patterns — Detect recurring patterns across sessions.
Use when: you want to understand project-level trends over time.
memory_consolidate — Run the 4-tier memory consolidation pipeline.
Use when: you want to compress and organize accumulated session observations.
All memory tools start with \`agentmemory_memory_\`. Use the exact names as they appear in your tool list. Tool results are JSON. Always check what was returned before presenting to the user.
</agentmemory-instructions>`;
function extractFilePaths(args: Record<string, unknown>): string[] {
const files: string[] = [];
for (const key of FILE_KEYS) {
const val = args[key];
if (typeof val === "string" && val.length > 0) {
files.push(val);
}
}
return files;
}
function extractErrorMessage(err: unknown): string {
if (typeof err === "string") return err;
if (err && typeof err === "object") {
const e = err as Record<string, unknown>;
if (typeof e.message === "string") return e.message;
if (e.data && typeof e.data === "object") {
const d = e.data as Record<string, unknown>;
if (typeof d.message === "string") return d.message;
}
if (typeof e.name === "string") return e.name;
try { return JSON.stringify(err); } catch { return ""; }
}
return String(err ?? "");
}
const v1Hooks: Plugin = async (ctx) => {
defaultProjectCwd = ctx.worktree || ctx.project?.id || process.cwd();
defaultProjectName = resolveProjectName(defaultProjectCwd);
return {
event: async ({ event }) => {
const type = event.type;
const props = (event as any).properties || {};
// ── session.created ──
if (type === "session.created") {
const info = props.info as Record<string, unknown> | undefined;
activeSessionId = (info?.id as string) || props.sessionID || null;
if (!activeSessionId) return;
stashedFiles.set(activeSessionId, new Set());
seenSubtaskIds.delete(activeSessionId);
seenToolCallIds.delete(activeSessionId);
contextInjectedSessions.delete(activeSessionId);
// Snapshot the session id locally — `activeSessionId` is mutable
// and another `session.created` event during the await could
// rebind it, causing context to be cached against the wrong key.
const sessionId = activeSessionId;
// Attribute this session to its own directory when the event
// carries one; a multi-directory OpenCode process otherwise
// records every session under whichever repo loaded the plugin.
const sessionDir =
typeof info?.directory === "string" && info.directory
? info.directory
: defaultProjectCwd;
let proj: { name: string | null; cwd: string | null };
if (sessionDir) {
const entry = { cwd: sessionDir, name: resolveProjectName(sessionDir) };
sessionProjects.set(sessionId, entry);
proj = entry;
} else {
proj = projectFor(sessionId);
}
const startResult = await postJson("/session/start", {
sessionId,
title: info?.title ?? null,
parentID: info?.parentID ?? null,
version: info?.version ?? null,
project: proj.name,
cwd: proj.cwd,
});
// cache the context returned at session/start so the
// chat.system.transform hook injects it without a second fetch.
const startCtx = (startResult as any)?.context;
if (typeof startCtx === "string" && startCtx.length > 0) {
startContextCache.set(sessionId, startCtx);
}
if (pendingConfig) {
await observe(sessionId, "config_loaded", pendingConfig);
pendingConfig = null;
}
}
// ── session.idle ── (summarize handled in session.status idle branch)
// ── session.status ──
if (type === "session.status") {
const status = props.status as Record<string, unknown> | undefined;
const sid = props.sessionID || activeSessionId;
if (!sid || !status) return;
if (status.type === "idle") {
await post("/summarize", { sessionId: sid });
}
await observe(sid, "session_status", {
status_type: status.type,
attempt: status.attempt ?? null,
message: safeSlice(status.message, 2000),
});
}
// ── session.compacted ──
if (type === "session.compacted") {
const sid = props.sessionID || activeSessionId;
if (sid) {
await post("/summarize", { sessionId: sid });
await observe(sid, "session_compacted", {});
}
}
// ── session.updated ──
if (type === "session.updated") {
const info = props.info as Record<string, unknown> | undefined;
const sid = (info?.id as string) || props.sessionID || activeSessionId;
if (!sid) return;
await observe(sid, "session_updated", {
title: info?.title ?? null,
parentID: info?.parentID ?? null,
additions: (info?.summary as any)?.additions ?? null,
deletions: (info?.summary as any)?.deletions ?? null,
files: (info?.summary as any)?.files ?? null,
});
}
// ── session.diff ──
if (type === "session.diff") {
const sid = props.sessionID || activeSessionId;
if (!sid || !Array.isArray(props.diff)) return;
const diffs = props.diff as Array<Record<string, unknown>>;
await observe(sid, "session_diff", {
files: diffs.map(d => d.file),
additions: diffs.reduce((s, d) => s + ((d.additions as number) || 0), 0),
deletions: diffs.reduce((s, d) => s + ((d.deletions as number) || 0), 0),
diffs: diffs.slice(0, 50),
});
}
// ── session.deleted ──
if (type === "session.deleted") {
const sid = props.info?.id || props.sessionID || activeSessionId;
if (!sid) {
if (DEBUG) console.error("[agentmemory] session.deleted with no session ID");
return;
}
await post("/session/end", { sessionId: sid, final: true });
post("/crystals/auto", { olderThanDays: 7 }, 30000);
post("/consolidate-pipeline", { tier: "all", force: true }, 30000);
if (sid === activeSessionId) activeSessionId = null;
pruneSessionMaps(sid);
startContextCache.delete(sid);
contextInjectedSessions.delete(sid);
}
// ── session.error ──
if (type === "session.error") {
const sid = props.sessionID || activeSessionId;
if (sid) {
await observe(sid, "post_tool_failure", {
tool_name: "session.error",
tool_input: "",
tool_output: safeSlice(props.error, 8000),
});
}
}
// ── message.updated ──
if (type === "message.updated") {
const info = props.info as Record<string, unknown> | undefined;
if (!info) return;
if (info.role === "assistant") {
const sid = props.sessionID || (info.sessionID as string) || activeSessionId;
if (!sid) return;
const tokens = info.tokens as Record<string, unknown> | undefined;
const error = info.error ? extractErrorMessage(info.error) : null;
await observe(sid, "assistant_message", {
messageID: info.id,
parentID: info.parentID,
modelID: info.modelID,
providerID: info.providerID,
mode: info.mode,
cost: info.cost ?? 0,
tokens: {
input: tokens?.input ?? 0,
output: tokens?.output ?? 0,
reasoning: tokens?.reasoning ?? 0,
cache_read: (tokens?.cache as any)?.read ?? 0,
cache_write: (tokens?.cache as any)?.write ?? 0,
},
finish: info.finish ?? null,
error,
duration_ms: (info.time && typeof (info.time as any).completed === "number")
? (info.time as any).completed - ((info.time as any).created || 0)
: null,
});
}
}
// ── message.removed ──
if (type === "message.removed") {
const sid = props.sessionID || activeSessionId;
if (sid) {
await observe(sid, "message_removed", {
messageID: props.messageID,
});
}
}
// ── message.part.updated ──
if (type === "message.part.updated") {
const part = props.part as Record<string, unknown> | undefined;
if (!part) return;
const sid = (part.sessionID as string) || props.sessionID || activeSessionId;
if (!sid) return;
if (part.type === "subtask") {
const subtaskId = part.id as string;
if (!subtaskId) return;
const subtaskSet = subtaskSetFor(sid);
if (subtaskSet.has(subtaskId)) return;
subtaskSet.add(subtaskId);
await observe(sid, "subagent_start", {
subtask_id: part.id,
agent: part.agent,
prompt: safeSlice(part.prompt, 4000),
description: safeSlice(part.description, 2000),
});
return;
}
if (part.type === "tool") {
const state = part.state as Record<string, unknown> | undefined;
if (!state) return;
const callId = part.callID as string;
if (!callId) return;
const toolName = part.tool as string;
if (state.status === "completed") {
const callSet = toolCallSetFor(sid);
if (callSet.has(callId)) return;
callSet.add(callId);
const st = state as Record<string, unknown>;
const rawTime = (st.time as any) || {};
const startTime = typeof rawTime.start === "number" ? rawTime.start : null;
const endTime = typeof rawTime.end === "number" ? rawTime.end : null;
await observe(sid, "post_tool_use", {
tool_name: toolName,
call_id: callId,
tool_input: safeSlice(st.input, 4000),
tool_output: safeSlice(st.output, 8000),
title: st.title ?? null,
metadata: st.metadata || {},
duration_ms: (startTime != null && endTime != null) ? endTime - startTime : null,
attachments: Array.isArray(st.attachments)
? (st.attachments as Array<Record<string, unknown>>).map(a => a.filename || a.url)
: [],
});
} else if (state.status === "error") {
const callSet = toolCallSetFor(sid);
if (callSet.has(callId)) return;
callSet.add(callId);
const st = state as Record<string, unknown>;
const rawTime = (st.time as any) || {};
const startTime = typeof rawTime.start === "number" ? rawTime.start : null;
const endTime = typeof rawTime.end === "number" ? rawTime.end : null;
await observe(sid, "post_tool_failure", {
tool_name: toolName,
call_id: callId,
tool_input: safeSlice(st.input, 4000),
tool_output: safeSlice(st.error, 8000),
duration_ms: (startTime != null && endTime != null) ? endTime - startTime : null,
});
}
return;
}
if (part.type === "step-finish") {
await observe(sid, "step_finish", {
messageID: part.messageID,
reason: part.reason ?? null,
cost: (part as any).cost ?? 0,
input_tokens: ((part as any).tokens?.input as number) ?? 0,
output_tokens: ((part as any).tokens?.output as number) ?? 0,
reasoning_tokens: ((part as any).tokens?.reasoning as number) ?? 0,
});
return;
}
if (part.type === "reasoning") {
await observe(sid, "reasoning", {
messageID: part.messageID,
text: safeSlice((part as any).text, 4000),
});
return;
}
if (part.type === "file") {
const filename = (part as any).filename || (part as any).url || null;
if (filename) stashFor(sid).add(filename);
return;
}
if (part.type === "patch") {
await observe(sid, "patch_applied", {
messageID: part.messageID,
hash: (part as any).hash,
files: (part as any).files || [],
});
return;
}
if (part.type === "compaction") {
await observe(sid, "compaction_event", {
messageID: part.messageID,
auto: (part as any).auto ?? false,
});
return;
}
if (part.type === "agent") {
await observe(sid, "agent_selected", {
messageID: part.messageID,
name: (part as any).name,
});
return;
}
if (part.type === "retry") {
await observe(sid, "retry_attempt", {
messageID: part.messageID,
attempt: (part as any).attempt,
error: safeSlice((part as any).error, 2000),
});
return;
}
}
// ── file.edited ──
if (type === "file.edited") {
const sid = props.sessionID || activeSessionId;
if (sid && typeof props.file === "string" && props.file.length > 0) {
const stash = stashFor(sid);
stash.add(props.file);
if (stash.size > MAX_STASHED_FILES) {
const keep = [...stash].slice(-MAX_STASHED_FILES);
stash.clear();
for (const f of keep) stash.add(f);
}
}
}
// ── permission.updated ──
if (type === "permission.updated") {
const sid = props.sessionID || activeSessionId;
if (!sid) return;
await observe(sid, "notification", {
notification_type: "permission_prompt",
permission: props.type || "unknown",
pattern: Array.isArray(props.pattern)
? props.pattern.join(", ")
: (props.pattern || ""),
tool_call_id: props.callID || null,
title: props.title || props.type || "",
metadata: props.metadata || {},
});
}
// ── permission.replied ──
if (type === "permission.replied") {
const sid = props.sessionID || activeSessionId;
if (!sid) return;
await observe(sid, "permission_replied", {
permission_id: props.permissionID || props.requestID || "",
response: props.response || props.reply || "",
});
}
// ── todo.updated ──
if (type === "todo.updated") {
const sid = props.sessionID || activeSessionId;
const todos = Array.isArray(props.todos) ? props.todos.slice(0, 100) : [];
if (!sid || todos.length === 0) return;
const completed = todos.filter((t: any) => t.status === "completed");
const active = todos.filter((t: any) => t.status !== "completed");
await observe(sid, "task_completed", {
completed: completed.map((t: any) => ({ content: t.content, priority: t.priority })),
in_progress: active.map((t: any) => ({ content: t.content, priority: t.priority })),
total: todos.length,
});
}
// ── command.executed ──
if (type === "command.executed") {
const sid = props.sessionID || activeSessionId;
if (sid) {
await observe(sid, "command_executed", {
name: props.name,
arguments: props.arguments || "",
});
}
}
},
// ── chat.message ──
"chat.message": async (input, output) => {
const sid = input.sessionID || activeSessionId;
if (!sid) return;
const parts = output.parts || [];
const files = parts
.filter((p: any) => p.type === "file")
.map((p: any) => p.filename || p.url)
.filter(Boolean);
for (const f of files) {
const stash = stashFor(sid);
stash.add(f);
if (stash.size > MAX_STASHED_FILES) {
const keep = [...stash].slice(-MAX_STASHED_FILES);
stash.clear();
for (const k of keep) stash.add(k);
}
}
const textParts = parts.filter((p: any) => p.type === "text" && !p.synthetic && !p.ignored);
const userText = textParts.map((p: any) => p.text || "").join("\n");
await observe(sid, "prompt_submit", {
agent: input.agent ?? null,
model: input.model ?? null,
variant: input.variant ?? null,
prompt: userText.slice(0, 8000),
files: files.slice(0, 20),
parts_summary: parts.map((p: any) => p.type).filter(Boolean),
});
},
// ── chat.params ──
"chat.params": async (input, output) => {
if (!input.model || !output) return;
const sid = input.sessionID || activeSessionId;
if (!sid) return;
await observe(sid, "llm_params", {
agent: input.agent,
model: `${input.model.providerID}/${input.model.id}`,
provider_url: input.model.api?.url ?? null,
temperature: output.temperature,
topP: output.topP,
max_output_tokens: input.model.limit?.output ?? null,
context_limit: input.model.limit?.context ?? null,
cost_1k_input: input.model.cost?.input ?? 0,
cost_1k_output: input.model.cost?.output ?? 0,
});
},
// ── tool.execute.before ──
"tool.execute.before": async (input, output) => {
if (!FILE_TOOLS.has(String(input.tool ?? "").toLowerCase())) return;
const sid = input.sessionID || activeSessionId;
if (!sid) return;
const args = output.args as Record<string, unknown> | undefined;
if (!args) return;
const stash = stashFor(sid);
for (const fp of extractFilePaths(args)) {
stash.add(fp);
}
if (stash.size > MAX_STASHED_FILES) {
const keep = [...stash].slice(-MAX_STASHED_FILES);
stash.clear();
for (const f of keep) stash.add(f);
}
},
// ── experimental.chat.system.transform ──
"experimental.chat.system.transform": async (input, output) => {
const sid = input.sessionID || activeSessionId;
if (!sid) return;
if (!contextInjectedSessions.has(sid)) {
if (!Array.isArray(output.system)) return;
output.system.push(AGENTMEMORY_INSTRUCTIONS);
// prefer the context already fetched at session.created;
// fall back to a fresh /context call if the cache missed (e.g.
// session resumed across plugin reloads).
let ctx = startContextCache.get(sid);
if (typeof ctx !== "string" || ctx.length === 0) {
const result = await postJson("/context", {
sessionId: sid,
project: projectFor(sid).name,
});
ctx = (result as any)?.context;
} else {
startContextCache.delete(sid);
}
if (typeof ctx === "string" && ctx.length > 0) {
output.system.push(ctx);
}
contextInjectedSessions.add(sid);
}
const stash = stashFor(sid);
if (stash.size === 0) return;
const files = [...stash].slice(0, 10);
const enrichResult = await postJson("/enrich", {
sessionId: sid,
files,
toolName: "enrich_inject",
});
const enrichCtx = (enrichResult as any)?.context;
if (typeof enrichCtx === "string" && enrichCtx.length > 0) {
if (Array.isArray(output.system)) {
output.system.push(enrichCtx);
}
for (const f of files) stash.delete(f);
}
},
// ── experimental.session.compacting (WIP) ──
"experimental.session.compacting": async (input, output) => {
const sid = input.sessionID || activeSessionId;
if (!sid) return;
const result = await postJson("/context", {
sessionId: sid,
project: projectFor(sid).name,
});
const ctx = (result as any)?.context;
if (typeof ctx === "string" && ctx.length > 0) {
if (Array.isArray(output.context)) {
output.context.push(ctx);
}
}
},
// ── config ──
config: async (input) => {
const payload: Record<string, unknown> = {
theme: input.theme ?? null,
model: input.model ?? null,
autoupdate: input.autoupdate ?? null,
agents: typeof input.agent === "object" && input.agent !== null && !Array.isArray(input.agent)
? Object.keys(input.agent as Record<string, unknown>)
: Array.isArray(input.agent) ? input.agent : [],
mcp_servers: typeof input.mcp === "object" && input.mcp !== null && !Array.isArray(input.mcp)
? Object.keys(input.mcp as Record<string, unknown>)
: Array.isArray(input.mcp) ? input.mcp : [],
providers: typeof input.provider === "object" && input.provider !== null && !Array.isArray(input.provider)
? Object.keys(input.provider as Record<string, unknown>)
: Array.isArray(input.provider) ? input.provider : [],
permission: input.permission ?? null,
};
if (activeSessionId) {
await observe(activeSessionId, "config_loaded", payload);
} else {
pendingConfig = payload;
}
},
};
};
async function v2Setup(ctx: any) {
if (typeof ctx?.tool?.hook !== "function" || typeof ctx?.session?.hook !== "function" || typeof ctx?.event?.subscribe !== "function") {
return;
}
const location = ctx.location;
defaultProjectCwd = location?.directory ?? location?.project?.directory ?? process.cwd();
defaultProjectName = resolveProjectName(defaultProjectCwd);
async function observeV2(sessionId: string, hookType: string, data: Record<string, unknown>): Promise<void> {
await observe(sessionId, hookType, data);
}
const shellSessions = new Map<string, string>();
const turnContextCache = new Map<string, string>();
function stashAdd(sid: string, paths: Iterable<string>): void {
const stash = stashFor(sid);
for (const p of paths) stash.add(p);
if (stash.size > MAX_STASHED_FILES) {
const keep = [...stash].slice(-MAX_STASHED_FILES);
stash.clear();
for (const k of keep) stash.add(k);
}
}
const toolNames = new Map<string, string>();
const toolCallInputs = new Map<string, Record<string, unknown>>();
const reportedToolCalls = new Set<string>();
const registeredSessions = new Set<string>();
function namesFrom(result: unknown): string[] {
const arr = Array.isArray(result) ? result : (result as any)?.data;
if (!Array.isArray(arr)) return [];
return arr.map((x: any) => (typeof x === "string" ? x : x?.id ?? x?.name)).filter(Boolean);
}
let lastConfigSnapshot: string | null = null;
async function snapshotConfig(): Promise<void> {
const [agents, providers, mcp, modelDefault] = await Promise.all([
ctx.agent?.list?.().catch(() => null),
ctx.provider?.list?.().catch(() => null),
ctx.mcp?.list?.().catch(() => null),
Promise.resolve(ctx.model?.default?.()).catch(() => null),
]);
const model = Array.isArray(modelDefault) ? modelDefault[0] : (modelDefault as any)?.data;
const payload = {
agents: namesFrom(agents),
providers: namesFrom(providers),
mcp_servers: namesFrom(mcp),
model: model ? `${model.providerID ?? ""}/${model.id ?? model.modelID ?? ""}` : null,
model_limits: model?.limit ?? null,
location: defaultProjectCwd,
};
const snapshot = JSON.stringify(payload);
if (snapshot === lastConfigSnapshot) return;
lastConfigSnapshot = snapshot;
if (activeSessionId) await observeV2(activeSessionId, "config_loaded", payload);
else pendingConfig = payload;
}
void snapshotConfig().catch((e) => {
if (DEBUG) console.error("[agentmemory] config snapshot failed:", (e as Error).message);
});
await ctx.tool.hook("execute.before", (event: any) => {
if (!FILE_TOOLS.has(String(event?.tool ?? "").toLowerCase())) return;
const sid = event?.sessionID || activeSessionId;
if (!sid) return;
const args = event?.input as Record<string, unknown> | undefined;
if (!args) return;
stashAdd(sid, extractFilePaths(args));
});
await ctx.tool.hook("execute.after", async (event: any) => {
const sid = event?.sessionID || activeSessionId;
if (!sid) return;
const tool = String(event?.tool ?? "");
const callId = (event?.id as string) || (event?.messageID as string) || null;
const status = String(event?.status ?? "");
const result = event?.result ?? {};
const metadata = (result?.metadata ?? {}) as Record<string, unknown>;
const output = result?.output as Record<string, unknown> | undefined;
const raw = output?.output ?? result?.content;
const text = Array.isArray(raw)
? raw.map((p: any) => (typeof p === "string" ? p : (p?.text ?? ""))).join("\n")
: typeof raw === "string"
? raw
: "";
const startMs = typeof metadata?.started === "number" ? metadata.started : null;
const endMs = typeof metadata?.ended === "number" ? metadata.ended : null;
const duration = startMs != null && endMs != null ? endMs - startMs : null;
if (status === "error") {
await observeV2(sid, "post_tool_failure", {
tool_name: tool,
call_id: callId,
tool_input: safeSlice(event?.input, 4000),
tool_output: safeSlice(text || extractErrorMessage(event?.error) || extractErrorMessage(metadata?.error), 8000),
duration_ms: duration,
});
if (callId) reportedToolCalls.add(`${sid}:${callId}`);
return;
}
await observeV2(sid, "post_tool_use", {
tool_name: tool,
call_id: callId,
tool_input: safeSlice(event?.input, 4000),
tool_output: safeSlice(text, 8000),
title: (output?.title as string) ?? null,
metadata: metadata,
duration_ms: duration,
attachments: Array.isArray(output?.attachments)
? (output?.attachments as Array<Record<string, unknown>>).map((a) => a.filename || a.url)
: [],
});
if (callId) reportedToolCalls.add(`${sid}:${callId}`);
});
await ctx.session.hook("prompt", async (event: any) => {
const sid = event?.sessionID || activeSessionId;
if (!sid) return;
const files = (event?.prompt?.files ?? [])
.map((f: any) => (typeof f === "string" ? f : f?.uri ?? f?.filename ?? f?.url))
.filter(Boolean) as string[];
stashAdd(sid, files);
turnContextCache.delete(sid);
await observeV2(sid, "prompt_submit", {
prompt: (event?.prompt?.text ?? "").slice(0, 8000),
files: files.slice(0, 20),
agents: event?.prompt?.agents ?? [],
skills: event?.prompt?.skills ?? [],
delivery: event?.delivery ?? null,
});
});
await ctx.session.hook("context", async (event: any) => {
const sid = event?.sessionID || activeSessionId;
if (!sid) return;
if (!Array.isArray(event.system)) return;
if (!contextInjectedSessions.has(sid)) {
event.system.push({ type: "text", text: AGENTMEMORY_INSTRUCTIONS });
contextInjectedSessions.add(sid);
}
let ctxText = startContextCache.get(sid) ?? turnContextCache.get(sid);
if (typeof ctxText !== "string" || ctxText.length === 0) {
const result = await postJson("/context", { sessionId: sid, project: projectFor(sid).name });
ctxText = (result as any)?.context;
}
if (typeof ctxText === "string" && ctxText.length > 0) {
turnContextCache.set(sid, ctxText);
startContextCache.delete(sid);
event.system.push({ type: "text", text: ctxText });
}
const stash = stashFor(sid);
if (stash.size === 0) return;
const files = [...stash].slice(0, 10);
const enrichResult = await postJson("/enrich", { sessionId: sid, files, toolName: "enrich_inject" });
const enrichCtx = (enrichResult as any)?.context;
if (typeof enrichCtx === "string" && enrichCtx.length > 0) {
event.system.push({ type: "text", text: enrichCtx });
for (const f of files) stash.delete(f);
}
});
await ctx.session.hook("compaction", async (event: any) => {
const sid = event?.sessionID || activeSessionId;
if (!sid) return;
if (!Array.isArray(event?.system)) return;
let ctxText = turnContextCache.get(sid);
if (typeof ctxText !== "string" || ctxText.length === 0) {
const result = await postJson("/context", { sessionId: sid, project: projectFor(sid).name });
ctxText = (result as any)?.context;
if (typeof ctxText === "string" && ctxText.length > 0) turnContextCache.set(sid, ctxText);
}
if (typeof ctxText === "string" && ctxText.length > 0) {
event.system.push({ type: "text", text: ctxText });
}
});
const controller = new AbortController();
const handleEvent = async (event: any): Promise<void> => {
const type = String(event?.type ?? "");
const data: any = event?.data ?? {};
const eventSid = typeof data.sessionID === "string" && data.sessionID ? data.sessionID : null;
const sid0 = eventSid || activeSessionId;
if (eventSid && !registeredSessions.has(eventSid)) {
if (!activeSessionId) activeSessionId = eventSid;
stashedFiles.set(sid0, new Set());
seenSubtaskIds.delete(sid0);
seenToolCallIds.delete(sid0);
contextInjectedSessions.delete(sid0);
const dir = (data.location?.directory as string) || (event?.location?.directory as string) || null;
if (dir) {
sessionProjects.set(sid0, { cwd: dir, name: resolveProjectName(dir) });
}
const proj = projectFor(sid0);
const startResult = await postJson("/session/start", {
sessionId: sid0,
title: (data.title as string) ?? null,
parentID: (data.parentID as string) ?? null,
project: proj.name,
cwd: proj.cwd,
});
if (startResult === null) {
stashedFiles.delete(sid0);
contextInjectedSessions.delete(sid0);
if (activeSessionId === eventSid) activeSessionId = null;
if (DEBUG) {
console.error("[agentmemory] /session/start failed, will retry on the next event for", eventSid);
}
return;
}
registeredSessions.add(eventSid);
const startCtx = (startResult as any)?.context;
if (typeof startCtx === "string" && startCtx.length > 0) startContextCache.set(sid0, startCtx);
await observeV2(sid0, "session_started", {});
if (pendingConfig) {
await observeV2(sid0, "config_loaded", pendingConfig);
pendingConfig = null;
}
}
switch (type) {
case "session.execution.failed": {
if (!sid0) return;
await observeV2(sid0, "post_tool_failure", {
tool_name: "session.execution",
tool_input: "",
tool_output: safeSlice(extractErrorMessage(data.error ?? data), 8000),
});
return;
}
case "session.compaction.started": {
if (!sid0) return;
await observeV2(sid0, "compaction_event", {
state: "started",
reason: (data.reason as string) ?? null,
inputID: (data.inputID as string) ?? null,
recent: safeSlice(data.recent, 8000),
});
return;
}
case "session.compaction.failed": {
if (!sid0) return;
await observeV2(sid0, "compaction_event", {
state: "failed",
reason: (data.reason as string) ?? null,
inputID: (data.inputID as string) ?? null,
tool_output: safeSlice(extractErrorMessage(data.error ?? data.reason), 8000),
});
return;
}
case "session.step.started": {
if (!sid0) return;
await observeV2(sid0, "step_start", {
messageID: (data.assistantMessageID as string) ?? null,
agent: (data.agent as string) ?? null,
model: data.model ? `${data.model.providerID ?? ""}/${data.model.id ?? ""}` : null,
});
return;
}
case "session.step.ended": {
if (!sid0) return;
const tokens = (data.tokens ?? {}) as Record<string, any>;
await observeV2(sid0, "step_finish", {
messageID: (data.assistantMessageID as string) ?? null,
reason: (data.rawFinish as string) ?? (data.finish as string) ?? null,
cost: data.cost ?? 0,
input_tokens: tokens.input ?? 0,
output_tokens: tokens.output ?? 0,
reasoning_tokens: tokens.reasoning ?? 0,
cache_read: tokens.cache?.read ?? 0,
cache_write: tokens.cache?.write ?? 0,
});
return;
}
case "session.agent.selected": {
if (!sid0) return;
await observeV2(sid0, "agent_selected", {
name: (data.agent as string) ?? null,
previous: (data.previous as string) ?? null,
});
return;
}
case "session.reasoning.ended": {
if (!sid0) return;
await observeV2(sid0, "reasoning", {
messageID: (data.assistantMessageID as string) ?? null,
text: safeSlice(data.text, 4000),
});
return;
}
case "session.instructions.updated": {
if (!sid0) return;
const sources = data.delta && typeof data.delta === "object" ? Object.keys(data.delta) : [];
if (sources.length === 0) return;
await observeV2(sid0, "notification", {
notification_type: "instructions_updated",
sources: sources.slice(0, 50),
});
return;
}
case "session.text.ended": {
if (!sid0) return;
const text = typeof data.text === "string" ? data.text : "";
if (!text) return;
await observeV2(sid0, "assistant_message", {
messageID: (data.assistantMessageID as string) ?? null,
text: text.slice(0, 8000),
});
return;
}
case "session.execution.succeeded": {
if (!sid0) return;
await post("/summarize", { sessionId: sid0 });
return;
}
case "shell.created": {
const info = (data.info ?? {}) as Record<string, any>;
const shellSid = (info.metadata?.sessionID as string) || sid0;
if (!shellSid) return;
if (info.id) shellSessions.set(String(info.id), shellSid);
return;
}
case "shell.exited": {
const shellId = String(data.id ?? "");
const shellSid = shellSessions.get(shellId) || activeSessionId;
if (!shellSid) return;
const exit = Number(data.exit ?? 0);
if (exit !== 0) {
await observeV2(shellSid, "post_tool_failure", {
tool_name: "shell",
call_id: shellId,
tool_input: null,
tool_output: safeSlice(data.status, 4000),
duration_ms: null,
});
}
return;
}
case "shell.deleted": {
const shellId = String(data.id ?? "");
shellSessions.delete(shellId);
return;
}
case "file.watcher.updated":
case "filesystem.changed":
case "vcs.branch.updated": {
const sid = sid0 || activeSessionId;
if (!sid) return;
const file = (data.file as string) ?? (data.path as string) ?? null;
if (file) stashAdd(sid, [file]);
return;
}
case "session.tool.input.started": {
if (!sid0) return;
if (data.id) toolNames.set(String(data.id), String(data.name ?? ""));
return;
}
case "session.tool.input.ended": {
if (!sid0) return;
if (data.id && typeof data.text === "string" && !toolNames.has(String(data.id))) {
try {
const parsed = JSON.parse(data.text);
if (typeof parsed?.name === "string") toolNames.set(String(data.id), parsed.name);
} catch {
}
}
return;
}
case "session.tool.called": {
if (!sid0) return;
if (data.id) toolCallInputs.set(String(data.id), (data.input ?? {}) as Record<string, unknown>);
return;
}
case "session.tool.progress": {
if (!sid0) return;
const callId = String(data.id ?? "");
if (!callId || !FILE_TOOLS.has((toolNames.get(callId) ?? "").toLowerCase())) return;
const input = toolCallInputs.get(callId);
if (!input) return;
stashAdd(sid0, extractFilePaths(input));
return;
}
case "session.tool.success": {
const callId = String(data.id ?? "");
toolNames.delete(callId);
toolCallInputs.delete(callId);
if (sid0) reportedToolCalls.delete(`${sid0}:${callId}`);
return;
}
case "session.tool.failed": {
if (!sid0) return;
const callId = String(data.id ?? "");
if (callId && reportedToolCalls.has(`${sid0}:${callId}`)) return;
await observeV2(sid0, "post_tool_failure", {
tool_name: toolNames.get(callId) || null,
call_id: callId || null,
tool_input: safeSlice(toolCallInputs.get(callId), 4000),
tool_output: safeSlice(extractErrorMessage(data.error), 8000),
duration_ms: null,
});
if (callId) {
toolNames.delete(callId);
toolCallInputs.delete(callId);
}
return;
}
case "permission.asked": {
if (!sid0) return;
const resources = (data.resources ?? data.patterns ?? []) as unknown;
await observeV2(sid0, "notification", {
notification_type: "permission_prompt",
permission: (data.action as string) ?? (data.permission as string) ?? "unknown",
pattern: Array.isArray(resources) ? resources.join(", ") : String(resources ?? ""),
tool_call_id: (data.tool?.callID as string) ?? (data.callID as string) ?? null,
title: (data.action as string) ?? (data.permission as string) ?? "",
metadata: data.metadata ?? {},
});
return;
}
case "permission.replied": {
if (!sid0) return;
await observeV2(sid0, "permission_replied", {
permission_id: (data.requestID as string) ?? (data.permissionID as string) ?? "",
response: (data.reply as string) ?? (data.response as string) ?? "",
});
return;
}
case "session.deleted": {
const sid = (data.sessionID as string) || activeSessionId;
if (!sid) return;
await post("/session/end", { sessionId: sid, final: true });
void post("/crystals/auto", { olderThanDays: 7 }, 30000);
void post("/consolidate-pipeline", { tier: "all", force: true }, 30000);
if (sid === activeSessionId) activeSessionId = null;
registeredSessions.delete(sid);
pruneSessionMaps(sid);
startContextCache.delete(sid);
contextInjectedSessions.delete(sid);
for (const key of reportedToolCalls) {
if (key.startsWith(`${sid}:`)) reportedToolCalls.delete(key);
}
return;
}
case "config.updated":
case "agent.updated":
case "provider.updated":
case "model.updated":
case "mcp.status.changed": {
if (DEBUG) console.error("[agentmemory] config changed, re-snapshotting");
void snapshotConfig().catch(() => {});
return;
}
}
};
void (async () => {
try {
for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
try {
await handleEvent(event);
} catch (e) {
if (DEBUG) console.error("[agentmemory] event handler failed:", (e as Error).message);
}
}
} catch (e) {
if (DEBUG) console.error("[agentmemory] event stream failed:", (e as Error).message);
}
})();
return () => {
controller.abort();
startContextCache.clear();
contextInjectedSessions.clear();
};
}
export default {
id: "agentmemory-capture",
setup: v2Setup,
server: v1Hooks,
};
export const AgentmemoryCapturePlugin: Plugin = v1Hooks;