@fusengine/harness 0.1.90 → 0.1.92

package/src/runtime/lifecycle/failure-lesson.ts

@@ -0,0 +1,55 @@
+/**
+ * @module failure-lesson
+ * PostToolUseFailure handler: keep the failure log, record the failure in the
+ * one-shot metric, and inject the ONE most-specific lesson whose `error:` trigger
+ * matches the failure message — reusing the PreToolUse {@link lessonFor} index and
+ * its cooldown (idempotent under the ~11-process fan-out). Fail-open throughout.
+ *
+ * Claude-Code-only in the sense that no equivalent `PostToolUseFailure` hook
+ * exists on Codex or Hermes — but Cursor's own `postToolUseFailure` DOES
+ * arrive here too, via `lifecycle-bridge.ts`'s `lifecycleStdout` translating
+ * the wire event name and forwarding to `dispatchLifecycle`'s
+ * `"PostToolUseFailure"` case (see `handle.ts`'s `cursorRawPayloadProjection`
+ * for how `data.tool_name` below arrives already canonicalized on Cursor).
+ * @packageDocumentation
+ */
+import { homedir } from "node:os";
+import { contextResponse } from "../../adapters/claude";
+import { lessonFor } from "../../policy/lessons/lesson-gate";
+import { lessonsFileFor } from "./lessons/state";
+import { projectRoot } from "../../util/project-root";
+import { oncePerWindow } from "../inject-dedup";
+import { defaultStateDir } from "../paths";
+import { recordFailure } from "../../tracking/one-shot-failure";
+import { logToolFailure } from "./tool-failure";
+import type { OncePerWindow } from "../../policy/lessons/types";
+
+/** The failure message across the documented `error` field and defensive fallbacks; "" when none. */
+function failureError(data: Record<string, unknown>): string {
+  const raw = data.error ?? data.tool_error ?? data.tool_output;
+  if (typeof raw === "string") return raw;
+  return raw != null ? JSON.stringify(raw) : "";
+}
+
+/**
+ * Handle PostToolUseFailure: log the failure, tally it per tool, and inject the
+ * matching `error:`-triggered lesson as `additionalContext` ("" when none).
+ * @param data - The raw PostToolUseFailure payload (`tool_name`, `error`, `session_id`).
+ * @param cwd - Project root.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @param once - Cooldown gate (injected for tests; defaults to {@link oncePerWindow}).
+ * @returns The native hook stdout, or "" when nothing to inject.
+ */
+export function failureLessonContext(data: Record<string, unknown>, cwd: string, home: string = homedir(), now: number = Date.now(), once: OncePerWindow = oncePerWindow): string {
+  logToolFailure(data, home, now);
+  const tool = typeof data.tool_name === "string" ? data.tool_name : "unknown";
+  const sessionId = typeof data.session_id === "string" ? data.session_id : undefined;
+  try { recordFailure(tool, { now, dir: defaultStateDir(cwd), sessionId }); } catch { /* metric never breaks the hook */ }
+  const errorMsg = failureError(data);
+  if (!errorMsg) return "";
+  // tool="" + empty input isolates matching to the `error:` regex (rank 1),
+  // reusing the PreToolUse gate's index + cooldown — no second lesson engine.
+  const lesson = lessonFor("", {}, { file: lessonsFileFor(projectRoot(cwd)), once, prevError: errorMsg });
+  return lesson?.reason ? contextResponse("PostToolUseFailure", lesson.reason) : "";
+}

package/src/runtime/lifecycle/index.ts

@@ -0,0 +1,34 @@
+export * from "./session-start";
+export * from "./inject-rules";
+export * from "./solid-detect";
+export * from "./check-file-size";
+export * from "./validate-solid";
+export * from "./validate-tailwind";
+export * from "./subagent-cache";
+export * from "./agent-memory";
+export * from "./teammate-idle";
+export * from "./tool-failure";
+export * from "./pre-compact";
+export * from "./session-end";
+export * from "./instructions-loaded";
+export * from "./track-changes";
+export * from "./post-edit-ts";
+export * from "./dispatch";
+export * from "./post-tracking";
+export * from "./changelog-research";
+export * from "./cartographer/session-start";
+export * from "./cartographer/project-map";
+export * from "./cartographer/track-enrichment";
+export * from "./cartographer/write-tree";
+export * from "./cartographer/merge";
+export * from "./cartographer/fs-util";
+export * from "./security/check-skill";
+export * from "./security/track-skill-read";
+export * from "./security/track-mcp";
+export * from "./security/skill-state";
+export * from "./lessons/dispatch";
+export * from "./lessons/state";
+export * from "./memory/dispatch";
+export * from "./seo/post-tool-use";
+export * from "./cartographer/ecosystem-map";
+export * from "./cartographer/write-plugin-map";

package/src/runtime/lifecycle/inject-rules.ts

@@ -0,0 +1,50 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderInform } from "../inform";
+import { rulesInAgentsMd } from "./kimi-rules-native";
+
+/** Read & concatenate all `*.md` files (sorted) under `rulesDir`. */
+export function readRules(rulesDir: string): string {
+  if (!existsSync(rulesDir)) return "";
+  let names: string[];
+  try {
+    names = readdirSync(rulesDir).filter((n) => n.endsWith(".md")).sort();
+  } catch {
+    return "";
+  }
+  const parts: string[] = [];
+  for (const name of names) {
+    try {
+      parts.push(readFileSync(join(rulesDir, name), "utf-8"));
+    } catch {
+      /* skip unreadable rule file */
+    }
+  }
+  return parts.join("\n\n");
+}
+
+/**
+ * Build the rules injection for claude-rules (SessionStart, UserPromptSubmit,
+ * SubagentStart): read `<pluginRoot>/rules/*.md` and emit via {@link renderInform}
+ * (Claude-shaped `additionalContext`, or raw text for kimi). Tags the output
+ * with the *actual* `hookEventName` — the spec requires it to match the firing
+ * event (a hardcoded "SessionStart" is non-conforming and may be dropped on
+ * UserPromptSubmit/SubagentStart).
+ *
+ * On kimi's `UserPromptSubmit` specifically, when the corpus is already fenced
+ * inside `<kimiHome>/AGENTS.md` (native load, {@link rulesInAgentsMd}), only the
+ * notice is emitted — the re-injected corpus would otherwise dump into the
+ * user's terminal on every single prompt for no model-context benefit.
+ * `SessionStart`/`SubagentStart` always keep the full corpus (session bootstrap
+ * / sub-agent contexts need it regardless of the native AGENTS.md load).
+ * @param pluginRoot - `CLAUDE_PLUGIN_ROOT` of the claude-rules plugin.
+ * @param event - The firing hook event name (e.g. "SessionStart").
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function injectRules(pluginRoot: string, event: string, id: string = "claude-code"): string {
+  const content = readRules(join(pluginRoot, "rules"));
+  if (!content) return "";
+  if (id === "kimi" && event === "UserPromptSubmit" && rulesInAgentsMd()) return "rules 00-08 injected";
+  return renderInform(id, event, content, "rules 00-08 injected");
+}

package/src/runtime/lifecycle/instructions-loaded.ts

@@ -0,0 +1,22 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Handle InstructionsLoaded: append `load_reason | memory_type | file_path` to
+ * the per-session debug log. Ports `instructions-loaded/validate-rules-loaded.py`.
+ * No stdout (logging only; InstructionsLoaded has no decision control).
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ */
+export function validateRulesLoaded(data: Record<string, unknown>, home: string = homedir()): void {
+  const filePath = String(data.file_path ?? "");
+  const loadReason = String(data.load_reason ?? "");
+  const memoryType = String(data.memory_type ?? "");
+  const sessionId = String(data.session_id ?? "unknown");
+  const dir = join(home, ".claude", "logs", "instructions-loaded");
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, `${sessionId}.log`), `${loadReason} | ${memoryType} | ${filePath}\n`, "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/kimi-rules-native.ts

@@ -0,0 +1,44 @@
+/**
+ * Guard for the kimi notice-only rules injection. Kimi Code CLI has no
+ * model-only hook channel (`src/runtime/inform.ts`) — every `UserPromptSubmit`
+ * stdout is BOTH appended to the model's context AND rendered raw in the
+ * user's terminal. `injectRules` (`inject-rules.ts`) normally re-injects the
+ * full ~18 Ko rules corpus on every prompt; when the installer has already
+ * merged that same corpus into `<kimiHome>/AGENTS.md` — which Kimi loads
+ * natively at session start via its documented `${agents_md}` mechanism,
+ * independent of hooks — the re-injection is pure noise the user has to
+ * scroll past. Confirmed present, fenced, in the local install:
+ * `~/.kimi-code/AGENTS.md:87` / `:335`.
+ *
+ * Fail-safe semantics: fences absent, file absent, or any read error ⟹
+ * `false` — the caller then falls back to the full corpus. A dump is
+ * verbose but never wrong; a false `true` would silently drop the rules.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { harnessHome } from "../../config/home-dir";
+
+/** Opening fence the fusengine installer writes around the merged corpus. */
+const FENCE_START = "<!-- fusengine:kimi-rules:start -->";
+
+/** Closing fence the fusengine installer writes around the merged corpus. */
+const FENCE_END = "<!-- fusengine:kimi-rules:end -->";
+
+/**
+ * Check whether the kimi rules corpus is already present, fenced, inside
+ * `<kimiHome>/AGENTS.md`.
+ * @param home - Kimi home dir override (defaults to `harnessHome("kimi")`,
+ * which honors `KIMI_CODE_HOME`).
+ * @returns `true` only when both fences are found in a readable file.
+ */
+export function rulesInAgentsMd(home?: string): boolean {
+  try {
+    const kimiHome = home ?? harnessHome("kimi");
+    const agentsMd = join(kimiHome, "AGENTS.md");
+    if (!existsSync(agentsMd)) return false;
+    const content = readFileSync(agentsMd, "utf-8");
+    return content.includes(FENCE_START) && content.includes(FENCE_END);
+  } catch {
+    return false;
+  }
+}

package/src/runtime/lifecycle/lessons/dispatch.ts

@@ -0,0 +1,88 @@
+/**
+ * fuse-lessons scope dispatch (TS port of the 4 handler scripts). Routes by
+ * event: SessionStart/SubagentStart inject `MEMORY/LESSON.md`; Stop reminds the
+ * stopping session about ITS OWN projects with unsaved code edits; PostToolUse
+ * marks the write to arm/silence the throttle. The reminder + mark logic (incl.
+ * the per-`session_id` scoping that fixes the multi-session misdirection) lives
+ * in {@link module:runtime/lifecycle/lessons/reminder}; this module keeps the
+ * event router + lesson-file injection. Non-fatal by design.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { renderInform } from "../../inform";
+import { projectRoot } from "../../../util/project-root";
+import { atomicWrite } from "../../../util/json-io";
+import { curateLessons } from "../aipilot/curate-lessons";
+import { compressInjection } from "../aipilot/lesson-inject";
+import { capFragment } from "../../inject-budget";
+import { lessonsArchiveFileFor, lessonsFileFor } from "./state";
+import { markWrite, remindWrite } from "./reminder";
+
+/**
+ * Persist a curation ATOMICALLY and ARCHIVE-FIRST for zero-loss: prepend the
+ * moved bullets to LESSON-archive.md, THEN rewrite LESSON.md. On ANY write error
+ * the original file is left untouched (returns `original`) so a bullet is never
+ * lost — a rare archive-then-trim-fail leaves a duplicate (never a loss), which
+ * the next dedup pass reconciles.
+ */
+function persistCuration(file: string, root: string, curated: string, archive: string, original: string): string {
+  try {
+    if (archive) {
+      const af = lessonsArchiveFileFor(root);
+      const prev = existsSync(af) ? readFileSync(af, "utf-8") : "";
+      atomicWrite(af, prev ? `${archive}\n${prev}` : archive);
+    }
+    atomicWrite(file, curated);
+    return curated;
+  } catch { return original; }
+}
+
+/**
+ * Inject `MEMORY/LESSON.md` for `event`. Mechanical curation (dedup + cap→archive)
+ * rewrites the FILE; the injected BLOCK is then COMPRESSED (newest bullets whole,
+ * older ones distilled to their rule) so a growing file never inflates the
+ * SessionStart/SubagentStart context. A hard {@link capFragment} budget is the
+ * last-resort backstop on top of compression — the regression that motivated it
+ * was this exact block silently reaching ~44k tokens. Any curation report
+ * surfaces via systemMessage.
+ */
+function injectMemory(cwd: string, event: string, now: number, id: string): string {
+  const root = projectRoot(cwd);
+  const file = lessonsFileFor(root);
+  if (!existsSync(file)) return "";
+  let content = "";
+  try { content = readFileSync(file, "utf-8").trim(); } catch { return ""; }
+  if (!content) return "";
+  const { content: curated, archive, report } = curateLessons(content, now, root);
+  if (curated !== content) content = persistCuration(file, root, curated, archive, content);
+  const body = capFragment("lessons", compressInjection(content));
+  const ctx = `Project lessons — never reproduce these:\n${body}\nYou may append OR refine/merge/dedupe bullets in MEMORY/LESSON.md — keep it terse.`;
+  const notice = report ? `lessons injected\nLESSON.md curation:\n${report}` : "lessons injected";
+  return renderInform(id, event, ctx, notice);
+}
+
+/**
+ * Route a fuse-lessons event to its handler. Returns the native stdout for
+ * context-injecting events (SessionStart/SubagentStart/UserPromptSubmit inject
+ * MEMORY/LESSON.md, Stop reminds) or "" for the side-effect-only PostToolUse mark.
+ * @param event - The raw hook event name.
+ * @param payload - The raw hook payload.
+ * @param cwd - Project root for memory injection.
+ * @param now - Clock.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native stdout (possibly empty).
+ */
+export function dispatchLessons(event: string, payload: Record<string, unknown>, cwd: string, now: number, id: string = "claude-code"): string {
+  switch (event) {
+    case "SessionStart":
+    case "SubagentStart":
+    case "UserPromptSubmit":
+      return injectMemory(cwd, event, now, id);
+    case "Stop":
+      return remindWrite(payload, now);
+    case "PostToolUse":
+      markWrite(payload, now);
+      return "";
+    default:
+      return "";
+  }
+}

package/src/runtime/lifecycle/lessons/reminder.ts

@@ -0,0 +1,89 @@
+/**
+ * fuse-lessons write-mark + Stop-reminder, scoped by `session_id` when present.
+ *
+ * WITH a session id (normal Claude Code): each `(session, root)` pair carries
+ * its own edit/reminder throttle in {@link module:memory/session-roots}, so a
+ * Stop lists and silences ONLY the roots THAT session edited — concurrent
+ * sessions on different projects never cross-remind nor steal each other's
+ * throttle. WITHOUT a usable session id (a harness that omits it, or the legacy
+ * on-disk state) it falls back to the original mono-session behavior: the global
+ * flat root registry + the per-project `MEMORY/state.json` throttle.
+ */
+import { dirname, resolve } from "node:path";
+import { contextResponse } from "../../../adapters/claude";
+import { sanitizeSessionId } from "../../home-state";
+import { addRoot, readRoots } from "../../../memory/registry";
+import { collectSessionPending, markSessionRoot } from "../../../memory/session-roots";
+import { nowStamp, readState, setStateField, throttleMs } from "../../../memory/state";
+import { isCodeFile, projectRootOrNull } from "../../../util/project-root";
+import { lessonsStateFileFor } from "./state";
+
+/** Sanitized session id from a raw hook payload, or null (→ legacy fallback). */
+function sessionOf(payload: Record<string, unknown>): string | null {
+  return sanitizeSessionId(payload.session_id);
+}
+
+/** Legacy (no session id): pending roots across the global flat registry. */
+function collectLegacyPending(now: number, window: number): string[] {
+  const pending: string[] = [];
+  for (const root of readRoots()) {
+    const stateFile = lessonsStateFileFor(root);
+    const { lastRemindedAt, lastCodeEditAt } = readState(stateFile);
+    if (lastCodeEditAt <= lastRemindedAt) continue;
+    if (now - lastRemindedAt < window) continue;
+    pending.push(root);
+    setStateField(stateFile, "lastRemindedAt", now);
+  }
+  return pending;
+}
+
+/** Stop reminder body listing each pending project's lessons file. */
+function reminderText(pending: string[]): string {
+  const stamp = nowStamp();
+  const targets = pending.map((r) => `- ${r}/MEMORY/LESSON.md`).join("\n");
+  return `Before ending: if this session hit a mistake/blocker worth never ` +
+    `reproducing, append 1-3 COMPACT bullets OR sharpen/merge existing ones ` +
+    `(format \`- [${stamp}] what went wrong → do instead\`, use exactly this ` +
+    `timestamp) in each project's lessons file below. Skip if nothing ` +
+    `notable.\n${targets}`;
+}
+
+/**
+ * Stop: emit one reminder covering the stopping session's pending projects.
+ * @param payload - Raw hook payload (`session_id` selects the scoped path).
+ * @param now - Clock.
+ * @returns Native Stop stdout, or "" when nothing is pending.
+ */
+export function remindWrite(payload: Record<string, unknown>, now: number): string {
+  const window = throttleMs();
+  const sid = sessionOf(payload);
+  const pending = sid ? collectSessionPending(sid, now, window) : collectLegacyPending(now, window);
+  if (pending.length === 0) return "";
+  return contextResponse("Stop", reminderText(pending));
+}
+
+/**
+ * PostToolUse: record the edit against the throttle. A code file arms the
+ * reminder; writing `MEMORY/LESSON.md` silences it (the lesson was just saved).
+ * Session-scoped when `session_id` is present, else the legacy global path.
+ * @param payload - Raw hook payload (`tool_input.file_path`, `session_id`).
+ * @param now - Clock.
+ */
+export function markWrite(payload: Record<string, unknown>, now: number): void {
+  const input = payload.tool_input as { file_path?: string } | undefined;
+  if (!input?.file_path) return;
+  const abs = resolve(input.file_path);
+  const root = projectRootOrNull(dirname(abs));
+  if (!root) return;
+  const isLesson = abs === resolve(root, "MEMORY", "LESSON.md");
+  if (!isLesson && !isCodeFile(abs)) return;
+  const sid = sessionOf(payload);
+  if (sid) {
+    markSessionRoot(sid, root, isLesson ? "remindedAt" : "editedAt", now);
+  } else if (isLesson) {
+    setStateField(lessonsStateFileFor(root), "lastRemindedAt", now);
+  } else {
+    setStateField(lessonsStateFileFor(root), "lastCodeEditAt", now);
+    addRoot(root);
+  }
+}

package/src/runtime/lifecycle/lessons/state.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-project lessons paths. The `fuse-lessons` plugin stores its lessons under
+ * `<root>/MEMORY/` (NOT the harness `.harness/memory/`), so these two path
+ * helpers override the layout while ALL state/gitignore/throttle logic is
+ * reused from `src/memory` (`setStateField`, `ensureMemoryGitignore`,
+ * `readState`, `nowStamp`, `throttleMs`).
+ */
+import { join } from "node:path";
+
+/** Absolute `<root>/MEMORY/LESSON.md` — the curated, committable lessons file. */
+export function lessonsFileFor(root: string): string {
+  return join(root, "MEMORY", "LESSON.md");
+}
+
+/** Absolute `<root>/MEMORY/LESSON-archive.md` — cold storage for capped-out bullets. */
+export function lessonsArchiveFileFor(root: string): string {
+  return join(root, "MEMORY", "LESSON-archive.md");
+}
+
+/** Absolute `<root>/MEMORY/state.json` — machine-local throttle counter. */
+export function lessonsStateFileFor(root: string): string {
+  return join(root, "MEMORY", "state.json");
+}

package/src/runtime/lifecycle/memory/agent-lesson.ts

@@ -0,0 +1,35 @@
+/**
+ * SubagentStop memory handler. Ports `capture-agent-lesson.py`: log a finished
+ * agent's conclusion and, when salient enough, store it as a Graphiti episode.
+ * Skips explore-codebase/websearch agents and errored exits.
+ */
+import { isoUtc } from "../security/skill-state";
+import { postEpisode } from "./client";
+import { SALIENCE_THRESHOLD, agentSeverity, salience } from "./salience";
+import { appendMemoryLog } from "./state";
+
+/** Agents whose conclusions are never captured. */
+const SKIP = new Set(["explore-codebase", "websearch"]);
+
+/**
+ * Handle SubagentStop: log + maybe store the agent's conclusion. Side-effect
+ * only (no stdout).
+ * @param payload - The raw hook payload.
+ * @param now - Clock.
+ */
+export async function captureAgentLesson(payload: Record<string, unknown>, now: number): Promise<void> {
+  const name = typeof payload.agent_name === "string" ? payload.agent_name : "unknown";
+  const lastMsg = typeof payload.last_assistant_message === "string" ? payload.last_assistant_message : "";
+  const exitReason = typeof payload.exit_reason === "string" ? payload.exit_reason : "unknown";
+  if (!lastMsg || exitReason === "error" || SKIP.has(name)) return;
+  const lesson = lastMsg.slice(0, 1000);
+  const ts = isoUtc(now);
+  appendMemoryLog("agent-lessons.log", `[${ts}] ${name} | ${exitReason} | ${lesson.slice(0, 80)}...`);
+  if (salience(agentSeverity(name)) <= SALIENCE_THRESHOLD) return;
+  await postEpisode({
+    name: "agent_lesson",
+    episode_body: `Agent ${name} conclusion: ${lesson}`,
+    source_description: `agent-stop-${name}`,
+    reference_time: ts,
+  });
+}

package/src/runtime/lifecycle/memory/capture-error.ts

@@ -0,0 +1,41 @@
+/**
+ * PostToolUse (Bash) memory handler. Ports `auto-capture-error.py`: on a
+ * non-zero Bash exit with stderr, store an episode in Graphiti and surface a
+ * `<memory-capture>` hint to search past errors / store the eventual solution.
+ */
+import { contextResponse } from "../../../adapters/claude";
+import { isoUtc } from "../security/skill-state";
+import { postEpisode } from "./client";
+import { SALIENCE_THRESHOLD, bashSeverity, salience } from "./salience";
+
+/** Extract exit code + stderr from a PostToolUse Bash payload (either field). */
+function bashResult(payload: Record<string, unknown>): { exit: string; stderr: string } {
+  const r = (payload.tool_result ?? payload.tool_response) as { exit_code?: unknown; stderr?: unknown } | undefined;
+  return { exit: String(r?.exit_code ?? "0"), stderr: typeof r?.stderr === "string" ? r.stderr : "" };
+}
+
+/**
+ * Handle a Bash PostToolUse: capture a failed command's error in neural memory
+ * and return the native additionalContext stdout (or "" when nothing to emit).
+ * @param payload - The raw hook payload.
+ * @param now - Clock.
+ * @returns The native stdout (possibly empty).
+ */
+export async function captureBashError(payload: Record<string, unknown>, now: number): Promise<string> {
+  const { exit, stderr } = bashResult(payload);
+  if (exit === "0" || !stderr) return "";
+  const sev = bashSeverity(stderr);
+  if (salience(sev) <= SALIENCE_THRESHOLD) return "";
+  const errorMsg = stderr.slice(0, 500);
+  await postEpisode({
+    name: "bash_error",
+    episode_body: `Bash error (exit ${exit}): ${errorMsg}`,
+    source_description: "auto-capture",
+    reference_time: isoUtc(now),
+  });
+  const ctx =
+    `Error captured in neural memory (Graphiti).\n` +
+    `Search for similar past errors: use mcp__qdrant__qdrant-find with query "${errorMsg}"\n` +
+    `If you solve this, store the solution: use mcp__qdrant__qdrant-store`;
+  return contextResponse("PostToolUse", ctx);
+}

package/src/runtime/lifecycle/memory/client.ts

@@ -0,0 +1,65 @@
+/**
+ * Graphiti neural-memory HTTP client (best-effort). Ports the urllib calls in
+ * the memory-neural scripts: POST /episodes (store) + POST /search (recall).
+ * Every call swallows network errors and honors a 5s timeout, so a hook never
+ * fails or hangs when the Graphiti server is absent.
+ */
+
+const TIMEOUT_MS = 5000;
+
+/** Base URL `http://<NEURAL_MEMORY_HOST>:<GRAPHITI_PORT>` (env-overridable). */
+export function neuralBase(env: NodeJS.ProcessEnv = process.env): string {
+  const host = env.NEURAL_MEMORY_HOST ?? "localhost";
+  const port = env.GRAPHITI_PORT ?? "8000";
+  return `http://${host}:${port}`;
+}
+
+/** A Graphiti episode payload. */
+export interface Episode {
+  name: string;
+  episode_body: string;
+  source_description: string;
+  reference_time: string;
+}
+
+/** POST an episode to Graphiti `/episodes`. Resolves silently on any failure. */
+export async function postEpisode(ep: Episode, env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  try {
+    await fetch(`${neuralBase(env)}/episodes`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(ep),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch { /* best effort */ }
+}
+
+/** A single recall hit (content or name). */
+export interface RecallHit {
+  content?: string;
+  name?: string;
+}
+
+/**
+ * POST a query to Graphiti `/search`; returns hits or `[]` on any failure
+ * (network error, timeout, non-2xx, malformed JSON).
+ * @param query - The search query.
+ * @param numResults - Max results requested.
+ * @param env - Env (for host/port overrides).
+ * @returns The recall hits, possibly empty.
+ */
+export async function searchMemory(query: string, numResults: number, env: NodeJS.ProcessEnv = process.env): Promise<RecallHit[]> {
+  try {
+    const resp = await fetch(`${neuralBase(env)}/search`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query, num_results: numResults }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!resp.ok) return [];
+    const data = (await resp.json()) as { results?: RecallHit[] };
+    return Array.isArray(data.results) ? data.results : [];
+  } catch {
+    return [];
+  }
+}

package/src/runtime/lifecycle/memory/dispatch.ts

@@ -0,0 +1,42 @@
+/**
+ * fuse-memory-neural scope dispatcher (async; the handlers hit Graphiti over
+ * HTTP, best-effort). Routes by event: SessionStart recalls past lessons,
+ * PostToolUse captures Bash errors / tracks graphiti+qdrant ops, SubagentStop
+ * captures agent conclusions. Returns the native stdout when handled, or `null`
+ * to fall through to the generic pipeline.
+ */
+import { captureAgentLesson } from "./agent-lesson";
+import { captureBashError } from "./capture-error";
+import { trackMemoryOp } from "./track-ops";
+import { recallOnSession } from "./recall";
+
+/** Is this a graphiti/qdrant MCP tool call? */
+function isMemoryTool(tool: string): boolean {
+  return tool.startsWith("mcp__graphiti") || tool.startsWith("mcp__qdrant");
+}
+
+/**
+ * Dispatch a memory-scope lifecycle event to its ported handler.
+ * @param event - Raw hook event name.
+ * @param payload - Raw hook payload.
+ * @param cwd - Project root.
+ * @param now - Clock.
+ * @returns The native stdout, or `null` when unhandled.
+ */
+export async function dispatchMemory(event: string, payload: Record<string, unknown>, cwd: string, now: number): Promise<string | null> {
+  if (event === "SessionStart") return recallOnSession(cwd, now);
+  if (event === "SubagentStop" || event === "Stop") {
+    await captureAgentLesson(payload, now);
+    return "";
+  }
+  if (event === "PostToolUse") {
+    const tool = typeof payload.tool_name === "string" ? payload.tool_name : "";
+    if (tool === "Bash") return captureBashError(payload, now);
+    if (isMemoryTool(tool)) {
+      trackMemoryOp(payload, now);
+      return "";
+    }
+    return null;
+  }
+  return null;
+}

package/src/runtime/lifecycle/memory/recall.ts

@@ -0,0 +1,30 @@
+/**
+ * SessionStart memory handler. Ports `recall-on-session.py`: detect the project
+ * type, recall relevant lessons from Graphiti, log the recall, and inject a
+ * neural-memory-recall additionalContext block.
+ */
+import { basename } from "node:path";
+import { contextResponse } from "../../../adapters/claude";
+import { isoUtc } from "../security/skill-state";
+import { searchMemory } from "./client";
+import { appendMemoryLog, detectProjectType } from "./state";
+
+/**
+ * Handle SessionStart: recall past lessons for this project and return the
+ * native additionalContext stdout (or "" when there is nothing to recall).
+ * @param cwd - Project root.
+ * @param now - Clock.
+ * @returns The native stdout (possibly empty).
+ */
+export async function recallOnSession(cwd: string, now: number): Promise<string> {
+  const projectType = detectProjectType(cwd);
+  const projectName = basename(cwd);
+  const hits = await searchMemory(`${projectType} ${projectName} common errors`, 5);
+  appendMemoryLog("recalls.log", `[${isoUtc(now)}] session_recall | ${projectType} | ${projectName}`);
+  if (hits.length === 0) return "";
+  const lessons = hits.slice(0, 5).map((r) => `- ${r.content || r.name || "unknown"}`).join("\n");
+  const ctx =
+    `Relevant lessons from past sessions:\n${lessons}\n` +
+    `For deeper search: use mcp__qdrant__qdrant-find with project-specific queries.`;
+  return contextResponse("SessionStart", ctx);
+}

package/src/runtime/lifecycle/memory/salience.ts

@@ -0,0 +1,31 @@
+/**
+ * Salience + severity scoring for the memory-neural scope. Ports the
+ * `_severity` / `_agent_severity` helpers and the shared salience formula from
+ * `auto-capture-error.py` and `capture-agent-lesson.py`.
+ */
+
+/** Episodes at or below this salience are not stored. */
+export const SALIENCE_THRESHOLD = 0.3;
+
+/** Severity (1-10) of a Bash stderr by keyword (mirrors auto-capture-error). */
+export function bashSeverity(stderr: string): number {
+  const s = stderr.toLowerCase();
+  if (s.includes("fatal") || s.includes("panic")) return 10;
+  if (s.includes("error") || s.includes("failed")) return 8;
+  if (s.includes("warning")) return 4;
+  if (s.includes("deprecated")) return 2;
+  return 5;
+}
+
+/** Severity (1-10) of a finished agent by name (mirrors capture-agent-lesson). */
+export function agentSeverity(name: string): number {
+  if (name === "sniper" || name === "sniper-faster") return 8;
+  if (name === "research-expert") return 6;
+  if (name.endsWith("-expert")) return 7;
+  return 5;
+}
+
+/** Salience from severity: 0.40·sev/10 + 0.30 + 0.20·0.5 + 0.10·0.5. */
+export function salience(severity: number): number {
+  return (0.4 * severity) / 10 + 0.3 + 0.2 * 0.5 + 0.1 * 0.5;
+}