@lorekit/cli 1.0.0

package/skill/lorekit-memory/rules/intake.md

@@ -0,0 +1,61 @@
+# Intake — reading lessons before you act
+
+Run this at task start, on first navigation into an unfamiliar area, and
+before any hard-to-reverse operation.
+
+## 1. Resolve the current scope
+
+Derive scope from the working repository:
+
+- `origin` remote `owner/repo` → `repo::{owner}/{repo}`
+- current branch → `branch::{owner}/{repo}::{branch}`
+- no git remote → fall back to `global` (and `project::{dir}` for a monorepo)
+
+Lowercase every segment.
+See [../references/scope-resolution.md](../references/scope-resolution.md) for the exact derivation.
+
+## 2. List narrow-to-broad
+
+Query each scope from most specific to least, and merge the results:
+
+```text
+memory.list { scope: "branch::{owner}/{repo}::{branch}" }
+memory.list { scope: "repo::{owner}/{repo}" }
+memory.list { scope: "project::{name}" }        # only if a monorepo
+memory.list { scope: "global" }
+```
+
+When the same key appears at multiple levels, the **more specific scope wins**.
+
+Keep it cheap: a `limit` of 20–50 per scope is plenty.
+Filter with `tags: ["skill::lorekit-memory"]` when you only want this skill's
+lessons; drop the filter to see everything an agent has recorded.
+
+## 3. Search when the task has a keyword
+
+If the task is about a specific subsystem, error, or tool, add a full-text
+search across the owner's repos and global:
+
+```text
+memory.search {
+  q: "<subsystem or error keywords>",
+  scopes: ["repo::{owner}/*", "global"],
+  limit: 10
+}
+```
+
+## 4. Apply as considerations, not commands
+
+Lessons are observations from past runs ("last time, X went wrong when Y").
+They inform your approach and can bias decisions — but they are not rules and
+they can be stale.
+If a lesson contradicts what you observe in the current code, trust the code
+and consider writing a corrective lesson on the way out (see
+[retrospective.md](./retrospective.md)).
+
+## 5. Report briefly
+
+If lessons matched, note them in one or two lines before proceeding
+("LoreKit: 2 relevant lessons — worktree naming, migration order").
+If nothing matched, say nothing and continue.
+If the MCP tools are not connected, note it once and continue without them.

package/skill/lorekit-memory/rules/retrospective.md

@@ -0,0 +1,85 @@
+# Retrospective — writing a lesson when something goes wrong
+
+Run this after friction: a stuck loop, a repeated command failure, a
+surprising gotcha, a near-miss, a wrong assumption that cost time, or a guess
+that paid off and should be reused.
+Do **not** run it on smooth successes — there is nothing durable to record.
+
+## 1. Decide if there is a lesson
+
+Ask the 30-second question:
+
+> Would a future run in this repo (or anywhere) do better if it knew this?
+
+If no, stop — write nothing. Empty retrospectives are skipped.
+If yes, continue.
+
+## 2. Phrase it as an observation
+
+Write what happened and what worked, not a commandment.
+
+- Good: "Running `pnpm nx test mcp-core` without `supabase start` fails with a
+  connection refused error; start Supabase first."
+- Avoid: "ALWAYS start Supabase." (rules rot; observations age gracefully)
+
+Keep the body tight markdown. A sentence or three. Include the concrete
+signal (the error text, the command, the file) so future search finds it.
+
+## 3. Pick the narrowest scope that fits
+
+| The lesson is about… | Scope |
+|----------------------|-------|
+| A universal principle, true in any repo | `global` |
+| This repository's codebase or tooling | `repo::{owner}/{repo}` |
+| A monorepo-wide convention | `project::{name}` |
+| A throwaway detail of this branch only | `branch::{owner}/{repo}::{branch}` |
+
+When in doubt for a "stuff went bad" lesson, default to **repo** scope.
+Reserve `global` for things that are genuinely true everywhere.
+
+## 4. Choose a stable key
+
+Use a short, kebab-case, namespaced key so related lessons cluster and
+re-writes update in place instead of duplicating:
+
+```text
+lorekit-memory::<short-slug>
+# e.g. lorekit-memory::supabase-start-before-test
+```
+
+## 5. Deduplicate before writing
+
+Check for a near-duplicate first, so you update rather than pile up:
+
+```text
+memory.search { q: "<key words of the lesson>", scopes: ["repo::{owner}/{repo}", "global"] }
+```
+
+- Found the same situation under a key → reuse that **exact scope + key** and
+  `memory.write` an updated body (writing the same scope+key updates in place).
+  Optionally note "(seen again <short-context>)" so the recurrence is visible.
+- Nothing similar → write a new lesson with a fresh key.
+
+## 6. Write
+
+```text
+memory.write {
+  scope:        "repo::{owner}/{repo}",
+  key:          "lorekit-memory::supabase-start-before-test",
+  value:        "<observation in markdown>",
+  tags:         ["skill::lorekit-memory", "source::stuck-loop"],
+  source_agent: "<your agent name, if known>",
+  trigger:      "stuck-loop"
+}
+```
+
+Pick `trigger` / `source::*` from what actually happened:
+`stuck-loop`, `command-failure`, `gotcha`, `near-miss`, `assumption-wrong`,
+`paid-off`, or `manual`.
+
+## 7. Confirm
+
+State in one line what you recorded and where
+("LoreKit: wrote repo lesson `supabase-start-before-test`").
+If the write fails because the token is read-only or missing, say so once and
+continue — never retry a write that failed on authorization.

package/src/adapters/claude.mjs

@@ -0,0 +1,41 @@
+// Adapter for Claude Code hooks.
+// Contract: stdin JSON with snake_case fields; stdout injects context via
+// hookSpecificOutput.additionalContext. Non-blocking (we never set decision).
+export const claude = {
+  name: 'claude',
+
+  intentFor(event) {
+    switch (event) {
+      case 'SessionStart':
+        return 'read';
+      case 'PostToolUse':
+      case 'PostToolUseFailure':
+        return 'failure';
+      case 'Stop':
+        return 'retrospective';
+      default:
+        return 'noop';
+    }
+  },
+
+  // PostToolUseFailure fires only when a tool failed — no heuristic needed.
+  guaranteedFailure(event) {
+    return event === 'PostToolUseFailure';
+  },
+
+  parse(input) {
+    return {
+      cwd: input.cwd || null,
+      sessionId: input.session_id || null,
+      toolName: input.tool_name || 'tool',
+      toolResponse: input.tool_response || null,
+      event: input.hook_event_name || null,
+    };
+  },
+
+  emit(event, text) {
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: event, additionalContext: text },
+    });
+  },
+};

package/src/adapters/codex.mjs

@@ -0,0 +1,36 @@
+// Adapter for OpenAI Codex CLI hooks (experimental; `codex_hooks` feature flag).
+// Codex mirrors Claude Code's event model and JSON shape closely, so we reuse
+// the same snake_case input fields and hookSpecificOutput.additionalContext
+// output. If a future Codex build diverges, only this file needs to change.
+export const codex = {
+  name: 'codex',
+
+  intentFor(event) {
+    switch (event) {
+      case 'SessionStart':
+        return 'read';
+      case 'PostToolUse':
+        return 'failure';
+      case 'Stop':
+        return 'retrospective';
+      default:
+        return 'noop';
+    }
+  },
+
+  parse(input) {
+    return {
+      cwd: input.cwd || (Array.isArray(input.workspace_roots) ? input.workspace_roots[0] : null),
+      sessionId: input.session_id || input.thread_id || null,
+      toolName: input.tool_name || 'tool',
+      toolResponse: input.tool_response || null,
+      event: input.hook_event_name || null,
+    };
+  },
+
+  emit(event, text) {
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: event, additionalContext: text },
+    });
+  },
+};

package/src/adapters/cursor.mjs

@@ -0,0 +1,42 @@
+// Adapter for Cursor hooks (.cursor/hooks.json, "version": 1).
+//
+// Cursor's hook surface is narrower than Claude/Codex:
+//   - there is no SessionStart, so the read-on-start path is handled by the
+//     bundled Cursor *rule* (the agent calls the MCP); the `beforeSubmitPrompt`
+//     hook is best-effort and injects via `followup_message` where supported.
+//   - `beforeShellExecution` fires *before* a command runs, so there is no exit
+//     code to inspect — reliable failure detection is not possible here.
+//   - the confirmed injection channel is `stop` → { followup_message }.
+//
+// Confirmed stdin fields: `command`, `file_path`, `edits`, `generation_id`.
+export const cursor = {
+  name: 'cursor',
+
+  intentFor(event) {
+    switch (event) {
+      case 'beforeSubmitPrompt':
+        return 'read';
+      case 'stop':
+        return 'retrospective';
+      default:
+        return 'noop';
+    }
+  },
+
+  parse(input) {
+    return {
+      cwd:
+        input.cwd ||
+        (Array.isArray(input.workspace_roots) ? input.workspace_roots[0] : null),
+      sessionId: input.generation_id || input.conversation_id || null,
+      toolName: 'command',
+      toolResponse: null,
+      event: input.hook_event_name || null,
+    };
+  },
+
+  // Cursor injects an agent-visible message via `followup_message`.
+  emit(_event, text) {
+    return JSON.stringify({ followup_message: text });
+  },
+};

package/src/config.mjs

@@ -0,0 +1,132 @@
+// Project layout + .mcp.json read/merge helpers.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// packages/cli/ — the installable package root (this file lives in src/).
+export const PKG_ROOT = fileURLToPath(new URL('../', import.meta.url));
+export const SKILL_SOURCE = path.join(PKG_ROOT, 'skill', 'lorekit-memory');
+export const SKILL_NAME = 'lorekit-memory';
+
+export function resolveProjectRoot(dir) {
+  return path.resolve(dir || process.cwd());
+}
+
+export function mcpJsonPath(root) {
+  return path.join(root, '.mcp.json');
+}
+
+export function skillInstallDir(root) {
+  return path.join(root, '.claude', 'skills', SKILL_NAME);
+}
+
+// Throwing read — used by `install` so a corrupt .mcp.json aborts the write
+// instead of silently clobbering the user's file.
+export function readJsonIfExists(file) {
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`Failed to parse ${file}: ${e.message}`);
+  }
+}
+
+// Non-throwing read — used by the diagnostic (doctor) and hook read paths,
+// which must degrade gracefully rather than crash on a malformed file.
+// Distinguishes absent from present-but-invalid so callers can report it.
+export function readMcpConfig(root) {
+  const file = mcpJsonPath(root);
+  if (!fs.existsSync(file)) return { present: false, valid: false, config: null };
+  try {
+    return { present: true, valid: true, config: JSON.parse(fs.readFileSync(file, 'utf8')) };
+  } catch {
+    return { present: true, valid: false, config: null };
+  }
+}
+
+// Merge a lorekit server entry into .mcp.json, preserving any other servers.
+export function upsertMcpServer(root, remoteUrl) {
+  const file = mcpJsonPath(root);
+  const config = readJsonIfExists(file) || {};
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+    config.mcpServers = {};
+  }
+  const existed = Boolean(config.mcpServers.lorekit);
+  config.mcpServers.lorekit = {
+    command: 'npx',
+    args: ['-y', 'mcp-remote', remoteUrl],
+  };
+  fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+  return { file, existed };
+}
+
+// Pull the configured lorekit remote URL out of .mcp.json, if present.
+// Non-throwing: returns null when the file is absent, invalid, or has no
+// lorekit server. Callers that need to distinguish those use readMcpConfig.
+export function readLorekitServer(root) {
+  const { config } = readMcpConfig(root);
+  const server = config && config.mcpServers && config.mcpServers.lorekit;
+  if (!server) return null;
+  const args = Array.isArray(server.args) ? server.args : [];
+  const url = args.find((a) => typeof a === 'string' && /^https?:\/\//.test(a));
+  return { server, url: url || null };
+}
+
+// Recursively copy the skill source into the target, skipping files that
+// already exist unless `force` is set. Returns the number of files actually
+// written, so the caller can report "installed" / "updated" / "unchanged"
+// honestly instead of guessing from whether the directory pre-existed.
+export function copyDir(src, dest, { force = false } = {}) {
+  fs.mkdirSync(dest, { recursive: true });
+  let written = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      written += copyDir(from, to, { force });
+    } else {
+      if (fs.existsSync(to) && !force) continue;
+      fs.copyFileSync(from, to);
+      written++;
+    }
+  }
+  return written;
+}
+
+// Resolve endpoint + token from flags, then env, in that order.
+export function resolveConnection(args) {
+  const endpoint =
+    args.endpoint ||
+    process.env.LOREKIT_MCP_URL ||
+    process.env.LOREKIT_ENDPOINT ||
+    null;
+  const token = args.token || process.env.LOREKIT_TOKEN || null;
+  return {
+    endpoint: typeof endpoint === 'string' ? endpoint.trim() : null,
+    token: typeof token === 'string' ? token.trim() : null,
+  };
+}
+
+export function tokenKind(token) {
+  if (!token) return 'none';
+  if (token.startsWith('lk_rw_')) return 'read-write';
+  if (token.startsWith('lk_ro_')) return 'read-only';
+  return 'unknown';
+}
+
+// For hooks: resolve the connection from the project's .mcp.json first
+// (that is where `lorekit install` wrote the token), then fall back to env.
+// `splitEndpoint` is passed in to avoid a circular import with mcp.mjs.
+export function resolveProjectConnection(root, splitEndpoint) {
+  const configured = readLorekitServer(root);
+  if (configured && configured.url) {
+    const { endpoint, token } = splitEndpoint(configured.url);
+    if (endpoint && !endpoint.includes('<project-ref>')) {
+      return {
+        endpoint,
+        token: token || process.env.LOREKIT_TOKEN || null,
+      };
+    }
+  }
+  return resolveConnection({});
+}

package/src/control.mjs

@@ -0,0 +1,152 @@
+// The control model: decide the memory mode (off | local | remote), the store
+// target, who decided, and which deny constraints are active.
+//
+// Two layers of config, two kinds of statement:
+//   - a SELECT (`mode`) chooses a mode within what is allowed;
+//   - a DENY forbids a mode outright and can never be overridden.
+//
+// Deny always wins. Denies are a UNION across every source and only ever
+// accumulate — so a user-level "never remote" (privacy/compliance) is a ceiling
+// no repo config or default can lift, and "never local" (no `.lorekit/` in the
+// tree / CI) is enforceable the same way. `off` is always allowed (you cannot
+// deny "disabled"), so it is the terminal fallback.
+//
+// Local mode is two-tier (mirroring the persistent-memory home + project-shared
+// model): a per-user `home` tier at $LOREKIT_HOME (default `~/.lorekit/`) and an
+// opt-in per-repo `project` tier at `<repo>/.lorekit/` (overridable with
+// $LOREKIT_STORE). The resolved local `storeTarget` is `{ home, project }`.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveProjectConnection } from './config.mjs';
+import { splitEndpoint } from './mcp.mjs';
+
+export const MODES = ['off', 'local', 'remote'];
+
+// Accept a few friendly spellings, incl. persistent-memory's `backend` values.
+export function normalizeMode(v) {
+  if (typeof v !== 'string') return null;
+  const s = v.trim().toLowerCase();
+  if (['off', 'disabled', 'none', 'false'].includes(s)) return 'off';
+  if (['local', 'markdown', 'file', 'files'].includes(s)) return 'local';
+  if (['remote', 'lorekit', 'mcp', 'hosted'].includes(s)) return 'remote';
+  return null;
+}
+
+function asList(v) {
+  if (Array.isArray(v)) return v;
+  if (typeof v === 'string') return v.split(',').map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+// Pure resolver — no IO. Given the already-loaded config objects, decide.
+// Returns { mode, storeTarget, decidedBy, denies, connection }.
+export function resolveControl({
+  env = {},
+  userConfig = {},
+  repoConfig = {},
+  connection = {},
+  root = process.cwd(),
+  home = env.LOREKIT_HOME || null,
+} = {}) {
+  // 1. Denies — union, deny-wins, accumulate (never removable).
+  const denies = [];
+  const addDeny = (mode, source) => {
+    const m = normalizeMode(mode);
+    if ((m === 'remote' || m === 'local') && !denies.some((d) => d.mode === m)) {
+      denies.push({ mode: m, source });
+    }
+  };
+  for (const m of asList(env.LOREKIT_DENY)) addDeny(m, 'env LOREKIT_DENY');
+  for (const m of asList(userConfig.deny)) addDeny(m, 'user config (~/.lorekit/config.json)');
+  for (const m of asList(repoConfig.deny)) addDeny(m, 'repo (.lorekit.json)');
+  const denied = new Set(denies.map((d) => d.mode));
+
+  // 2. Candidate selections, highest precedence first. An explicit env/flag
+  //    outranks a user preference, which outranks the repo default, which
+  //    outranks the built-in default.
+  const candidates = [];
+  const push = (mode, source) => {
+    const m = normalizeMode(mode);
+    if (m) candidates.push({ mode: m, source });
+  };
+  push(env.LOREKIT_MODE, 'env LOREKIT_MODE');
+  push(userConfig.mode ?? userConfig.backend, 'user config (~/.lorekit/config.json)');
+  push(repoConfig.mode ?? repoConfig.backend, 'repo (.lorekit.json)');
+  // Built-in default is `remote`: it preserves the pre-control behaviour where
+  // reads stay silent until a connection is configured while the retrospective
+  // / failure nudges still fire (they are backend-agnostic reminders). `off`
+  // is reached only by an explicit selection, or when `remote` is denied.
+  push(
+    'remote',
+    connection.usable
+      ? 'default (remote connection configured)'
+      : 'default (remote — not yet configured)',
+  );
+  push('off', 'terminal fallback (all selections denied)');
+
+  // 3. First candidate that is allowed. `off` is never denied, so this always
+  //    resolves. A denied higher-precedence selection is silently capped.
+  const idx = candidates.findIndex((c) => c.mode === 'off' || !denied.has(c.mode));
+  const chosen = candidates[idx];
+  const cappedModes = [
+    ...new Set(candidates.slice(0, idx).filter((c) => denied.has(c.mode)).map((c) => c.mode)),
+  ];
+  const decidedBy = cappedModes.length
+    ? `${chosen.source} (after deny: ${cappedModes.join(', ')})`
+    : chosen.source;
+
+  // 4. Store target. Local mode is two-tier: { home, project }.
+  let storeTarget = null;
+  if (chosen.mode === 'local') {
+    storeTarget = { home: home || null, project: projectDirFrom({ env, userConfig, repoConfig, root }) };
+  } else if (chosen.mode === 'remote') {
+    storeTarget = connection.endpoint || null;
+  }
+
+  return { mode: chosen.mode, storeTarget, decidedBy, denies, connection };
+}
+
+// The per-repo project-tier directory: $LOREKIT_STORE, else a `store` override
+// in either config layer, else the default `.lorekit/` at the repo root.
+function projectDirFrom({ env, userConfig, repoConfig, root }) {
+  const raw = env.LOREKIT_STORE || userConfig.store || repoConfig.store || '.lorekit';
+  return path.isAbsolute(raw) ? raw : path.join(root, raw);
+}
+
+// Resolve both local-tier directories with IO (reads the config files for a
+// `store` override). Used by `migrate` so it works regardless of the active
+// mode. `home` is the per-user tier root; `project` is the opt-in repo tier.
+export function localStoreDirs(root = process.cwd(), env = process.env) {
+  const home = userConfigDir(env);
+  const userConfig = readJson(path.join(home, 'config.json'));
+  const repoConfig = readJson(path.join(root, '.lorekit.json'));
+  return { home, project: projectDirFrom({ env, userConfig, repoConfig, root }) };
+}
+
+// IO wrapper — load env + config files, derive the connection, then resolve.
+export function loadControl(root, { env = process.env } = {}) {
+  const home = userConfigDir(env);
+  const userConfig = readJson(path.join(home, 'config.json'));
+  const repoConfig = readJson(path.join(root, '.lorekit.json'));
+  const conn = resolveProjectConnection(root, splitEndpoint);
+  const usable = Boolean(
+    conn.endpoint && conn.token && !String(conn.endpoint).includes('<project-ref>'),
+  );
+  const connection = { endpoint: conn.endpoint, token: conn.token, usable };
+  return resolveControl({ env, userConfig, repoConfig, connection, root, home });
+}
+
+// The per-user home tier root (also holds config.json): $LOREKIT_HOME, default
+// `~/.lorekit`. Moved from the old `~/.agent-memory` location.
+function userConfigDir(env) {
+  return env.LOREKIT_HOME || path.join(os.homedir(), '.lorekit');
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}

package/src/core/failure.mjs

@@ -0,0 +1,28 @@
+// Heuristic: did a completed tool call fail? Framework-agnostic.
+// Conservative on purpose — a false "failed" nudges the agent needlessly.
+
+function num(v) {
+  return typeof v === 'number' ? v : typeof v === 'string' && /^-?\d+$/.test(v) ? Number(v) : null;
+}
+
+// `response` is the tool_response object (shape varies by framework/tool).
+export function isFailure(toolName, response) {
+  if (!response || typeof response !== 'object') return false;
+
+  // Explicit error flags set by the harness.
+  if (response.is_error === true || response.isError === true) return true;
+  if (response.interrupted === true) return false; // user abort, not a lesson
+
+  // Exit codes from shell-style tools.
+  for (const field of ['exit_code', 'exitCode', 'code', 'returnCode']) {
+    const n = num(response[field]);
+    if (n !== null) return n !== 0;
+  }
+
+  // Some tools report status directly.
+  if (typeof response.status === 'string') {
+    return /^(error|fail(ed)?)$/i.test(response.status);
+  }
+
+  return false;
+}

package/src/core/lessons.mjs

@@ -0,0 +1,60 @@
+// Shared hook logic: fetch and format lessons; build the nudge text.
+// Framework-agnostic — adapters shape these strings into each tool's contract.
+// Storage is reached through the resolved store (local | remote), never a
+// backend directly, so the same read path serves every mode.
+import { deriveScope } from '../scope.mjs';
+
+const MAX_LESSONS = 15;
+
+// Read lessons narrow-to-broad through the store and merge; more specific
+// scope wins on key. Any per-scope failure is skipped (memory is best-effort).
+export async function fetchLessons(store, cwd) {
+  const scope = deriveScope(cwd);
+  const byKey = new Map();
+  for (const s of scope.readOrder) {
+    const res = await store.list({ scope: s, limit: 25 });
+    if (!res || !res.ok) continue;
+    const entries = Array.isArray(res.entries) ? res.entries : [];
+    for (const e of entries) {
+      if (e && e.key && !byKey.has(e.key)) byKey.set(e.key, { ...e, scope: s });
+    }
+  }
+  return { scope, lessons: [...byKey.values()].slice(0, MAX_LESSONS) };
+}
+
+// Render lessons as a compact markdown block, or null when there are none.
+export function formatLessons(lessons, scope) {
+  if (!lessons || lessons.length === 0) return null;
+  const header =
+    `LoreKit — ${lessons.length} shared lesson(s) for ${scope.repoScope || 'this workspace'}. ` +
+    `Treat as considerations, not rules; trust the current code if they conflict.`;
+  const body = lessons
+    .map((l) => {
+      const first = String(l.value || '').split('\n')[0].slice(0, 300);
+      return `- (${l.scope}) ${l.key}: ${first}`;
+    })
+    .join('\n');
+  return `${header}\n${body}`;
+}
+
+// The retrospective nudge emitted at end-of-turn (one-shot per session).
+export function retrospectiveNudge(scope) {
+  const writeScope = scope.repoScope || 'global';
+  return (
+    'LoreKit retrospective: if this session hit a stuck loop, a repeated ' +
+    'command failure, a surprising gotcha, a near-miss, or a wrong assumption ' +
+    'that cost time, record it now via the lorekit-memory skill ' +
+    `(memory.write to ${writeScope}, phrased as an observation). ` +
+    'If nothing was durable, do nothing.'
+  );
+}
+
+// The nudge emitted when a tool failure is detected.
+export function failureNudge(toolName, scope) {
+  const writeScope = scope.repoScope || 'global';
+  return (
+    `LoreKit: the last ${toolName} call failed. If this is a recurring or ` +
+    'non-obvious failure, consider recording the fix as a lesson via ' +
+    `lorekit-memory (memory.write to ${writeScope}), so the next run avoids it.`
+  );
+}

package/src/core/record.mjs

@@ -0,0 +1,27 @@
+// Fixture recorder. When LOREKIT_HOOK_RECORD points at a directory, every hook
+// invocation writes the exact payload the host sent to
+// <dir>/<adapter>-<event>.json. Run each framework ONCE with this env set to
+// harvest real fixtures; the replay tests then run offline forever.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function recordFixture(adapter, event, raw) {
+  const dir = process.env.LOREKIT_HOOK_RECORD;
+  if (!dir) return;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    let stdin;
+    try {
+      stdin = JSON.parse(raw);
+    } catch {
+      stdin = raw; // keep the raw string if it was not valid JSON
+    }
+    const name = `${adapter}-${event || 'unknown'}.json`;
+    fs.writeFileSync(
+      path.join(dir, name),
+      JSON.stringify({ adapter, event: event || null, stdin }, null, 2) + '\n',
+    );
+  } catch {
+    // Recording must never affect the host — swallow any error.
+  }
+}