agent-procedures 0.1.0 → 0.2.0

package/README.md

@@ -2,21 +2,72 @@
 
 Procedural memory for coding agents.
 
+Coding agents are pretty good at figuring things out. They're bad at remembering how they did it last time, so they just figure it out again. Every time.
+
+Reflex watches the tools your agent actually runs, keeps the paths that worked, and hands them back the next time you ask for something similar. It doesn't store facts, your docs already do that. It stores how.
+
+The npm package is `agent-procedures`. The product is Reflex.
+
+## How it works (hot path vs cold path)
+
+The **hot path** runs every time you prompt the agent or the agent runs a tool. It has to be fast, so it doesn't call an LLM. It's just disk I/O. When you ask for something, Reflex checks its memory for a match and injects the steps into the agent's context. When the agent uses tools, Reflex traces what happens. If the agent gets the job done without leaving broken steps behind, Reflex saves that trace as a new procedure.
+
+The **cold path** is a background groomer. Once 5 new procedures pile up, it kicks off a background process that asks a cheap LLM to review them. It drops the risky ones and adds aliases (like synonyms) to the good ones so they match more easily next time. 
+
+You don't run either of these manually. You just use your agent.
+
+## Status & Harnesses
+
+Early. Reflex is built to plug into different agent platforms (harnesses). Right now, **Claude Code is the only one built** and is the default.
+
+I set the engine up so Cursor and others can plug in later, but the adapters for those don't exist yet.
+
 ## Install
 
+Run this in the repo you want Reflex in:
+
 ```bash
 npx agent-procedures init
 ```
 
-Creates a project-scoped store:
+By default this installs the Claude Code harness. If you were using a different one later, you'd run `npx agent-procedures init --harness cursor`. 
+
+Installing the package on its own won't do anything. You need `init`. It creates the folders, copies the runtime in, and adds a hook so your agent knows to call it.
+
+## API key (for the background groomer)
+
+Because the groomer uses an LLM to review procedures, it needs a cheap model key. 
+
+If you already have `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `GEMINI_API_KEY` exported in your terminal, it just uses that. Otherwise:
+
+```bash
+npx agent-procedures auth login    # pick a provider, paste your key
+npx agent-procedures auth status   # check what it's using and the last groomer error
+```
+
+The key gets checked before it's saved, so a typo fails right away instead of a week later in a log file. It gets stored in `~/.reflex/credentials.json` on your machine and only you can read it. 
+
+## What ends up in your repo
 
 ```
 .reflex/
-  config.json        # settings (not memory)
-  procedures.jsonl   # remembered procedures
+  config.json        # settings, not memory
+  procedures.jsonl   # what it remembered
   runs.jsonl         # optional run outcomes
+  engine/            # the runtime
+  traces/            # scratch for the current turn
 ```
 
-`.reflex/` is added to `.gitignore` by default.
+`traces/` gets added to `.gitignore`. **Commit everything else**, including `.claude/settings.json` (the hook wiring), so anyone who clones the repo gets the same memory. If you upgrade the package, run `init` again to refresh the engine.
+
+## Adding a harness
+
+If you want to build an adapter for something other than Claude Code:
+
+Only three things change between harnesses: where hooks get registered, what the event payload looks like, and how context gets passed back to the agent. The rest of the engine doesn't care who called it.
+
+Adding one is a single file in `lib/harnesses/` plus one line in `lib/harnesses/index.js`. `claude.js` is the reference.
+
+## License
 
-npm install alone does nothing — you need `init` to seed the project.
+MIT

package/bin/cli.js

@@ -8,19 +8,48 @@ if (!command || command === "--help" || command === "-h") {
   console.log(`agent-procedures — procedural memory for coding agents (Reflex)
 
 Usage:
-  npx agent-procedures init    Create .reflex/ in the current project
+  npx agent-procedures init [--harness claude]   Create .reflex/ and wire hooks
+  npx agent-procedures auth login                Store an API key for the background groomer
+  npx agent-procedures auth status               Show which provider/key the groomer will use
 `);
   process.exit(command ? 0 : 1);
 }
 
 if (command === "init") {
-  const results = init(process.cwd());
-  console.log("Initialized Reflex in .reflex/");
-  console.log(`  config.json       ${results.config}`);
-  console.log(`  procedures.jsonl  ${results.procedures}`);
-  console.log(`  runs.jsonl        ${results.runs}`);
-  console.log(`  .gitignore        ${results.gitignore}`);
-  process.exit(0);
+  const args = process.argv.slice(3);
+  const i = args.indexOf("--harness");
+  const harness = i >= 0 ? args[i + 1] : undefined;
+  try {
+    const results = init(process.cwd(), { harness });
+    console.log("Initialized Reflex in the repository");
+    console.log(`  .reflex/config.json       ${results.config}`);
+    console.log(`  .reflex/procedures.jsonl  ${results.procedures}`);
+    console.log(`  .reflex/runs.jsonl        ${results.runs}`);
+    console.log(`  .reflex/engine/           ${results.engine}`);
+    console.log(`  .gitignore                ${results.gitignore}`);
+    console.log(`  hooks (${harness || "claude"})            ${results.hooks}`);
+    process.exit(0);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (command === "auth") {
+  const { login, status, USAGE } = await import("../lib/auth.js");
+  const [sub, ...rest] = process.argv.slice(3);
+  try {
+    if (sub === "login") await login(rest);
+    else if (sub === "status") status();
+    else {
+      console.error(USAGE);
+      process.exit(1);
+    }
+    process.exit(0);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
 }
 
 console.error(`Unknown command: ${command}`);

package/lib/auth.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { Writable } from "node:stream";
+import {
+  PROVIDERS,
+  PROVIDER_NAMES,
+  credentialsFile,
+  readCredentials,
+  reflexHome,
+  resolveCredentials,
+} from "./providers.js";
+
+export const USAGE = `Usage:
+  npx agent-procedures auth login [--provider <name>] [--model <id>] [--key-stdin]
+  npx agent-procedures auth status
+
+Providers: ${PROVIDER_NAMES.join(", ")}
+
+Interactive by default. For scripts/CI, pipe the key on stdin:
+  echo "$OPENAI_API_KEY" | npx agent-procedures auth login --provider openai --key-stdin
+
+The groomer also reads ${PROVIDER_NAMES.map((p) => PROVIDERS[p].envVar).join(" / ")}
+directly, so \`auth login\` is optional if one of those is already set.`;
+
+function parseArgs(args) {
+  const out = { provider: null, model: null, keyStdin: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--provider" && args[i + 1]) out.provider = args[++i];
+    else if (a === "--model" && args[i + 1]) out.model = args[++i];
+    else if (a === "--key-stdin") out.keyStdin = true;
+    else throw new Error(`Unknown argument: ${a}\n\n${USAGE}`);
+  }
+  return out;
+}
+
+function ask(question, io) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: io.stdin, output: io.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// Readline with a muted output stream: line editing still works, nothing is echoed.
+function askHidden(question, io) {
+  return new Promise((resolve) => {
+    io.stdout.write(question);
+    const muted = new Writable({ write(_chunk, _enc, cb) { cb(); } });
+    const rl = readline.createInterface({ input: io.stdin, output: muted, terminal: true });
+    rl.question("", (answer) => {
+      rl.close();
+      io.stdout.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+
+function readAll(stream) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    stream.setEncoding("utf8");
+    stream.on("data", (c) => (data += c));
+    stream.on("end", () => resolve(data.trim()));
+    stream.on("error", reject);
+  });
+}
+
+async function chooseProvider(io) {
+  const menu = PROVIDER_NAMES.map((p, i) => `  [${i + 1}] ${PROVIDERS[p].label}`).join("\n");
+  const answer = await ask(`Provider:\n${menu}\n> `, io);
+  const byIndex = PROVIDER_NAMES[Number(answer) - 1];
+  const byName = PROVIDER_NAMES.find((p) => p === answer.toLowerCase());
+  const provider = byIndex || byName;
+  if (!provider) throw new Error(`Unknown provider "${answer}". Choose one of: ${PROVIDER_NAMES.join(", ")}`);
+  return provider;
+}
+
+function saveCredentials(provider, apiKey, model) {
+  const dir = reflexHome();
+  const file = credentialsFile();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  let creds = { version: 1, providers: {} };
+  try {
+    creds = { ...creds, ...(readCredentials() || {}) };
+  } catch (e) {
+    // corrupt file; start fresh
+  }
+  creds.providers = creds.providers || {};
+  creds.providers[provider] = { apiKey, model };
+  creds.defaultProvider = provider;
+
+  fs.writeFileSync(file, JSON.stringify(creds, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  fs.chmodSync(file, 0o600); // mode above only applies on create
+  return file;
+}
+
+export async function login(args, io = { stdin: process.stdin, stdout: process.stdout }) {
+  const opts = parseArgs(args);
+  const interactive = Boolean(io.stdin.isTTY) && !opts.keyStdin;
+
+  let provider = opts.provider;
+  if (provider && !PROVIDERS[provider]) {
+    throw new Error(`Unsupported provider "${provider}". Choose one of: ${PROVIDER_NAMES.join(", ")}`);
+  }
+  if (!provider) {
+    if (!interactive) throw new Error(`--provider is required when not running interactively.\n\n${USAGE}`);
+    provider = await chooseProvider(io);
+  }
+  const def = PROVIDERS[provider];
+
+  let apiKey;
+  if (opts.keyStdin) {
+    apiKey = await readAll(io.stdin);
+  } else if (interactive) {
+    apiKey = await askHidden(`${def.label} API key (get one at ${def.keysUrl}): `, io);
+  } else {
+    throw new Error(`No key given. Use --key-stdin when not running interactively.\n\n${USAGE}`);
+  }
+  if (!apiKey) throw new Error("No key given.");
+
+  if (!apiKey.startsWith(def.keyPrefix)) {
+    io.stdout.write(`Warning: ${def.label} keys usually start with "${def.keyPrefix}". Checking anyway.\n`);
+  }
+
+  const model = opts.model || def.defaultModel;
+
+  io.stdout.write(`Checking key with ${def.label}... `);
+  try {
+    await def.verify(apiKey);
+  } catch (e) {
+    io.stdout.write("failed\n");
+    throw new Error(`${def.label} rejected the key: ${e.message}`);
+  }
+  io.stdout.write("ok\n");
+
+  const file = saveCredentials(provider, apiKey, model);
+  io.stdout.write(`Saved to ${file} (readable only by you)\n`);
+  io.stdout.write(`Provider: ${def.label}\nModel: ${model}\n`);
+}
+
+function maskKey(key) {
+  if (key.length <= 8) return "****";
+  return `${key.slice(0, 4)}...${key.slice(-4)}`;
+}
+
+export function status(io = { stdout: process.stdout }, cwd = process.cwd()) {
+  const resolved = resolveCredentials();
+  if (!resolved) {
+    io.stdout.write(
+      `Not configured. Run \`npx agent-procedures auth login\` or set one of: ${PROVIDER_NAMES.map((p) => PROVIDERS[p].envVar).join(", ")}\n`,
+    );
+  } else {
+    const def = PROVIDERS[resolved.provider];
+    const from = resolved.source === "env" ? `env ${def.envVar}` : credentialsFile();
+    io.stdout.write(`Provider: ${def.label}\nModel: ${resolved.model}\nKey: ${maskKey(resolved.apiKey)} (from ${from})\n`);
+  }
+
+  const log = path.join(cwd, ".reflex", "worker.log");
+  if (fs.existsSync(log)) {
+    const lines = fs.readFileSync(log, "utf8").trim().split("\n");
+    const last = lines[lines.length - 1];
+    if (last) io.stdout.write(`Last groomer error: ${last}\n`);
+  }
+}

package/lib/engine.js

@@ -0,0 +1,179 @@
+import {
+  appendProcedure,
+  appendTrace,
+  deleteTrace,
+  readProcedures,
+  readTrace,
+  startTrace,
+} from "./store.js";
+
+/**
+ * Harness-free hot path.
+ *
+ * Normalized event (produced by a harness adapter):
+ *   { type: "prompt", sessionId, promptId, prompt }
+ *   { type: "tool",   sessionId, promptId, tool, target, ok }
+ *   { type: "stop",   sessionId, promptId, interrupted, busy }
+ *
+ * Returns { context: string | null }. `context` is text the harness should
+ * inject into the agent's next turn, if it knows how.
+ */
+export function handleEvent(evt, reflexDir, deps = {}) {
+  if (!evt || !evt.sessionId || !evt.promptId) return { context: null };
+
+  if (evt.type === "prompt") return onPrompt(evt, reflexDir);
+  if (evt.type === "tool") return onTool(evt, reflexDir);
+  if (evt.type === "stop") return onStop(evt, reflexDir, deps);
+  return { context: null };
+}
+
+export const GROOM_THRESHOLD = 5;
+
+// --- prompt: open turn + recall ------------------------------------------
+
+function onPrompt(evt, reflexDir) {
+  const { sessionId, promptId, prompt } = evt;
+  startTrace(reflexDir, sessionId, promptId, { t: "Goal", prompt });
+
+  const hit = recall(prompt, readProcedures(reflexDir));
+  if (!hit) return { context: null };
+
+  appendTrace(reflexDir, sessionId, promptId, { t: "Recall", hit: hit.node.id });
+  return { context: hit.text };
+}
+
+function recall(prompt, procs) {
+  if (!prompt) return null;
+  const p = prompt.toLowerCase();
+  const fmt = (steps) => steps.map((s) => `- ${s.t}: ${s.target}`).join("\n");
+
+  for (const node of procs) {
+    if (node.enabled === false || node.parent_id) continue;
+
+    let match = node.trigger && p.includes(node.trigger.toLowerCase());
+    if (!match && Array.isArray(node.aliases)) {
+      match = node.aliases.some((a) => p.includes(a.toLowerCase()));
+    }
+    if (!match) continue;
+
+    let text = fmt(node.steps);
+    const alt = procs.find((e) => e.parent_id === node.id && e.type === "alt" && e.enabled !== false);
+    const onFail = procs.find((e) => e.parent_id === node.id && e.type === "on_fail" && e.enabled !== false);
+    if (alt) text += "\n\nAlternative path that worked:\n" + fmt(alt.steps);
+    if (onFail) text += "\n\nIf it fails, this recovery worked:\n" + fmt(onFail.steps);
+
+    return {
+      node,
+      text: `Reflex memory found a procedure for this task:\n\n${text}\n\nFollow these steps instead of figuring it out from scratch.`,
+    };
+  }
+  return null;
+}
+
+// --- tool: trace ----------------------------------------------------------
+
+function onTool(evt, reflexDir) {
+  appendTrace(reflexDir, evt.sessionId, evt.promptId, { t: evt.tool, target: evt.target || "", ok: evt.ok });
+  return { context: null };
+}
+
+// --- stop: judge → gate → synthesize → write ------------------------------
+
+function onStop(evt, reflexDir, deps) {
+  const { sessionId, promptId } = evt;
+  const lines = readTrace(reflexDir, sessionId, promptId);
+  if (lines.length === 0) return { context: null };
+
+  let goal = "";
+  let recallHit = null;
+  for (const l of lines) {
+    if (l.t === "Goal") goal = l.prompt;
+    if (l.t === "Recall" && l.hit) recallHit = l.hit;
+  }
+
+  if (judge(lines, evt)) {
+    const steps = synthesize(lines);
+    if (steps.length > 0) {
+      if (!recallHit) {
+        appendProcedure(reflexDir, {
+          id: Math.random().toString(36).slice(2, 11),
+          title: goal,
+          trigger: goal,
+          steps,
+          enabled: true,
+          hits: 0,
+          last_used_at: new Date().toISOString(),
+          created_at: new Date().toISOString(),
+          status: "pending_review",
+        });
+      } else {
+        const parent = readProcedures(reflexDir).find((p) => p.id === recallHit);
+        const parentSteps = parent ? parent.steps : [];
+        const same =
+          parentSteps.length === steps.length &&
+          parentSteps.every((s, i) => s.t === steps[i].t && s.target === steps[i].target);
+        if (!same) {
+          appendProcedure(reflexDir, {
+            parent_id: recallHit,
+            type: "alt",
+            steps,
+            created_at: new Date().toISOString(),
+            status: "pending_review",
+          });
+        }
+      }
+
+      const pending = readProcedures(reflexDir).filter((p) => p.status === "pending_review").length;
+      if (pending >= GROOM_THRESHOLD && deps.spawnGroomer) deps.spawnGroomer();
+    }
+  }
+
+  deleteTrace(reflexDir, sessionId, promptId);
+  return { context: null };
+}
+
+const READ_ONLY_CMDS = ["cat", "ls", "git", "pwd", "head", "tail", "echo", "grep", "find"];
+const PURE_READ_CMDS = ["cat", "ls", "pwd", "head", "tail"];
+
+function isMutating(t, target) {
+  if (t === "Edit" || t === "Write" || t === "NotebookEdit") return true;
+  if (t === "Bash" || t === "bash") {
+    const cmd = (target || "").trim();
+    if (!cmd) return false;
+    const first = cmd.split(" ")[0];
+    if (READ_ONLY_CMDS.includes(first)) {
+      return first === "git" && /\s(commit|push|add|rm|mv)\b/.test(cmd);
+    }
+    return true;
+  }
+  return false;
+}
+
+function judge(lines, evt) {
+  const steps = lines.filter((l) => l.t !== "Goal" && l.t !== "Recall");
+  if (!steps.some((l) => isMutating(l.t, l.target))) return false;
+  if (evt.interrupted || evt.busy) return false;
+
+  const failed = new Set();
+  for (const l of steps) {
+    const key = `${l.t}|${l.target}`;
+    if (l.ok === false) failed.add(key);
+    else if (l.ok === true) failed.delete(key);
+  }
+  return failed.size === 0;
+}
+
+function synthesize(lines) {
+  const steps = [];
+  for (const l of lines) {
+    if (l.t === "Goal" || l.t === "Recall" || l.ok === false) continue;
+    if (l.t === "Read" || l.t === "View") continue;
+    if (l.t === "Bash" || l.t === "bash") {
+      const target = l.target || "";
+      if (PURE_READ_CMDS.includes(target.trim().split(" ")[0])) continue;
+      if (/^git (status|log|diff)/.test(target)) continue;
+    }
+    steps.push({ t: l.t, target: l.target });
+  }
+  return steps;
+}

package/lib/groomer.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PROVIDERS, resolveCredentials } from "./providers.js";
+
+// Silent Failure Logging
+function logError(proceduresFile, msg) {
+  const reflexDir = path.dirname(proceduresFile);
+  const logFile = path.join(reflexDir, "worker.log");
+  const timestamp = new Date().toISOString();
+  try {
+    fs.appendFileSync(logFile, `[${timestamp}] ${msg}\n`, "utf8");
+  } catch (e) {
+    // nowhere to log, silently fail
+  }
+}
+
+export async function runGroomer(proceduresFile) {
+  let creds;
+  try {
+    creds = resolveCredentials();
+  } catch (e) {
+    logError(proceduresFile, e.message);
+    return;
+  }
+  if (!creds) {
+    logError(
+      proceduresFile,
+      "No API key found. Run `npx agent-procedures auth login` or set ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY.",
+    );
+    return;
+  }
+  const { provider, apiKey, model } = creds;
+
+  if (!fs.existsSync(proceduresFile)) return;
+
+  const lines = fs
+    .readFileSync(proceduresFile, "utf8")
+    .split("\n")
+    .filter(Boolean);
+  const nodes = lines
+    .map((l) => {
+      try {
+        return JSON.parse(l);
+      } catch (e) {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  const pending = nodes.filter((n) => n.status === "pending_review");
+  if (pending.length === 0) return;
+
+  const prompt = `
+Here are ${pending.length} new execution nodes/edges added by a coding agent.
+
+<edges>
+${JSON.stringify(pending, null, 2)}
+</edges>
+
+For each item:
+1) Did the agent verify this worked? (e.g. ran a test, checked a log). If it just wrote code and blindly stopped without checking, it's risky.
+2) Is this a generic/reusable workflow, or a one-off anomaly?
+If it's unverified and risky, or a pure anomaly, decide to DROP it.
+If it's good, KEEP it.
+
+If you KEEP a root node (has no parent_id), generate 5-10 semantic aliases (synonyms) for its 'trigger' text so we can match variations of the user's prompt later.
+
+Return ONLY a JSON array of objects with this schema:
+[
+  {
+    "id": "node_id",
+    "action": "KEEP" | "DROP",
+    "aliases": ["alias1", "alias2"] // only if KEEP and root node
+  }
+]
+`;
+
+  let responseText;
+  try {
+    responseText = await PROVIDERS[provider].complete(apiKey, model, prompt);
+  } catch (err) {
+    logError(proceduresFile, err.message);
+    return;
+  }
+
+  let actions = [];
+  try {
+    const jsonStr = responseText
+      .replace(/```json/g, "")
+      .replace(/```/g, "")
+      .trim();
+    actions = JSON.parse(jsonStr);
+  } catch (e) {
+    logError(
+      proceduresFile,
+      "Failed to parse LLM JSON response: " + responseText,
+    );
+    return;
+  }
+
+  const newNodes = [];
+  for (const node of nodes) {
+    if (node.status === "pending_review") {
+      const actionDef = actions.find((a) => a.id === node.id);
+      if (actionDef) {
+        if (actionDef.action === "DROP") {
+          continue;
+        } else {
+          delete node.status;
+          if (!node.parent_id && actionDef.aliases) {
+            node.aliases = actionDef.aliases;
+          }
+        }
+      }
+    }
+    newNodes.push(node);
+  }
+
+  // Atomic Writes for the Groomer
+  const newFileContent =
+    newNodes.map((n) => JSON.stringify(n)).join("\n") + "\n";
+  const tmpFile = proceduresFile + ".tmp";
+  try {
+    fs.writeFileSync(tmpFile, newFileContent, "utf8");
+    fs.renameSync(tmpFile, proceduresFile);
+  } catch (err) {
+    logError(proceduresFile, `Failed atomic write: ${err.message}`);
+  }
+}

package/lib/harnesses/claude.js

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Claude Code adapter. Everything Claude-specific lives here.
+// Docs: https://code.claude.com/docs/en/hooks
+
+const EVENTS = ["UserPromptSubmit", "PostToolUse", "PostToolUseFailure", "Stop"];
+
+export default {
+  id: "claude",
+
+  /** Where the generated hook shim goes, relative to the repo root. */
+  hookFile: ".claude/hooks/reflex.mjs",
+
+  /** Merge our hooks into .claude/settings.json without touching anything else. */
+  register(cwd) {
+    const settingsPath = path.join(cwd, ".claude", "settings.json");
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+      } catch (e) {
+        console.warn("Failed to parse existing .claude/settings.json, overwriting...");
+      }
+    }
+    settings.hooks = settings.hooks || {};
+
+    for (const event of EVENTS) {
+      if (!Array.isArray(settings.hooks[event])) settings.hooks[event] = [];
+      const command = `node "$CLAUDE_PROJECT_DIR/${this.hookFile}" ${event}`;
+      const wired = settings.hooks[event].some((g) => (g.hooks || []).some((h) => h.command === command));
+      if (!wired) settings.hooks[event].push({ hooks: [{ type: "command", command }] });
+    }
+
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  },
+
+  /** Claude's stdin payload → normalized engine event, or null to ignore. */
+  normalize(eventName, payload) {
+    const name = payload.hook_event_name || eventName;
+    const base = { sessionId: payload.session_id, promptId: payload.prompt_id };
+
+    if (name === "UserPromptSubmit") {
+      return { type: "prompt", ...base, prompt: payload.prompt };
+    }
+    if (name === "PostToolUse" || name === "PostToolUseFailure") {
+      const tool = payload.tool_name;
+      const input = payload.tool_input || {};
+      let target = "";
+      if (tool === "Bash" || tool === "bash") target = input.command || "";
+      else if (typeof input === "string") target = input;
+      else target = input.target || input.file_path || input.path || "";
+      return { type: "tool", ...base, tool, target, ok: name === "PostToolUse" };
+    }
+    if (name === "Stop") {
+      return {
+        type: "stop",
+        ...base,
+        interrupted: payload.stop_hook_active === true,
+        busy: Array.isArray(payload.background_tasks) && payload.background_tasks.length > 0,
+      };
+    }
+    return null;
+  },
+
+  /** Engine result → what to print on stdout for Claude. */
+  render(evt, result) {
+    if (evt.type !== "prompt") return "";
+    if (!result.context) return "{}";
+    return JSON.stringify({
+      hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: result.context },
+    });
+  },
+};

package/lib/harnesses/index.js

@@ -0,0 +1,15 @@
+import claude from "./claude.js";
+
+// To add a harness: write lib/harnesses/<id>.js with the same shape as claude.js
+// (id, hookFile, register, normalize, render) and list it here.
+export const HARNESSES = { claude };
+
+export const DEFAULT_HARNESS = "claude";
+
+export function getHarness(id = DEFAULT_HARNESS) {
+  const h = HARNESSES[id];
+  if (!h) {
+    throw new Error(`Unknown harness "${id}". Available: ${Object.keys(HARNESSES).join(", ")}`);
+  }
+  return h;
+}

package/lib/init.js

@@ -1,11 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_HARNESS, getHarness } from "./harnesses/index.js";
+
+const LIB_DIR = path.dirname(fileURLToPath(import.meta.url));
 
 const DEFAULT_CONFIG = {
   version: 1,
-  harness: "cursor",
-  recall: true,
-  capture: true,
+  harness: "claude",
   minConfidence: 0.7,
   store: {
     procedures: "procedures.jsonl",
@@ -29,9 +31,14 @@ function writeIfMissing(filePath, contents) {
   return "created";
 }
 
+function writeAlways(filePath, contents) {
+  fs.writeFileSync(filePath, contents, "utf8");
+  return "updated";
+}
+
 function ensureGitignore(cwd) {
   const gitignorePath = path.join(cwd, ".gitignore");
-  const entry = ".reflex/";
+  const entry = ".reflex/traces/";
 
   if (!fs.existsSync(gitignorePath)) {
     fs.writeFileSync(gitignorePath, `${entry}\n`, "utf8");
@@ -41,7 +48,8 @@ function ensureGitignore(cwd) {
   const current = fs.readFileSync(gitignorePath, "utf8");
   const lines = current.split(/\r?\n/);
   const alreadyIgnored = lines.some(
-    (line) => line.trim() === ".reflex/" || line.trim() === ".reflex"
+    (line) =>
+      line.trim() === ".reflex/traces/" || line.trim() === ".reflex/traces",
   );
 
   if (alreadyIgnored) {
@@ -53,18 +61,71 @@ function ensureGitignore(cwd) {
   return "updated";
 }
 
-export function init(cwd = process.cwd()) {
+// Runtime that gets copied into <repo>/.reflex/engine/. npx doesn't leave the
+// package behind, so the repo has to carry the engine. Harness-neutral location
+// so several harnesses in one repo share a single copy.
+const ENGINE_FILES = [
+  "main.js",
+  "engine.js",
+  "store.js",
+  "groomer.js",
+  "providers.js",
+  "harnesses/index.js",
+  "harnesses/claude.js",
+];
+
+function installEngine(reflexDir) {
+  const engineDir = path.join(reflexDir, "engine");
+  for (const f of ENGINE_FILES) {
+    const dest = path.join(engineDir, f);
+    ensureDir(path.dirname(dest));
+    fs.copyFileSync(path.join(LIB_DIR, f), dest);
+  }
+  return "updated";
+}
+
+// A few lines that point the harness's hook at the shared engine.
+function writeShim(cwd, harness) {
+  const hookPath = path.join(cwd, harness.hookFile);
+  const enginePath = path.join(cwd, ".reflex", "engine", "main.js");
+  let rel = path.relative(path.dirname(hookPath), enginePath).split(path.sep).join("/");
+  if (!rel.startsWith(".")) rel = "./" + rel;
+
+  ensureDir(path.dirname(hookPath));
+  writeAlways(
+    hookPath,
+    `#!/usr/bin/env node
+// Generated by agent-procedures init. Re-run init to refresh; do not edit.
+import { run } from "${rel}";
+await run(${JSON.stringify(harness.id)});
+`,
+  );
+  fs.chmodSync(hookPath, 0o755);
+}
+
+export function init(cwd = process.cwd(), { harness: harnessId = DEFAULT_HARNESS } = {}) {
+  const harness = getHarness(harnessId);
   const reflexDir = path.join(cwd, ".reflex");
+  const tracesDir = path.join(reflexDir, "traces");
+
+  ensureDir(reflexDir);
+  ensureDir(tracesDir);
+
   const results = {
-    dir: ensureDir(reflexDir),
+    dir: "exists",
     config: writeIfMissing(
       path.join(reflexDir, "config.json"),
-      `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`
+      `${JSON.stringify({ ...DEFAULT_CONFIG, harness: harness.id }, null, 2)}\n`,
     ),
     procedures: writeIfMissing(path.join(reflexDir, "procedures.jsonl"), ""),
     runs: writeIfMissing(path.join(reflexDir, "runs.jsonl"), ""),
     gitignore: ensureGitignore(cwd),
+    engine: installEngine(reflexDir),
   };
 
+  writeShim(cwd, harness);
+  harness.register(cwd);
+  results.hooks = "updated";
+
   return results;
 }

package/lib/main.js

@@ -0,0 +1,52 @@
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { handleEvent } from "./engine.js";
+import { getHarness } from "./harnesses/index.js";
+
+// Entry point for the generated hook shim. Lives in <repo>/.reflex/engine/,
+// so .reflex/ is one level up.
+const REFLEX_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.on("error", () => resolve(data));
+  });
+}
+
+function spawnGroomer() {
+  const child = spawn(process.argv[0], [process.argv[1], "Groom"], { detached: true, stdio: "ignore" });
+  child.unref();
+}
+
+export async function run(harnessId, argv = process.argv.slice(2)) {
+  const [eventName] = argv;
+  if (!eventName) return;
+
+  if (eventName === "Groom") {
+    const { runGroomer } = await import("./groomer.js");
+    await runGroomer(path.join(REFLEX_DIR, "procedures.jsonl"));
+    return;
+  }
+
+  const raw = await readStdin();
+  if (!raw) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (e) {
+    return;
+  }
+
+  const harness = getHarness(harnessId);
+  const evt = harness.normalize(eventName, payload);
+  if (!evt) return;
+
+  const result = handleEvent(evt, REFLEX_DIR, { spawnGroomer });
+  const out = harness.render(evt, result);
+  if (out) process.stdout.write(out + "\n");
+}

package/lib/providers.js

@@ -0,0 +1,178 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// Shared by `auth` (CLI) and the groomer (background hook). Keep dependency-free.
+
+export function reflexHome() {
+  return process.env.REFLEX_HOME || path.join(os.homedir(), ".reflex");
+}
+
+export function credentialsFile() {
+  return path.join(reflexHome(), "credentials.json");
+}
+
+const SYSTEM_PROMPT =
+  "You are the Reflex graph groomer. Your job is to review execution edges from coding agents, drop bad ones, and add semantic aliases.";
+
+async function expectOk(res, label) {
+  if (res.ok) return;
+  let detail = await res.text().catch(() => "");
+  try {
+    // All three providers return { error: { message } } on failure.
+    detail = JSON.parse(detail).error?.message || detail;
+  } catch (e) {}
+  detail = detail.replace(/\s+/g, " ").trim().slice(0, 200);
+  throw new Error(`${label} API error: ${res.status} ${res.statusText}${detail ? ` - ${detail}` : ""}`);
+}
+
+export const PROVIDERS = {
+  anthropic: {
+    label: "Anthropic",
+    envVar: "ANTHROPIC_API_KEY",
+    defaultModel: "claude-haiku-4-5",
+    keyPrefix: "sk-ant-",
+    keysUrl: "https://console.anthropic.com/settings/keys",
+    async verify(apiKey) {
+      const res = await fetch("https://api.anthropic.com/v1/models?limit=1", {
+        headers: { "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
+      });
+      await expectOk(res, "Anthropic");
+    },
+    async complete(apiKey, model, prompt) {
+      const res = await fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          model,
+          max_tokens: 1024,
+          system: SYSTEM_PROMPT,
+          messages: [{ role: "user", content: prompt }],
+        }),
+      });
+      await expectOk(res, "Anthropic");
+      const data = await res.json();
+      return data.content[0].text;
+    },
+  },
+
+  openai: {
+    label: "OpenAI",
+    envVar: "OPENAI_API_KEY",
+    defaultModel: "gpt-6-luna",
+    keyPrefix: "sk-",
+    keysUrl: "https://platform.openai.com/api-keys",
+    async verify(apiKey) {
+      const res = await fetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+      await expectOk(res, "OpenAI");
+    },
+    async complete(apiKey, model, prompt) {
+      const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          model,
+          max_tokens: 1024,
+          messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: prompt },
+          ],
+        }),
+      });
+      await expectOk(res, "OpenAI");
+      const data = await res.json();
+      return data.choices[0].message.content;
+    },
+  },
+
+  gemini: {
+    label: "Gemini",
+    envVar: "GEMINI_API_KEY",
+    defaultModel: "gemini-3.5-flash-lite",
+    keyPrefix: "AIza",
+    keysUrl: "https://aistudio.google.com/apikey",
+    async verify(apiKey) {
+      const res = await fetch(
+        "https://generativelanguage.googleapis.com/v1beta/models?pageSize=1",
+        { headers: { "x-goog-api-key": apiKey } },
+      );
+      await expectOk(res, "Gemini");
+    },
+    async complete(apiKey, model, prompt) {
+      const res = await fetch(
+        `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`,
+        {
+          method: "POST",
+          headers: {
+            "x-goog-api-key": apiKey,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({
+            system_instruction: { parts: [{ text: SYSTEM_PROMPT }] },
+            contents: [{ role: "user", parts: [{ text: prompt }] }],
+            generationConfig: { maxOutputTokens: 1024 },
+          }),
+        },
+      );
+      await expectOk(res, "Gemini");
+      const data = await res.json();
+      return data.candidates[0].content.parts[0].text;
+    },
+  },
+};
+
+export const PROVIDER_NAMES = Object.keys(PROVIDERS);
+
+export function readCredentials() {
+  const file = credentialsFile();
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+/**
+ * Resolve which provider/key/model the groomer should use.
+ *
+ * Provider: credentials.json's defaultProvider if present, else the first
+ * provider with an env var set.
+ * Key: the provider's env var wins over the stored key.
+ * Model: stored model, else the provider default.
+ *
+ * Returns null if nothing usable is found.
+ */
+export function resolveCredentials(env = process.env) {
+  let stored = null;
+  try {
+    stored = readCredentials();
+  } catch (e) {
+    throw new Error(`Failed to parse ${credentialsFile()}: ${e.message}`);
+  }
+
+  let provider = stored?.defaultProvider;
+  if (!provider) {
+    provider = PROVIDER_NAMES.find((p) => env[PROVIDERS[p].envVar]);
+  }
+  if (!provider || !PROVIDERS[provider]) return null;
+
+  const def = PROVIDERS[provider];
+  const entry = stored?.providers?.[provider] || {};
+
+  const envKey = env[def.envVar];
+  const apiKey = envKey || entry.apiKey;
+  if (!apiKey) return null;
+
+  return {
+    provider,
+    apiKey,
+    model: entry.model || def.defaultModel,
+    source: envKey ? "env" : "file",
+  };
+}

package/lib/store.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Disk layout under .reflex/. Harness-free.
+
+export function paths(reflexDir) {
+  return {
+    reflexDir,
+    tracesDir: path.join(reflexDir, "traces"),
+    proceduresFile: path.join(reflexDir, "procedures.jsonl"),
+  };
+}
+
+function readJsonl(file) {
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+
+export function traceFile(reflexDir, sessionId, promptId) {
+  return path.join(paths(reflexDir).tracesDir, sessionId, `${promptId}.jsonl`);
+}
+
+export function startTrace(reflexDir, sessionId, promptId, goal) {
+  const file = traceFile(reflexDir, sessionId, promptId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(goal) + "\n", "utf8");
+}
+
+export function appendTrace(reflexDir, sessionId, promptId, line) {
+  const file = traceFile(reflexDir, sessionId, promptId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(line) + "\n", "utf8");
+}
+
+export function readTrace(reflexDir, sessionId, promptId) {
+  return readJsonl(traceFile(reflexDir, sessionId, promptId));
+}
+
+export function deleteTrace(reflexDir, sessionId, promptId) {
+  try {
+    fs.unlinkSync(traceFile(reflexDir, sessionId, promptId));
+  } catch (e) {}
+}
+
+export function readProcedures(reflexDir) {
+  return readJsonl(paths(reflexDir).proceduresFile);
+}
+
+export function appendProcedure(reflexDir, node) {
+  const file = paths(reflexDir).proceduresFile;
+  if (!fs.existsSync(file)) fs.writeFileSync(file, "", "utf8");
+  fs.appendFileSync(file, JSON.stringify(node) + "\n", "utf8");
+}

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "agent-procedures",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Procedural memory for coding agents",
   "type": "module",
-  "bin": "./bin/cli.js",
+  "bin": {
+    "agent-procedures": "./bin/cli.js"
+  },
   "files": [
     "bin",
     "lib"
@@ -11,6 +13,9 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "test": "vitest run"
+  },
   "keywords": [
     "agents",
     "coding-agents",
@@ -27,5 +32,8 @@
   "bugs": {
     "url": "https://github.com/itskrishna21/reflex/issues"
   },
-  "homepage": "https://github.com/itskrishna21/reflex#readme"
+  "homepage": "https://github.com/itskrishna21/reflex#readme",
+  "devDependencies": {
+    "vitest": "^5.0.3"
+  }
 }