@agentmemory/agentmemory 0.7.0

package/src/functions/verify.ts

@@ -0,0 +1,117 @@
+import type { ISdk } from "iii-sdk";
+import type { StateKV } from "../state/kv.js";
+import { KV } from "../state/schema.js";
+import type {
+  Memory,
+  CompressedObservation,
+  Session,
+} from "../types.js";
+
+export function registerVerifyFunction(sdk: ISdk, kv: StateKV): void {
+  sdk.registerFunction(
+    { id: "mem::verify" },
+    async (data: { id: string }) => {
+      if (!data.id || typeof data.id !== "string") {
+        return { success: false, error: "id is required" };
+      }
+
+      const memory = await kv.get<Memory>(KV.memories, data.id);
+      if (memory) {
+        const observationIds = memory.sourceObservationIds || [];
+        const observations: Array<{
+          observation: CompressedObservation;
+          session?: Session;
+        }> = [];
+
+        for (const obsId of observationIds) {
+          const obs = await findObservation(kv, obsId, memory.sessionIds);
+          if (obs) {
+            const session = await kv.get<Session>(KV.sessions, obs.sessionId);
+            observations.push({ observation: obs, session: session || undefined });
+          }
+        }
+
+        return {
+          success: true,
+          type: "memory",
+          memory: {
+            id: memory.id,
+            title: memory.title,
+            type: memory.type,
+            version: memory.version,
+            strength: memory.strength,
+            isLatest: memory.isLatest,
+            createdAt: memory.createdAt,
+            updatedAt: memory.updatedAt,
+            supersedes: memory.supersedes,
+            parentId: memory.parentId,
+          },
+          citations: observations.map((o) => ({
+            observationId: o.observation.id,
+            title: o.observation.title,
+            type: o.observation.type,
+            confidence: o.observation.confidence,
+            timestamp: o.observation.timestamp,
+            sessionId: o.observation.sessionId,
+            sessionProject: o.session?.project,
+            sessionStatus: o.session?.status,
+          })),
+          citationCount: observations.length,
+        };
+      }
+
+      const obs = await findObservation(kv, data.id);
+      if (obs) {
+        const session = await kv.get<Session>(KV.sessions, obs.sessionId);
+        return {
+          success: true,
+          type: "observation",
+          observation: {
+            id: obs.id,
+            title: obs.title,
+            type: obs.type,
+            confidence: obs.confidence,
+            importance: obs.importance,
+            timestamp: obs.timestamp,
+            sessionId: obs.sessionId,
+          },
+          session: session
+            ? {
+                id: session.id,
+                project: session.project,
+                status: session.status,
+                startedAt: session.startedAt,
+              }
+            : null,
+          citationCount: 0,
+          citations: [],
+        };
+      }
+
+      return { success: false, error: "not found" };
+    },
+  );
+}
+
+async function findObservation(
+  kv: StateKV,
+  obsId: string,
+  hintSessionIds?: string[],
+): Promise<CompressedObservation | null> {
+  if (hintSessionIds) {
+    for (const sid of hintSessionIds) {
+      const obs = await kv.get<CompressedObservation>(KV.observations(sid), obsId);
+      if (obs) return obs;
+    }
+  }
+  const sessions = await kv.list<Session>(KV.sessions);
+  for (const session of sessions) {
+    if (hintSessionIds?.includes(session.id)) continue;
+    const obs = await kv.get<CompressedObservation>(
+      KV.observations(session.id),
+      obsId,
+    );
+    if (obs) return obs;
+  }
+  return null;
+}

package/src/health/monitor.ts

@@ -0,0 +1,110 @@
+import type { ISdk } from "iii-sdk";
+import type { HealthSnapshot } from "../types.js";
+import type { StateKV } from "../state/kv.js";
+import { KV } from "../state/schema.js";
+import { evaluateHealth } from "./thresholds.js";
+
+export function registerHealthMonitor(
+  sdk: ISdk,
+  kv: StateKV,
+): { stop: () => void } {
+  let connectionState = "connected";
+  let prevCpuUsage = process.cpuUsage();
+  let prevCpuTime = Date.now();
+
+  if (typeof sdk.on === "function") {
+    sdk.on("connection_state", (state?: unknown) => {
+      connectionState = state as string;
+    });
+  }
+
+  async function collectHealth(): Promise<HealthSnapshot> {
+    const mem = process.memoryUsage();
+    const currentCpu = process.cpuUsage();
+    const now = Date.now();
+    const uptime = process.uptime();
+
+    const elapsedMs = now - prevCpuTime;
+    const userDelta = currentCpu.user - prevCpuUsage.user;
+    const systemDelta = currentCpu.system - prevCpuUsage.system;
+    const cpuPercent =
+      elapsedMs > 0 ? ((userDelta + systemDelta) / 1000 / elapsedMs) * 100 : 0;
+    prevCpuUsage = currentCpu;
+    prevCpuTime = now;
+
+    const startMark = performance.now();
+    await new Promise((resolve) => setImmediate(resolve));
+    const eventLoopLagMs = performance.now() - startMark;
+
+    let workers: HealthSnapshot["workers"] = [];
+    try {
+      const result = await sdk.trigger<
+        unknown,
+        { workers?: HealthSnapshot["workers"] }
+      >("engine::workers::list", {});
+      if (result?.workers) workers = result.workers;
+    } catch {}
+
+    const KV_PROBE_TIMEOUT = 5000;
+    let kvConnectivity: { status: string; latencyMs?: number; error?: string };
+    const kvStart = performance.now();
+    try {
+      await Promise.race([
+        (async () => {
+          await kv.set(KV.health, "_probe", { ts: Date.now() });
+          await kv.get(KV.health, "_probe");
+        })(),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error("timeout")), KV_PROBE_TIMEOUT),
+        ),
+      ]);
+      kvConnectivity = { status: "ok", latencyMs: Math.round((performance.now() - kvStart) * 100) / 100 };
+    } catch {
+      kvConnectivity = { status: "error", error: "kv_probe_failed", latencyMs: Math.round((performance.now() - kvStart) * 100) / 100 };
+    }
+
+    const snapshot: HealthSnapshot = {
+      connectionState,
+      workers,
+      memory: {
+        heapUsed: mem.heapUsed,
+        heapTotal: mem.heapTotal,
+        rss: mem.rss,
+        external: mem.external,
+      },
+      cpu: {
+        userMicros: currentCpu.user,
+        systemMicros: currentCpu.system,
+        percent: Math.round(cpuPercent * 100) / 100,
+      },
+      eventLoopLagMs,
+      uptimeSeconds: uptime,
+      kvConnectivity,
+      status: "healthy",
+      alerts: [],
+    };
+
+    const evaluated = evaluateHealth(snapshot);
+    snapshot.status = evaluated.status;
+    snapshot.alerts = evaluated.alerts;
+
+    await kv.set(KV.health, "latest", snapshot).catch(() => {});
+    return snapshot;
+  }
+
+  collectHealth().catch(() => {});
+  const interval = setInterval(() => {
+    collectHealth().catch(() => {});
+  }, 30_000);
+  interval.unref();
+
+  return {
+    stop: () => clearInterval(interval),
+  };
+}
+
+export async function getLatestHealth(
+  kv: StateKV,
+): Promise<HealthSnapshot | null> {
+  return kv.get<HealthSnapshot>(KV.health, "latest");
+}

package/src/health/thresholds.ts

@@ -0,0 +1,73 @@
+import type { HealthSnapshot } from "../types.js";
+
+interface ThresholdConfig {
+  eventLoopLagWarnMs: number;
+  eventLoopLagCriticalMs: number;
+  cpuWarnPercent: number;
+  cpuCriticalPercent: number;
+  memoryWarnPercent: number;
+  memoryCriticalPercent: number;
+}
+
+const DEFAULTS: ThresholdConfig = {
+  eventLoopLagWarnMs: 100,
+  eventLoopLagCriticalMs: 500,
+  cpuWarnPercent: 80,
+  cpuCriticalPercent: 90,
+  memoryWarnPercent: 80,
+  memoryCriticalPercent: 95,
+};
+
+export function evaluateHealth(
+  snapshot: HealthSnapshot,
+  config: Partial<ThresholdConfig> = {},
+): { status: "healthy" | "degraded" | "critical"; alerts: string[] } {
+  const cfg = { ...DEFAULTS, ...config };
+  const alerts: string[] = [];
+  let critical = false;
+  let degraded = false;
+
+  if (
+    snapshot.connectionState === "disconnected" ||
+    snapshot.connectionState === "failed"
+  ) {
+    alerts.push(`connection_${snapshot.connectionState}`);
+    critical = true;
+  } else if (snapshot.connectionState === "reconnecting") {
+    alerts.push("connection_reconnecting");
+    degraded = true;
+  }
+
+  if (snapshot.eventLoopLagMs > cfg.eventLoopLagCriticalMs) {
+    alerts.push(
+      `event_loop_lag_critical_${Math.round(snapshot.eventLoopLagMs)}ms`,
+    );
+    critical = true;
+  } else if (snapshot.eventLoopLagMs > cfg.eventLoopLagWarnMs) {
+    alerts.push(`event_loop_lag_warn_${Math.round(snapshot.eventLoopLagMs)}ms`);
+    degraded = true;
+  }
+
+  if (snapshot.cpu.percent > cfg.cpuCriticalPercent) {
+    alerts.push(`cpu_critical_${Math.round(snapshot.cpu.percent)}%`);
+    critical = true;
+  } else if (snapshot.cpu.percent > cfg.cpuWarnPercent) {
+    alerts.push(`cpu_warn_${Math.round(snapshot.cpu.percent)}%`);
+    degraded = true;
+  }
+
+  const memPercent =
+    snapshot.memory.heapTotal > 0
+      ? (snapshot.memory.heapUsed / snapshot.memory.heapTotal) * 100
+      : 0;
+  if (memPercent > cfg.memoryCriticalPercent) {
+    alerts.push(`memory_critical_${Math.round(memPercent)}%`);
+    critical = true;
+  } else if (memPercent > cfg.memoryWarnPercent) {
+    alerts.push(`memory_warn_${Math.round(memPercent)}%`);
+    degraded = true;
+  }
+
+  const status = critical ? "critical" : degraded ? "degraded" : "healthy";
+  return { status, alerts };
+}

package/src/hooks/notification.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111";
+const SECRET = process.env["AGENTMEMORY_SECRET"] || "";
+
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;
+  return h;
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  if (data.notification_type !== "permission_prompt") return;
+
+  const sessionId = (data.session_id as string) || "unknown";
+
+  try {
+    await fetch(`${REST_URL}/agentmemory/observe`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({
+        hookType: "notification",
+        sessionId,
+        project: data.cwd || process.cwd(),
+        cwd: data.cwd || process.cwd(),
+        timestamp: new Date().toISOString(),
+        data: {
+          notification_type: data.notification_type,
+          title: data.title,
+          message: data.message,
+        },
+      }),
+      signal: AbortSignal.timeout(2000),
+    });
+  } catch {
+    // fire and forget
+  }
+}
+
+main();

package/src/hooks/post-tool-failure.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111";
+const SECRET = process.env["AGENTMEMORY_SECRET"] || "";
+
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;
+  return h;
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  if (data.is_interrupt) return;
+
+  const sessionId = (data.session_id as string) || "unknown";
+
+  try {
+    await fetch(`${REST_URL}/agentmemory/observe`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({
+        hookType: "post_tool_failure",
+        sessionId,
+        project: data.cwd || process.cwd(),
+        cwd: data.cwd || process.cwd(),
+        timestamp: new Date().toISOString(),
+        data: {
+          tool_name: data.tool_name,
+          tool_input:
+            typeof data.tool_input === "string"
+              ? data.tool_input.slice(0, 4000)
+              : JSON.stringify(data.tool_input ?? "").slice(0, 4000),
+          error:
+            typeof data.error === "string"
+              ? data.error.slice(0, 4000)
+              : JSON.stringify(data.error ?? "").slice(0, 4000),
+        },
+      }),
+      signal: AbortSignal.timeout(3000),
+    });
+  } catch {
+    // fire and forget
+  }
+}
+
+main();

package/src/hooks/post-tool-use.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111";
+const SECRET = process.env["AGENTMEMORY_SECRET"] || "";
+
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;
+  return h;
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  const sessionId = (data.session_id as string) || "unknown";
+
+  try {
+    await fetch(`${REST_URL}/agentmemory/observe`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({
+        hookType: "post_tool_use",
+        sessionId,
+        project: data.cwd || process.cwd(),
+        cwd: data.cwd || process.cwd(),
+        timestamp: new Date().toISOString(),
+        data: {
+          tool_name: data.tool_name,
+          tool_input: data.tool_input,
+          tool_output: truncate(data.tool_output, 8000),
+        },
+      }),
+      signal: AbortSignal.timeout(3000),
+    });
+  } catch {
+    // fire and forget
+  }
+}
+
+function truncate(value: unknown, max: number): unknown {
+  if (typeof value === "string" && value.length > max) {
+    return value.slice(0, max) + "\n[...truncated]";
+  }
+  if (typeof value === "object" && value !== null) {
+    const str = JSON.stringify(value);
+    if (str.length > max) return str.slice(0, max) + "...[truncated]";
+    return value;
+  }
+  return value;
+}
+
+main();

package/src/hooks/pre-compact.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111";
+const SECRET = process.env["AGENTMEMORY_SECRET"] || "";
+
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;
+  return h;
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  const sessionId = (data.session_id as string) || "unknown";
+  const project = (data.cwd as string) || process.cwd();
+
+  if (process.env["CLAUDE_MEMORY_BRIDGE"] === "true") {
+    try {
+      await fetch(`${REST_URL}/agentmemory/claude-bridge/sync`, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // best-effort
+    }
+  }
+
+  try {
+    const res = await fetch(`${REST_URL}/agentmemory/context`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ sessionId, project, budget: 1500 }),
+      signal: AbortSignal.timeout(5000),
+    });
+
+    if (res.ok) {
+      const result = (await res.json()) as { context?: string };
+      if (result.context) {
+        process.stdout.write(result.context);
+      }
+    }
+  } catch {
+    // best effort -- don't block compaction
+  }
+}
+
+main();

package/src/hooks/pre-tool-use.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111";
+const SECRET = process.env["AGENTMEMORY_SECRET"] || "";
+
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;
+  return h;
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  const toolName = data.tool_name as string;
+  if (!toolName) return;
+
+  const fileTools = ["Edit", "Write", "Read", "Glob", "Grep"];
+  if (!fileTools.includes(toolName)) return;
+
+  const toolInput = (data.tool_input || {}) as Record<string, unknown>;
+  const files: string[] = [];
+  const fileKeys =
+    toolName === "Grep"
+      ? ["path", "file"]
+      : ["file_path", "path", "file", "pattern"];
+  for (const key of fileKeys) {
+    const val = toolInput[key];
+    if (typeof val === "string" && val.length > 0) files.push(val);
+  }
+  if (files.length === 0) return;
+
+  const terms: string[] = [];
+  if (toolName === "Grep" || toolName === "Glob") {
+    const pattern = toolInput["pattern"];
+    if (typeof pattern === "string" && pattern.length > 0) {
+      terms.push(pattern);
+    }
+  }
+
+  const sessionId = (data.session_id as string) || "unknown";
+
+  try {
+    const res = await fetch(`${REST_URL}/agentmemory/enrich`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ sessionId, files, terms, toolName }),
+      signal: AbortSignal.timeout(2000),
+    });
+
+    if (res.ok) {
+      const result = (await res.json()) as { context?: string };
+      if (result.context) {
+        process.stdout.write(result.context);
+      }
+    }
+  } catch {
+    // don't block tool execution
+  }
+}
+
+main();

package/src/hooks/prompt-submit.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const REST_URL = process.env["AGENTMEMORY_URL"] || "http://localhost:3111";
+const SECRET = process.env["AGENTMEMORY_SECRET"] || "";
+
+function authHeaders(): Record<string, string> {
+  const h: Record<string, string> = { "Content-Type": "application/json" };
+  if (SECRET) h["Authorization"] = `Bearer ${SECRET}`;
+  return h;
+}
+
+async function main() {
+  let input = "";
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return;
+  }
+
+  const sessionId = (data.session_id as string) || "unknown";
+
+  try {
+    await fetch(`${REST_URL}/agentmemory/observe`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({
+        hookType: "prompt_submit",
+        sessionId,
+        project: data.cwd || process.cwd(),
+        cwd: data.cwd || process.cwd(),
+        timestamp: new Date().toISOString(),
+        data: { prompt: data.prompt },
+      }),
+      signal: AbortSignal.timeout(3000),
+    });
+  } catch {
+    // fire and forget
+  }
+}
+
+main();