agent-procedures 0.1.0 → 0.3.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
+  runtime.js         # the engine, one bundled file — do not edit
+  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. That overwrites `runtime.js`.
+
+## 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/runtime.js        ${results.runtime}`);
+    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}`);