@fingerskier/augment 0.1.3 → 0.1.5

package/docs/verify-memory-flow.md

@@ -0,0 +1,112 @@
+# Verifying the auto-memory flow
+
+Augment now *enforces* the memory loop through host lifecycle hooks rather than
+relying on the agent to remember to call the MCP tools:
+
+| Event              | Hook command                       | Effect |
+| ------------------ | ---------------------------------- | ------ |
+| `SessionStart`     | `augment hook session-start`       | Warms the daemon and registers the project. |
+| `UserPromptSubmit` | `augment hook user-prompt-submit`  | Recalls relevant memory and injects it as `additionalContext` **before** the model sees the prompt. |
+| `PreToolUse`       | `augment hook pre-tool-use`        | Recalls **additional** memory keyed to the matched tool action (the edited file / the Bash command) and injects it as `additionalContext`. Matcher-scoped to `Edit\|Write\|Bash` to bound the hot path; injection-only (never blocks, gates, or rewrites a tool call). |
+| `Stop`             | `augment hook stop`                | Blocks the turn **once** with a directive to upsert a memory, then allows the stop (loop-guarded per turn). |
+
+`PreToolUse` fires before **every matched** tool call, so it is the only hook with a tool-name
+`matcher` (the others fire once per prompt/turn). Two host nuances: on Claude the injected text
+rides alongside the *tool result* on the next model request (it supplements, rather than precedes,
+the action); on Codex builds older than ~0.124.0 `PreToolUse` `additionalContext` is rejected and
+silently dropped (the tool still runs). It is purely additive — `UserPromptSubmit` remains the
+guaranteed memory path on both hosts.
+
+The same `hooks/hooks.json` ships in both the Claude Code and Codex plugins
+(Codex copied Claude's event names + stdin/stdout contract), so one set of
+handlers serves both hosts.
+
+This doc is the test process. Run the layers top-to-bottom; each is cheaper and
+more isolated than the one below it.
+
+## 1. Automated (no network, no host) — `npm test`
+
+```sh
+npm test
+```
+
+Covers:
+- `test/hooks.test.ts` — the stdin→stdout contract of every hook event
+  (UserPromptSubmit envelope, PreToolUse tool-query derivation + injection-only
+  envelope, Stop block-once loop guard, fail-open paths).
+- `test/recall.test.ts` — recall degrades to `""` on any failure (a hook must
+  never break the agent).
+- `test/cli.test.ts` — the `recall` and `hook` CLI commands.
+- `test/install.test.ts` — the installer writes `hooks/hooks.json` for both hosts.
+- `test/integration/memory-flow.test.ts` — a planted memory flows
+  upsert → index → `recall()` → UserPromptSubmit **and** PreToolUse envelopes, against a **real**
+  `AugmentService` (real store + sqlite index), using the deterministic hash
+  embedder. Proves the wiring end-to-end without a model download.
+
+## 2. CLI smoke (real daemon + real embeddings, one machine)
+
+Build first, then drive the real daemon by hand. Use a throwaway memory root so
+you don't pollute your real memories:
+
+```sh
+npm run build
+export AUGMENT_MEMORY_ROOT="$(mktemp -d)"      # PowerShell: $env:AUGMENT_MEMORY_ROOT = (New-Item -ItemType Directory -Path $env:TEMP\augver -Force).FullName
+
+# Plant a memory (project_id 1 after the first init), then recall it.
+node ./dist/bin/augment.js recall "the deploy pipeline"      # prints recalled text (empty until something is stored)
+
+# Exercise the hook handlers exactly as a host would (JSON on stdin):
+echo '{"user_input":"fix the deploy pipeline","cwd":"."}' | node ./dist/bin/augment.js hook user-prompt-submit
+#   -> {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
+
+# PreToolUse keys the query off the tool action (Bash -> command, Edit/Write -> file_path):
+echo '{"tool_name":"Bash","tool_input":{"command":"deploy the pipeline"},"cwd":"."}' | node ./dist/bin/augment.js hook pre-tool-use
+#   -> {"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
+echo '{"tool_name":"Read","tool_input":{"file_path":"x"}}' | node ./dist/bin/augment.js hook pre-tool-use
+#   -> (empty)  Read isn't in the installed matcher; even if invoked it derives a query but stays injection-only
+
+echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
+#   -> {"decision":"block","reason":"Before ending this turn, record durable memory ..."}
+echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
+#   -> (empty)  second stop for the same turn is allowed — proves the loop guard
+```
+
+The first `recall`/`hook user-prompt-submit` call auto-starts the daemon and, on
+a cold machine, downloads the bge-small model — so the very first run is slow.
+This is real-model retrieval; ranking quality (not just wiring) is what you're
+eyeballing here.
+
+## 3. Real project (host-level hook firing)
+
+1. Install into a repo (or user scope):
+   ```sh
+   npm exec --yes --package @fingerskier/augment -- augment install all --scope repo --memory-root "<your shared memory root>"
+   ```
+2. Confirm the plugin is actually installed/enabled — hooks only fire when the
+   plugin is active:
+   - **Claude Code:** `/plugin` → `augment` listed and enabled. The installer
+     best-effort-registers it via the `claude` CLI; if that was skipped, run the
+     printed `/plugin marketplace add … && /plugin install …` commands.
+   - **Codex:** plugin-shipped hooks need a **one-time trust** — run `/hooks` and
+     approve the augment hooks. (Managed/enterprise distribution can pre-trust;
+     a plain plugin install cannot.)
+3. Observe the loop on a real task:
+   - **Inject:** start a session and give a task that matches something in your
+     memory. The recalled block ("## Augment memory (recalled for this task)")
+     should appear in the model's context — confirm it influenced the answer.
+   - **Capture:** finish the task. The Stop hook should prompt the agent to
+     `upsert` a WORK/ARCH/ISSUE/TODO/SPEC memory; confirm a new file appears under
+     your memory root and that `augment recall` surfaces it next time.
+
+## Known caveats (logged, not blockers)
+
+- **Per-prompt latency.** Each hook shells out via `npm exec --yes` (self-bootstrapping,
+  matches the MCP server). On UserPromptSubmit that adds startup overhead before
+  every prompt. A direct-node invocation is a planned optimization.
+- **Claude hook activation depends on plugin install.** The MCP server is also
+  direct-registered (so the tools always exist), but the hooks live in the plugin;
+  if the plugin isn't installed, the loop degrades to the CLAUDE.md prose guidance.
+- **Retrieval floor calibration.** Real bge-small cosine is mis-normalized
+  (`(cos+1)/2`), so abstention is weaker than intended on the real model — see
+  `.council/memory/retrieval-quality-roadmap.md`. The flow still injects; it just
+  may inject loosely-related memory. Tracked separately.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fingerskier/augment",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Local RAG memory system for coding agents",
   "type": "module",
   "publishConfig": {