@pleri/olam-cli 0.1.204 → 0.1.206

package/memory-hooks/agentmemory-recall-trigger.mjs

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * agentmemory-recall-trigger.mjs
+ *
+ * PreToolUse hook for Claude Code — derives a prompt-context from the
+ * incoming tool event, POSTs to the bridge `/classify/recall` endpoint
+ * (Phase C2), and injects the top-3 results as additionalContext so
+ * the agent has relevant memory before executing the tool call.
+ *
+ * Hot-path SLO: p99 latency < 500ms (Phase A plan P1 row). The 500ms
+ * budget covers the bridge round-trip + the bridge → container
+ * memory_recall hop. Fail-open: any error exits 0 with no stdout —
+ * never blocks the tool loop.
+ *
+ * cwd → store routing (T4 mitigation):
+ *   Derived from process.cwd() via the same regex pattern the existing
+ *   SessionStart agentmemory-session-recall.js hook uses. The bridge
+ *   URL itself is per-store (operators set AGENTMEMORY_BRIDGE_URL per
+ *   project / per store) so cross-store leak is impossible from this
+ *   hook — the bridge it talks to is single-store by configuration.
+ *
+ * Install (operator runs manually):
+ *   $ cp packages/memory-service/hooks/agentmemory-recall-trigger.mjs \
+ *        ~/.claude/scripts/hooks/agentmemory-recall-trigger.mjs
+ *   $ packages/memory-service/scripts/install-recall-hook.sh
+ *   # the install script does the cp + the settings.json edit + cp BACKUP first
+ *
+ * Plan reference:
+ *   docs/plans/agentmemory-classifier-and-regret/phase-c-tasks.md C3
+ */
+
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Built-in tool-event filter: only fire on tool calls where recall has
+// signal. Bash + Edit + MultiEdit + Read on substantive paths qualify;
+// TodoWrite + Glob + Grep are too lightweight to justify the recall
+// round-trip.
+const RECALL_WORTHY_TOOL_NAMES = new Set([
+  'Bash', 'Edit', 'MultiEdit', 'Write', 'Read', 'NotebookEdit',
+]);
+
+// Default to the LIVE memory-service Worker — the same host the remember/write
+// path targets, so recall reads where the fleet writes. The prior default
+// (olam-agent-memory.ernestcodes.workers.dev) is a dead host (HTTP 404), which
+// made recall reach nothing. env still overrides for per-store / wrangler-dev.
+// env wins → `olam memory connect` artifact → live default. See
+// packages/cli/src/lib/memory-connection.ts (keep precedence in sync).
+function resolveBridgeUrlDefault() {
+  if (process.env.AGENTMEMORY_BRIDGE_URL) return process.env.AGENTMEMORY_BRIDGE_URL;
+  try {
+    const conn = JSON.parse(
+      readFileSync(join(homedir(), '.olam', 'memory-connection.json'), 'utf8'),
+    );
+    if (conn && typeof conn.url === 'string' && conn.url) return conn.url;
+  } catch {
+    // artifact absent / malformed — fall through
+  }
+  return 'https://atlas-agent-memory.atlas-kitchen.workers.dev';
+}
+const BRIDGE_URL = resolveBridgeUrlDefault();
+
+/**
+ * Resolve a secret file path: prefers ~/.olam/secrets/<name>,
+ * falls back to ~/.olam/<name>. Inlined here because this .mjs hook
+ * has no @olam/core dep.
+ */
+function resolveSecretPathInline(name) {
+  const olamHome = join(homedir(), '.olam');
+  const newPath = join(olamHome, 'secrets', name);
+  if (existsSync(newPath)) return newPath;
+  return join(olamHome, name);
+}
+
+/** Read a trimmed secret file by name, or '' if absent/unreadable. */
+function readSecretFile(name) {
+  try {
+    return readFileSync(resolveSecretPathInline(name), 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+// Bearer resolution (first match wins; no literal embedded):
+//   env AGENTMEMORY_BRIDGE_SECRET → env OLAM_AGENT_MEMORY_BEARER
+//   → file bridge-secret → file agent-memory-bearer → '' (no-op fail-open).
+// Empty string short-circuits callBridge() to a fail-open no-op so the hook
+// never blocks the tool loop on a missing secret.
+const BEARER =
+  process.env.AGENTMEMORY_BRIDGE_SECRET ||
+  process.env.OLAM_AGENT_MEMORY_BEARER ||
+  readSecretFile('bridge-secret') ||
+  readSecretFile('agent-memory-bearer') ||
+  '';
+const RECALL_TIMEOUT_MS = 1500;
+
+/**
+ * Derive the recall prompt from a Claude Code PreToolUse event. Each
+ * tool gets a tailored prompt shape:
+ *   Bash      → `$ <command>`
+ *   Edit      → `edit <file_path>: <truncated new_string>`
+ *   MultiEdit → `multi-edit <file_path>`
+ *   Write     → `wrote <file_path>`
+ *   Read      → `read <file_path>`
+ *   default   → JSON.stringify(tool_input).slice(0, 200)
+ */
+export function derivePrompt(event) {
+  if (!event || typeof event !== 'object') return '';
+  const toolName = event.tool_name;
+  const ti = event.tool_input ?? event.toolInput ?? null;
+  if (!RECALL_WORTHY_TOOL_NAMES.has(toolName)) return '';
+
+  if (toolName === 'Bash') {
+    const cmd = ti?.command;
+    return typeof cmd === 'string' ? `$ ${cmd}` : '';
+  }
+  if (toolName === 'Edit') {
+    const fp = ti?.file_path ?? '';
+    const ns = typeof ti?.new_string === 'string'
+      ? ti.new_string.slice(0, 200)
+      : '';
+    return `edit ${fp}: ${ns}`;
+  }
+  if (toolName === 'MultiEdit') {
+    return `multi-edit ${ti?.file_path ?? ''}`;
+  }
+  if (toolName === 'Write') {
+    return `wrote ${ti?.file_path ?? ''}`;
+  }
+  if (toolName === 'Read') {
+    return `read ${ti?.file_path ?? ''}`;
+  }
+  if (toolName === 'NotebookEdit') {
+    return `edit ${ti?.notebook_path ?? ''}`;
+  }
+  return '';
+}
+
+/**
+ * Call the bridge /classify/recall endpoint. Returns the parsed
+ * response body or null on any failure (fail-open).
+ */
+async function callBridge(prompt, cwd) {
+  if (!prompt || !BRIDGE_URL || !BEARER) return null;
+  try {
+    const res = await fetch(`${BRIDGE_URL}/classify/recall`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${BEARER}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ prompt, cwd, limit: 3 }),
+      signal: AbortSignal.timeout(RECALL_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch (err) {
+    // Fail-open: one-line breadcrumb to stderr, then null (no output, no block).
+    process.stderr.write(`[agentmemory-recall-trigger] recall failed: ${err?.message ?? err}\n`);
+    return null;
+  }
+}
+
+/**
+ * Format the recall response as a markdown additionalContext block
+ * for hookSpecificOutput. Returns empty string when no results so the
+ * hook emits no output and the agent sees no noise.
+ */
+export function formatAdditionalContext(response, prompt) {
+  if (!response || !Array.isArray(response.results) || response.results.length === 0) {
+    return '';
+  }
+  const lines = [
+    `## Recalled from agent memory (prompt: "${prompt.slice(0, 80)}${prompt.length > 80 ? '…' : ''}")`,
+    '',
+  ];
+  for (const r of response.results) {
+    const title = r.title || r.id || '(untitled)';
+    const score = typeof r.score === 'number' ? r.score.toFixed(1) : '?';
+    const conv = typeof r.conviction === 'number' ? r.conviction : '?';
+    const sim = typeof r.similarity === 'number' ? r.similarity.toFixed(2) : '?';
+    lines.push(`- [score ${score} | conv ${conv} | sim ${sim}] ${title}`);
+    if (r.contentExcerpt) {
+      lines.push(`  ${r.contentExcerpt}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+async function main() {
+  let event = {};
+  try {
+    event = JSON.parse(readFileSync(0, 'utf-8'));
+  } catch {
+    return; // unparseable stdin → fail-open
+  }
+
+  const prompt = derivePrompt(event);
+  if (!prompt) return;
+
+  const response = await callBridge(prompt, event.cwd ?? process.cwd());
+  const additionalContext = formatAdditionalContext(response, prompt);
+  if (!additionalContext) return;
+
+  const count = response?.results?.length ?? 0;
+  process.stderr.write(
+    `\x1b[34m[🧠⇣ Memory recalled]\x1b[0m (${count} memories · "${prompt.slice(0, 60)}${prompt.length > 60 ? '…' : ''}")\n`
+  );
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext,
+    },
+  }));
+}
+
+// Run main only when invoked directly (allows test files to import the
+// pure functions above without firing the hook side-effects). Compare
+// REAL paths (not raw argv vs file://) so the hook still fires when
+// resolved through a symlink — toolbox sync mounts these scripts via
+// $HOME/.claude/scripts/agentmemory-classifier/ which is a symlink to the
+// canonical atlas-toolbox path. Pre-fix, the raw-string compare missed
+// the symlink and main() never ran.
+function isDirectInvocation() {
+  try {
+    const argvPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+    const metaPath = realpathSync(fileURLToPath(import.meta.url));
+    return argvPath === metaPath;
+  } catch {
+    return false;
+  }
+}
+if (isDirectInvocation()) {
+  main().catch(() => process.exit(0));
+}

package/memory-hooks/agentmemory-reflect-cite.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+/**
+ * agentmemory-reflect-cite.mjs — the Phase D citation floor WIRING (Stop hook).
+ *
+ * This is the session-end backstop to the explicit `memory_reinforce` tool. At
+ * Stop it:
+ *   1. derives the SAME session key the recall hook wrote under
+ *      ({@link sessionKeyFor} — keyed on `session_id`, identical derivation at
+ *      both ends; a mismatch would be a silent no-op, so it is inlined from the
+ *      same source as the recall hook and covered by a key-parity test),
+ *   2. reads the surfaced set from the recall-log ({@link collectSurfaced}),
+ *   3. builds the scan text from the agent's OWN output/edits in the transcript,
+ *      EXCLUDING the injected recall-context block (the self-citation guard —
+ *      see {@link buildScanText}),
+ *   4. runs {@link detectCitedMemories} (precision-biased contiguous-distinctive
+ *      -run match), and
+ *   5. POSTs the cited ids to `/classify/reinforce` with `source: 'citation'`.
+ *
+ * The bridge enforces the FIX-1 abuse guards, so cited ids pass the recalled-gate
+ * by construction (they were surfaced this session → recorded in last_recalled_at
+ * by the recall path) and the cooldown still bounds re-stamping.
+ *
+ * Fail-open in every branch: a missing bearer, an unreadable transcript, an empty
+ * recall-log, or a bridge error all exit 0 with no output. The floor is a
+ * best-effort signal and must NEVER block session end.
+ *
+ * ESM (.mjs) so it can import recall-log.mjs + reinforce-citation logic directly
+ * and be unit-tested via node:test. The citation DETECTOR lives in TS
+ * (src/reinforce-citation.ts); its small, dependency-free logic is mirrored here
+ * as an inlined ESM copy for the same no-build reason the recall hook inlines
+ * deriveRecallQuery (the .ts remains the source of truth + carries its own
+ * adversarial unit tests).
+ */
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+import { collectSurfaced, sessionKeyFor, sweepStaleLogs } from './recall-log.mjs';
+
+// ---------------------------------------------------------------------------
+// Bridge config — mirrors agentmemory-session-recall.js so recall + cite agree.
+// ---------------------------------------------------------------------------
+
+// env wins → `olam memory connect` artifact → live default. See
+// packages/cli/src/lib/memory-connection.ts (keep precedence in sync).
+function resolveBridgeUrlDefault() {
+  if (process.env.AGENTMEMORY_BRIDGE_URL) return process.env.AGENTMEMORY_BRIDGE_URL;
+  try {
+    const conn = JSON.parse(
+      readFileSync(join(homedir(), '.olam', 'memory-connection.json'), 'utf8'),
+    );
+    if (conn && typeof conn.url === 'string' && conn.url) return conn.url;
+  } catch {
+    // artifact absent / malformed — fall through
+  }
+  return 'https://atlas-agent-memory.atlas-kitchen.workers.dev';
+}
+const BRIDGE_URL = resolveBridgeUrlDefault();
+
+function resolveSecretPath(name) {
+  const olamHome = join(homedir(), '.olam');
+  const newPath = join(olamHome, 'secrets', name);
+  try {
+    readFileSync(newPath);
+    return newPath;
+  } catch {
+    return join(olamHome, name);
+  }
+}
+
+function readSecretFile(name) {
+  try {
+    return readFileSync(resolveSecretPath(name), 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+const BEARER =
+  process.env.AGENTMEMORY_BRIDGE_SECRET ||
+  process.env.OLAM_AGENT_MEMORY_BEARER ||
+  readSecretFile('bridge-secret') ||
+  readSecretFile('agent-memory-bearer') ||
+  '';
+
+// ---------------------------------------------------------------------------
+// Citation detector (inlined ESM mirror of src/reinforce-citation.ts).
+// Kept structurally identical — the .ts is the source of truth + unit tests.
+// ---------------------------------------------------------------------------
+
+const MIN_SHINGLE = 4;
+const MIN_TITLE_TOKENS = 4;
+
+const STOPWORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'if', 'then', 'else', 'of', 'to', 'in',
+  'on', 'at', 'by', 'for', 'with', 'as', 'is', 'are', 'was', 'were', 'be',
+  'been', 'being', 'it', 'its', 'this', 'that', 'these', 'those', 'i', 'you',
+  'we', 'they', 'he', 'she', 'do', 'does', 'did', 'so', 'not', 'no', 'can',
+  'will', 'would', 'should', 'could', 'has', 'have', 'had', 'from', 'into',
+  'out', 'up', 'down', 'over', 'under', 'about', 'than', 'too', 'very', 'just',
+  'use', 'used', 'using', 'via', 'per', 'when', 'while', 'how', 'what', 'why',
+]);
+
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 0);
+}
+function distinctiveTokens(text) {
+  return tokenize(text).filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+function distinctiveOf(tokens) {
+  return tokens.filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+function containsRun(haystackTokens, needleTokens) {
+  if (needleTokens.length === 0 || needleTokens.length > haystackTokens.length) return false;
+  for (let i = 0; i + needleTokens.length <= haystackTokens.length; i += 1) {
+    let match = true;
+    for (let j = 0; j < needleTokens.length; j += 1) {
+      if (haystackTokens[i + j] !== needleTokens[j]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) return true;
+  }
+  return false;
+}
+function hasShingleMatch(sourceTokens, outputTokens) {
+  if (sourceTokens.length < MIN_SHINGLE) return false;
+  for (let i = 0; i + MIN_SHINGLE <= sourceTokens.length; i += 1) {
+    if (containsRun(outputTokens, sourceTokens.slice(i, i + MIN_SHINGLE))) return true;
+  }
+  return false;
+}
+function isMemoryCited(memory, outputTokens) {
+  const outputDistinctive = distinctiveOf(outputTokens);
+  if (outputDistinctive.length === 0) return false;
+  const titleTokens = distinctiveTokens(memory.title ?? '');
+  if (titleTokens.length >= MIN_TITLE_TOKENS && containsRun(outputDistinctive, titleTokens)) return true;
+  if (hasShingleMatch(titleTokens, outputDistinctive)) return true;
+  const excerptTokens = distinctiveTokens(memory.excerpt ?? '');
+  if (hasShingleMatch(excerptTokens, outputDistinctive)) return true;
+  return false;
+}
+
+/**
+ * Return the subset of `surfaced` literally referenced in `agentOutputText`.
+ * Order-preserving, de-duplicated by id. (Mirror of the TS export.)
+ */
+export function detectCitedMemories(surfaced, agentOutputText) {
+  if (!Array.isArray(surfaced) || surfaced.length === 0) return [];
+  if (typeof agentOutputText !== 'string' || agentOutputText.length === 0) return [];
+  const outputTokens = tokenize(agentOutputText);
+  if (outputTokens.length === 0) return [];
+  const cited = [];
+  const seen = new Set();
+  for (const m of surfaced) {
+    if (!m || typeof m.id !== 'string' || seen.has(m.id)) continue;
+    if (isMemoryCited(m, outputTokens)) {
+      cited.push(m);
+      seen.add(m.id);
+    }
+  }
+  return cited;
+}
+
+// ---------------------------------------------------------------------------
+// Self-citation guard — extract the agent's OWN output, EXCLUDING the recall block.
+// ---------------------------------------------------------------------------
+
+/**
+ * Markers that identify the injected recall-context block (from
+ * agentmemory-session-recall.js + agentmemory-recall-trigger.mjs). Any text
+ * block containing one of these is the SYSTEM's injected context — NOT the
+ * agent's own output — and must be excluded from the citation scan, or every
+ * surfaced memory self-matches its own injected title (the self-citation loop).
+ */
+export const RECALL_BLOCK_MARKERS = [
+  'Recalled from agent memory',
+  'call `memory_reinforce`',
+  'call memory_reinforce',
+];
+
+function looksLikeRecallBlock(text) {
+  return RECALL_BLOCK_MARKERS.some((m) => text.includes(m));
+}
+
+/**
+ * Build the citation-scan text from a parsed transcript (array of JSONL entries).
+ *
+ * Includes ONLY the agent's OWN output:
+ *   - `assistant` message `text` blocks (the agent's prose), and
+ *   - `assistant` `tool_use` input strings (the edits/commands the agent issued)
+ *
+ * Excludes — by construction and by marker — anything that is NOT the agent's own
+ * authored output:
+ *   - all `user` messages + `tool_result` blocks (inputs / tool outputs the agent
+ *     merely received, including the recalled memory content itself),
+ *   - any assistant text block that carries a {@link RECALL_BLOCK_MARKERS} marker
+ *     (defensive: the injected recall block is normally a system/user-context
+ *     injection, but if a transcript variant echoes it into an assistant turn we
+ *     still strip it).
+ *
+ * This is THE self-citation guard: the scanned text never contains the injected
+ * titles, so a surfaced memory can only be "cited" if the AGENT independently
+ * wrote its distinctive tokens.
+ */
+export function buildScanText(transcriptEntries) {
+  if (!Array.isArray(transcriptEntries)) return '';
+  const parts = [];
+  for (const entry of transcriptEntries) {
+    if (!entry || entry.type !== 'assistant') continue;
+    const msg = entry.message;
+    const content = msg && msg.content;
+    if (typeof content === 'string') {
+      if (!looksLikeRecallBlock(content)) parts.push(content);
+      continue;
+    }
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (!block || typeof block !== 'object') continue;
+      if (block.type === 'text' && typeof block.text === 'string') {
+        if (!looksLikeRecallBlock(block.text)) parts.push(block.text);
+      } else if (block.type === 'tool_use' && block.input && typeof block.input === 'object') {
+        // The agent's edits/commands ARE its output. Pull the string-valued
+        // fields (new_string / content / command / etc.); skip the recall block
+        // if a tool input somehow echoes it.
+        for (const v of Object.values(block.input)) {
+          if (typeof v === 'string' && v.length > 0 && !looksLikeRecallBlock(v)) parts.push(v);
+        }
+      }
+    }
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Parse a transcript JSONL file into an array of entries. Fail-open: returns []
+ * on any read/parse error (the floor is best-effort).
+ */
+export function readTranscript(transcriptPath) {
+  if (typeof transcriptPath !== 'string' || transcriptPath.length === 0) return [];
+  let raw;
+  try {
+    raw = readFileSync(transcriptPath, 'utf8');
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed));
+    } catch {
+      // skip a malformed line — never abort the whole parse
+    }
+  }
+  return entries;
+}
+
+async function postReinforce(memoryIds) {
+  const res = await fetch(`${BRIDGE_URL}/classify/reinforce`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${BEARER}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      memoryIds,
+      source: 'citation',
+      reason: 'session-end citation floor: literally referenced in agent output',
+    }),
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+
+async function main() {
+  let event = {};
+  try {
+    event = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return; // unparseable stdin → fail-open
+  }
+
+  // No bearer → no-op fail-open (matches the recall hook).
+  if (!BEARER) return;
+
+  // SAME session-key derivation as the recall hook — keyed on session_id. A
+  // mismatch here would silently union nothing; the key-parity test pins this.
+  const sessionKey = sessionKeyFor(event);
+  const surfaced = collectSurfaced(sessionKey);
+  if (!surfaced || surfaced.length === 0) {
+    sweepStaleLogs(); // opportunistic GC even when there's nothing to cite
+    return;
+  }
+
+  const transcript = readTranscript(event.transcript_path);
+  const scanText = buildScanText(transcript);
+  if (!scanText) {
+    sweepStaleLogs();
+    return;
+  }
+
+  const cited = detectCitedMemories(surfaced, scanText);
+  if (cited.length === 0) {
+    sweepStaleLogs();
+    return;
+  }
+
+  try {
+    await postReinforce(cited.map((m) => m.id));
+  } catch (err) {
+    process.stderr.write(`[agentmemory-reflect-cite] reinforce failed: ${err?.message ?? err}\n`);
+  }
+  sweepStaleLogs();
+}
+
+function isDirectInvocation() {
+  try {
+    const argvPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+    const metaPath = realpathSync(fileURLToPath(import.meta.url));
+    return argvPath === metaPath;
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation()) {
+  main().catch(() => process.exit(0));
+}