@fingerskier/augment 0.1.10 → 0.2.0

package/docs/verify-memory-flow.md

@@ -7,7 +7,7 @@ relying on the agent to remember to call the MCP tools:
 | ------------------ | ---------------------------------- | ------ |
 | `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). |
+| `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). Uses a raised relevance floor (`min_score` 0.45 — above the 0.4 search default, calibrated on the real model because tool queries are command/path-shaped, not prose) and injects each distinct query at most once per session. |
 | `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
@@ -33,7 +33,8 @@ 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).
+  envelope + 0.45 floor + per-session dedupe, 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.
@@ -76,6 +77,17 @@ 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.
 
+Two footnotes on the examples: they omit `session_id`, which deliberately skips
+the PreToolUse once-per-session dedupe — include one to demo it. And the Stop
+loop-guard marker persists in the OS tmpdir, so re-running the stop example
+later with the same `session_id`/`prompt_id` yields empty on the *first* call
+too — use fresh ids per run.
+
+For a binding version of the ranking-quality check, `npm run test:model` runs
+the pinned real-bge abstention/recall tripwires
+(`test/real-model-abstention.model.ts`) — what this layer can otherwise only
+eyeball.
+
 ## 3. Real project (host-level hook firing)
 
 1. Install into a repo (or user scope):
@@ -100,13 +112,20 @@ eyeballing here.
 
 ## 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.
+- **Hook startup cost (resolved).** Hooks now invoke the install-time-provisioned
+  runtime directly (`node <prefix>/node_modules/@fingerskier/augment/dist/bin/augment.js
+  hook <event>`, tens of milliseconds) — the old `npm exec --yes` form paid a
+  multi-second npm bootstrap per event. Residual caveat: provisioning is
+  best-effort. If npm was missing at install time the installer prints a manual
+  `npm install --prefix <prefix> @fingerskier/augment` command and hooks fail
+  open (silent no-ops) until it is run. The MCP server itself still launches via
+  `npm exec`; only the hook hot path changed.
 - **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.
+- **Retrieval floor calibration (resolved).** The `(cos+1)/2` mis-normalization
+  is fixed by an empirically-anchored cosine rescale (`SEMANTIC_COSINE_BASELINE`
+  0.33), and abstention is now proven on the real model by `npm run test:model`.
+  Remaining retrieval-quality follow-ups (Phase 2 dogfood tally, credential-warn,
+  HF revision pin) are tracked in `.council/memory/retrieval-quality-roadmap.md`
+  and [ROADMAP.md](../ROADMAP.md).

package/package.json

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