agent-working-memory 0.14.6 → 0.15.4

package/dist/storage/factory.js

@@ -44,15 +44,27 @@ import { existsSync, statSync } from 'node:fs';
 function detectBackendFromDisk() {
     // If AWM_DB_PATH is set, infer from its shape.
     const explicitPath = process.env.AWM_DB_PATH;
-    if (explicitPath && existsSync(explicitPath)) {
-        try {
-            const stat = statSync(explicitPath);
-            if (stat.isDirectory())
-                return 'pglite'; // PGlite uses a directory
-            if (stat.isFile())
-                return 'sqlite'; // SQLite is a single file
+    if (explicitPath) {
+        if (existsSync(explicitPath)) {
+            try {
+                const stat = statSync(explicitPath);
+                if (stat.isDirectory())
+                    return 'pglite'; // PGlite uses a directory
+                if (stat.isFile())
+                    return 'sqlite'; // SQLite is a single file
+            }
+            catch { /* fall through to the default below */ }
         }
-        catch { /* fall through */ }
+        // The caller named a path that does not exist yet — a brand-new store. Default it to
+        // SQLite and STOP: falling through to the cwd conventions below would pick the backend
+        // from files that have nothing to do with the path that was asked for.
+        //
+        // Not hypothetical. Running from a checkout containing a `memory-pglite/` directory
+        // made a fresh AWM_DB_PATH=/tmp/new-store.db resolve to PGlite, which is
+        // single-process — so two surfaces pointed at 'the same store' would have had the
+        // second refuse to start. Found by the cross-surface end-to-end test.
+        // PGlite at a new path is still reachable via AWM_STORE_BACKEND=pglite.
+        return 'sqlite';
     }
     // Otherwise look for the conventional defaults in cwd.
     // PGlite directory wins over SQLite file when both exist — assume the

package/dist/storage/factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/storage/factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/storage/factory.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-working-memory",
-  "version": "0.14.6",
+  "version": "0.15.4",
   "description": "Persistent, local-first memory for AI agents. Selective by design: filters what's worth keeping, links what's related, and says nothing when it doesn't know. SQLite + ONNX, no cloud, no API keys.",
   "keywords": [
     "ai-agents",
@@ -27,7 +27,10 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build && npm run check:release",
+    "build:plugin": "node scripts/build-plugin.mjs",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
+    "pack:mcpb": "node scripts/build-mcpb.mjs --pack",
+    "prepublishOnly": "npm run build && npm run build:plugin && npm run build:mcpb && npm run check:release",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "test": "vitest",
@@ -51,7 +54,8 @@
     "check:release": "node scripts/check-release.mjs",
     "bench": "node scripts/bench-current.mjs",
     "test:docker": "bash scripts/docker-release-test.sh",
-    "test:linux": "bash scripts/docker-release-test.sh linux"
+    "test:linux": "bash scripts/docker-release-test.sh linux",
+    "test:desktop": "bash scripts/docker-release-test.sh desktop"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -60,6 +64,8 @@
   "files": [
     "dist/",
     "src/",
+    "plugin/",
+    ".claude-plugin/",
     "package.json",
     "README.md",
     "LICENSE"

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "awm",
+  "displayName": "Agent Working Memory",
+  "version": "0.15.4",
+  "description": "Persistent, local-first memory for AI agents. Selective by design: filters what's worth keeping, links what's related, and says nothing when it doesn't know. SQLite + ONNX, no cloud, no API keys.",
+  "author": {
+    "name": "Robert Winter"
+  },
+  "homepage": "https://completeideas.github.io/agent-working-memory/",
+  "repository": "https://github.com/CompleteIdeas/agent-working-memory",
+  "license": "Apache-2.0",
+  "keywords": [
+    "memory",
+    "mcp",
+    "recall",
+    "agent"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": {
+    "agent-working-memory": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/bin/awm-mcp-launcher.cjs"
+      ],
+      "env": {
+        "AWM_RERANK2": "1",
+        "AWM_RERANK_WINDOW": "query",
+        "AWM_RERANK_TAGS": "1",
+        "AWM_CLIENT": "claude-code"
+      }
+    }
+  }
+}

package/plugin/README.md

@@ -0,0 +1,36 @@
+# AWM — Claude Code plugin
+
+Installs Agent Working Memory as a plugin: the MCP server, the session hooks, and the usage
+guidance, all versioned together. This is the plugin equivalent of `awm setup --global`.
+
+**This directory is generated.** `npm run build:plugin` emits it from the same modules the
+installer uses, and `npm run check:release` fails if the committed output has drifted. Edit
+`src/adapters/`, not these files.
+
+## What it installs
+
+| | |
+|---|---|
+| MCP server | 1 server, 19 memory tools, via `bin/awm-mcp-launcher.cjs` |
+| Hooks | Stop, PreCompact, SessionEnd, UserPromptSubmit (prime), PostToolUse — hooks v0.14.6 |
+| Skill | `awm-memory` — when to recall, when to write, how to tag |
+
+## The store
+
+The launcher defaults `AWM_DB_PATH` to `~/.awm/memory.db` — **the same file
+`awm setup --global` uses** — so a plugin install shares memory with a CLI install rather
+than quietly starting an empty one. Set `AWM_DB_PATH` yourself to override.
+
+It prefers an installed copy of the package (global, or a local `node_modules`) and falls
+back to `npx -p agent-working-memory@0.15.4`. The npx path rebuilds
+`better-sqlite3` on a cold cache, which is slow enough to look like a hang, so a real
+install is worth having:
+
+```bash
+npm install -g agent-working-memory
+```
+
+## Turning prime off
+
+`UserPromptSubmit` primes relevant memory into context. To silence it without uninstalling,
+create an empty `~/.claude/hooks/awm-prime.disabled`.

package/plugin/bin/awm-mcp-launcher.cjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+//
+// Entry point for the Claude Code plugin's MCP server.
+//
+// This is a REAL source file, not a string inside the generator, because it is real code:
+// it gets syntax-checked, linted and tested like everything else. `npm run build:plugin`
+// copies it to plugin/bin/ and substitutes 0.15.4.
+//
+// Two jobs a bare `mcpServers` entry in plugin.json cannot do:
+//
+//   1. Default the store to ~/.awm/memory.db — the SAME file `awm setup --global` writes.
+//      Without this the plugin opens its own empty database and "your memory follows you
+//      between Claude Code, Desktop and Cowork" is simply false.
+//
+//   2. Find the server. A plugin does not know whether the package is installed globally,
+//      sits in a local node_modules, or is a checkout on disk.
+//
+// Fails loudly on stderr. A silent exit here looks like "the memory tools just aren't there",
+// which is the least debuggable failure this could have.
+'use strict';
+
+const { join, resolve, sep } = require('node:path');
+const { homedir } = require('node:os');
+const { existsSync } = require('node:fs');
+const { pathToFileURL } = require('node:url');
+const { spawn, execFileSync } = require('node:child_process');
+
+const NL = '\n';
+
+// Claude Desktop substitutes user_config values into env, and a field the user cleared
+// arrives as an empty string rather than being absent. An empty AWM_AGENT_ID would override
+// the server's directory-derived default with nothing, so drop empties before anything reads
+// them and let the normal defaults apply.
+for (const k of ['AWM_DB_PATH', 'AWM_AGENT_ID', 'AWM_HOOK_PORT', 'AWM_PACKAGE_ROOT']) {
+  if (process.env[k] !== undefined && String(process.env[k]).trim() === '') delete process.env[k];
+}
+
+// An explicit AWM_DB_PATH always wins, so per-project pools still work.
+if (!process.env.AWM_DB_PATH) {
+  process.env.AWM_DB_PATH = join(homedir(), '.awm', 'memory.db').split(sep).join('/');
+}
+
+const tried = [];
+function candidate(p) {
+  if (!p) return null;
+  tried.push(p);
+  return existsSync(p) ? p : null;
+}
+
+// In priority order. npx is last: on a cold cache it rebuilds better-sqlite3, which takes
+// minutes and is indistinguishable from a hang.
+let found =
+  // 1. An explicit override.
+  candidate(process.env.AWM_PACKAGE_ROOT && join(process.env.AWM_PACKAGE_ROOT, 'dist', 'mcp.js')) ||
+  // 2. The plugin sitting inside an AWM checkout (plugin/bin -> ../../dist).
+  candidate(resolve(__dirname, '..', '..', 'dist', 'mcp.js')) ||
+  // 3. A local dependency of the project being worked on.
+  candidate(join(process.cwd(), 'node_modules', 'agent-working-memory', 'dist', 'mcp.js'));
+
+// 4. A global install. require.resolve does not search global roots, so ask npm once.
+if (!found) {
+  try {
+    const isWin = process.platform === 'win32';
+    const root = execFileSync(isWin ? 'npm.cmd' : 'npm', ['root', '-g'], {
+      encoding: 'utf-8',
+      shell: isWin,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    found = candidate(root && join(root, 'agent-working-memory', 'dist', 'mcp.js'));
+  } catch {
+    /* npm not on PATH — fall through */
+  }
+}
+
+// 5. Anywhere node can resolve it from here.
+if (!found) {
+  try {
+    found = require.resolve('agent-working-memory/dist/mcp.js');
+  } catch {
+    /* not installed where this script can see it */
+  }
+}
+
+if (found) {
+  // dist/ is ESM ("type": "module"), so import() — require() throws ERR_REQUIRE_ESM.
+  import(pathToFileURL(found).href).catch((e) => {
+    process.stderr.write('[awm] failed to load ' + found + ': ' + e.message + NL);
+    process.exit(1);
+  });
+} else {
+  // Last resort, pinned so the tools match the hook scripts shipped beside them.
+  // shell:true on Windows: spawning npx.cmd directly throws EINVAL since Node 18.20/20.12.
+  const isWin = process.platform === 'win32';
+  const child = spawn(
+    isWin ? 'npx.cmd' : 'npx',
+    ['-y', '-p', 'agent-working-memory@0.15.4', 'awm', 'mcp'],
+    { stdio: 'inherit', env: process.env, shell: isWin }
+  );
+  child.on('error', (e) => {
+    process.stderr.write('[awm] could not start the MCP server: ' + e.message + NL);
+    process.stderr.write('[awm] looked in:' + NL);
+    for (const t of tried) process.stderr.write('  ' + t + NL);
+    process.stderr.write('[awm] fix: npm install -g agent-working-memory' + NL);
+    process.exit(1);
+  });
+  child.on('exit', (code) => process.exit(code == null ? 0 : code));
+}

package/plugin/hooks/awm-checkpoint.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// awm-checkpoint.cjs — installed by `awm setup` (hooks v0.14.6). PreCompact / SessionEnd: checkpoint this session into ITS agent's AWM.
+// Re-running `awm setup` rewrites this file; put local changes elsewhere.
+// Fails open: on any problem it prints nothing and exits 0.
+
+// Forwards the whole hook payload (hook_event_name, transcript_path, cwd,
+// session_id) to POST /hooks/checkpoint on the sidecar that belongs to this
+// session's agent. transcript_path matters: the sidecar parses it for the
+// current task and active files, so the checkpoint is a real one, not a stub.
+'use strict';
+const http = require('http');
+
+let finder = null;
+try { finder = require('./awm-find-sidecar.cjs'); } catch (e) { process.exit(0); }
+
+const TIMEOUT_MS = 5000;
+
+let raw = '';
+process.stdin.on('data', function (d) { raw += d; });
+process.stdin.on('end', function () {
+  let payload = {};
+  try { payload = JSON.parse(raw || '{}'); } catch (e) { payload = {}; }
+  if (!payload.hook_event_name) payload.hook_event_name = 'PreCompact';
+  main(payload).catch(function () { process.exit(0); });
+});
+// A hook with nothing on stdin must still exit.
+process.stdin.on('error', function () { process.exit(0); });
+
+async function main(payload) {
+  const found = await finder.findSidecar(payload.cwd);
+  const sc = found.sidecar;
+  if (!sc) {
+    finder.debugLog('checkpoint', { event: payload.hook_event_name, agent: found.config.agentId, sidecar: null, live: found.all.length });
+    process.exit(0);
+  }
+  const body = JSON.stringify(payload);
+  const req = http.request({
+    host: '127.0.0.1', port: sc.port, path: '/hooks/checkpoint', method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'Authorization': 'Bearer ' + found.config.secret,
+    },
+    timeout: TIMEOUT_MS,
+  }, function (res) {
+    res.resume();
+    res.on('end', function () {
+      finder.debugLog('checkpoint', { event: payload.hook_event_name, agent: found.config.agentId, port: sc.port, status: res.statusCode });
+      process.exit(0);
+    });
+  });
+  req.on('error', function () { process.exit(0); });
+  req.on('timeout', function () { req.destroy(); process.exit(0); });
+  req.end(body);
+}

package/plugin/hooks/awm-db-mutation-reminder.cjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// AWM DB-mutation reminder hook (PostToolUse on Bash|PowerShell). Installed by awm setup.
+let raw = '';
+process.stdin.on('data', (d) => (raw += d));
+process.stdin.on('end', () => {
+  try {
+    const j = JSON.parse(raw || '{}');
+    const cmd = (j.tool_input && j.tool_input.command) || '';
+    const isDbClient = /\b(sqlcmd|mysql|psql)\b/i.test(cmd) || /(sqlcmd|mysql|psql)\.exe/i.test(cmd);
+    const isMutation = /\b(INSERT|UPDATE|DELETE|ALTER|TRUNCATE|DROP|MERGE)\b/i.test(cmd);
+    if (isDbClient && isMutation) {
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PostToolUse',
+          additionalContext:
+            'AWM REMINDER: this command contains a production DB mutation (INSERT/UPDATE/DELETE/ALTER/DROP/TRUNCATE/MERGE). ' +
+            'The change is NOT complete until it is recorded: call memory_write NOW with the table, what changed, row counts, date, and why ' +
+            '(memory_class canonical if other agents must recall it), and confirm a rollback/backup exists. ' +
+            'If the keywords were only in a string/comment or on temp tables (#...), no write is needed.',
+        },
+      }));
+    }
+  } catch (e) { /* never block the tool result */ }
+  process.exit(0);
+});

package/plugin/hooks/awm-find-sidecar.cjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// awm-find-sidecar.cjs — installed by `awm setup` (hooks v0.14.6). Shared resolver: which AWM sidecar belongs to THIS session.
+// Re-running `awm setup` rewrites this file; put local changes elsewhere.
+// Fails open: on any problem it prints nothing and exits 0.
+
+// Since AWM 0.14.2 each MCP process binds the first free port in
+// [AWM_HOOK_PORT, +AWM_HOOK_PORT_RANGE), so "the sidecar is on 8401" is not a
+// safe assumption: with N sessions open there are N sidecars and the one on
+// 8401 may serve a different agent pool. This module (1) works out which agent
+// a session started in `cwd` belongs to, from the MCP config that governs that
+// directory, (2) probes the whole range in parallel (local, ~10 ms), and
+// (3) returns the responder whose agentId matches — newest version first, then
+// lowest port. No match → null, and callers fail open.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+
+const SERVER_NAME = 'agent-working-memory';
+const PROBE_TIMEOUT_MS = 400;
+
+function norm(p) { return String(p || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase(); }
+function readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (e) { return null; } }
+function readText(p) { try { return fs.readFileSync(p, 'utf8').trim(); } catch (e) { return ''; } }
+
+// MIRROR of deriveAgentFromDir() in src/core/agent-id.ts — the server's own
+// fallback when AWM_AGENT_ID is unset. Kept in sync by tests/adapters/hook-scripts.test.ts.
+function deriveAgentFromDir(dir) {
+  const d = String(dir || '').replace(/\\/g, '/');
+  if (/\/AgentSynapse\//i.test(d)) return 'work';
+  return /\/Personal-Projects(\/|$)/i.test(d) ? 'personal' : 'work';
+}
+
+// The AWM entry inside one MCP config file, if any. ~/.claude.json keeps
+// project-scoped servers under projects[<path>].mcpServers.
+function awmEntry(json, cwd) {
+  if (!json) return null;
+  if (json.mcpServers && json.mcpServers[SERVER_NAME]) return json.mcpServers[SERVER_NAME];
+  if (json.projects && cwd) {
+    for (const k of Object.keys(json.projects)) {
+      if (norm(k) !== norm(cwd)) continue;
+      const s = json.projects[k] && json.projects[k].mcpServers;
+      if (s && s[SERVER_NAME]) return s[SERVER_NAME];
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the configuration that governs a session started in `cwd`:
+ * { agentId, secret, port, range, dbPath, source }.
+ *
+ * Order: the nearest .mcp.json / .claude/mcp.json walking up from cwd, then
+ * ~/.mcp.json, then ~/.claude.json, then the record `awm setup` left in
+ * ~/.claude/hooks/awm-hooks.json. Process env always wins for a given key.
+ */
+function resolveConfig(cwd) {
+  cwd = cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const home = os.homedir();
+  const candidates = [];
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 16; i++) {
+    candidates.push(path.join(dir, '.mcp.json'), path.join(dir, '.claude', 'mcp.json'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  candidates.push(path.join(home, '.mcp.json'), path.join(home, '.claude.json'));
+
+  let entry = null, source = null;
+  for (const c of candidates) {
+    const e = awmEntry(readJson(c), cwd);
+    if (e) { entry = e; source = c; break; }
+  }
+  const env = (entry && entry.env) || {};
+  const fallback = readJson(path.join(home, '.claude', 'hooks', 'awm-hooks.json')) || {};
+
+  const agentId = process.env.AWM_AGENT_ID || env.AWM_AGENT_ID
+    || (entry ? deriveAgentFromDir(cwd) : (fallback.agentId || deriveAgentFromDir(cwd)));
+  const dbPath = env.AWM_DB_PATH || fallback.dbPath || null;
+  let secret = process.env.AWM_HOOK_SECRET || env.AWM_HOOK_SECRET || '';
+  if (!secret && dbPath) secret = readText(path.join(path.dirname(dbPath), '.awm-hook-secret'));
+  if (!secret && fallback.secretPath) secret = readText(fallback.secretPath);
+  const port = parseInt(process.env.AWM_HOOK_PORT || env.AWM_HOOK_PORT || fallback.hookPort || '8401', 10) || 8401;
+  const range = Math.max(1, parseInt(process.env.AWM_HOOK_PORT_RANGE || env.AWM_HOOK_PORT_RANGE || fallback.hookPortRange || '10', 10) || 10);
+  return { agentId: agentId, secret: secret, port: port, range: range, dbPath: dbPath, source: source };
+}
+
+function probe(port) {
+  return new Promise(function (resolve) {
+    const req = http.get({ host: '127.0.0.1', port: port, path: '/health', timeout: PROBE_TIMEOUT_MS }, function (res) {
+      let data = '';
+      res.on('data', function (c) { data += c; });
+      res.on('end', function () {
+        try {
+          const j = JSON.parse(data);
+          resolve(j && j.sidecar ? { port: port, agentId: j.agentId || null, version: j.version || '0.0.0', pid: j.pid || null } : null);
+        } catch (e) { resolve(null); }
+      });
+    });
+    req.on('error', function () { resolve(null); });
+    req.on('timeout', function () { req.destroy(); resolve(null); });
+  });
+}
+
+function versionKey(v) { return String(v || '0').split('.').map(function (n) { return parseInt(n, 10) || 0; }); }
+function newer(a, b) {
+  const ka = versionKey(a), kb = versionKey(b);
+  for (let i = 0; i < Math.max(ka.length, kb.length); i++) {
+    const d = (ka[i] || 0) - (kb[i] || 0);
+    if (d) return d > 0;
+  }
+  return false;
+}
+
+/** Every live sidecar in the configured range, regardless of agent. */
+async function listSidecars(cfg) {
+  const ports = [];
+  for (let i = 0; i < cfg.range; i++) ports.push(cfg.port + i);
+  return (await Promise.all(ports.map(probe))).filter(Boolean);
+}
+
+/**
+ * The sidecar for this session, or null. Resolves to
+ * { sidecar: {port, agentId, version, pid} | null, config, all: [...] }.
+ */
+async function findSidecar(cwd) {
+  const cfg = resolveConfig(cwd);
+  const all = await listSidecars(cfg);
+  const mine = all.filter(function (s) { return s.agentId === cfg.agentId; });
+  mine.sort(function (a, b) { return newer(a.version, b.version) ? -1 : newer(b.version, a.version) ? 1 : a.port - b.port; });
+  return { sidecar: mine[0] || null, config: cfg, all: all };
+}
+
+/** Optional trace for troubleshooting: AWM_HOOK_DEBUG=1 appends to ~/.claude/hooks/awm-hooks.log. */
+function debugLog(hook, fields) {
+  if (!process.env.AWM_HOOK_DEBUG) return;
+  try {
+    const line = Object.assign({ ts: new Date().toISOString(), hook: hook }, fields);
+    fs.appendFileSync(path.join(os.homedir(), '.claude', 'hooks', 'awm-hooks.log'), JSON.stringify(line) + '\n');
+  } catch (e) { /* never matters */ }
+}
+
+module.exports = { resolveConfig, findSidecar, listSidecars, deriveAgentFromDir, debugLog, PROBE_TIMEOUT_MS };

package/plugin/hooks/awm-prime.cjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// awm-prime.cjs — installed by `awm setup` (hooks v0.14.6). UserPromptSubmit: prime the turn with relevant memories, or stay silent.
+// Re-running `awm setup` rewrites this file; put local changes elsewhere.
+// Fails open: on any problem it prints nothing and exits 0.
+
+// The PRIME phase of the AWM-native harness (docs/patterns/awm-native-harness.md).
+// Posts the prompt to POST /hooks/prime on this session's sidecar and injects the
+// returned text as additionalContext. The sidecar decides what to inject, formats
+// it, abstains when confidence is low and caps the token budget — see
+// src/hooks/prime.ts — so this file stays thin.
+//
+// Turn it off without uninstalling: create ~/.claude/hooks/awm-prime.disabled
+// (an empty file). Remove the file to turn it back on. `awm doctor` reports which.
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const http = require('http');
+
+let finder = null;
+try { finder = require('./awm-find-sidecar.cjs'); } catch (e) { process.exit(0); }
+
+// A slow AWM must never delay a prompt. Warm recall with rerank measures 1.4–1.8 s
+// on a 30k-memory store; 4 s leaves margin. Connection refused returns in ~100 ms.
+const TIMEOUT_MS = 4000;
+const MIN_PROMPT_LEN = 15;   // skip "yes" / "ok" / "go on" turns
+// Set-level confidence below which the sidecar injects nothing. 0.10 rather than
+// the 0.25 once documented as "balanced": measured 2026-09-11, 0.25 silenced
+// specific prompts with one clear winner (top score 0.26–0.38) while passing a
+// vague one at 0.92. The gate is on the shape of the score distribution, not on
+// relevance, so specific questions are exactly the ones a high threshold loses.
+const MIN_CONFIDENCE = 0.10;
+const DISABLE_FILE = path.join(os.homedir(), '.claude', 'hooks', 'awm-prime.disabled');
+
+let raw = '';
+process.stdin.on('data', function (d) { raw += d; });
+process.stdin.on('end', function () {
+  let payload = {};
+  try { payload = JSON.parse(raw || '{}'); } catch (e) { process.exit(0); }
+  main(payload).catch(function () { process.exit(0); });
+});
+process.stdin.on('error', function () { process.exit(0); });
+
+function extractPrompt(j) {
+  for (const key of ['prompt', 'message', 'user_prompt', 'text', 'input']) {
+    if (typeof j[key] === 'string' && j[key].trim()) return j[key];
+  }
+  return null;
+}
+
+async function main(payload) {
+  if (fs.existsSync(DISABLE_FILE)) process.exit(0);
+  const prompt = extractPrompt(payload);
+  if (!prompt || prompt.trim().length < MIN_PROMPT_LEN) process.exit(0);
+
+  const found = await finder.findSidecar(payload.cwd);
+  const sc = found.sidecar;
+  if (!sc) {
+    finder.debugLog('prime', { agent: found.config.agentId, sidecar: null, live: found.all.length });
+    process.exit(0);
+  }
+
+  const body = JSON.stringify({
+    hook_event_name: 'UserPromptSubmit',
+    session_id: payload.session_id,
+    cwd: payload.cwd,
+    prompt: prompt,
+    minConfidence: MIN_CONFIDENCE,
+  });
+  const req = http.request({
+    host: '127.0.0.1', port: sc.port, path: '/hooks/prime', method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+      'Authorization': 'Bearer ' + found.config.secret,
+    },
+    timeout: TIMEOUT_MS,
+  }, function (res) {
+    let data = '';
+    res.on('data', function (c) { data += c; });
+    res.on('end', function () {
+      let out = null;
+      try { out = JSON.parse(data); } catch (e) { out = null; }
+      const inject = out && typeof out.inject === 'string' ? out.inject : '';
+      finder.debugLog('prime', { agent: found.config.agentId, port: sc.port, status: res.statusCode, kept: out && out.kept, total: out && out.total, reason: out && out.reason });
+      if (res.statusCode === 200 && inject) {
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: inject },
+        }));
+      }
+      process.exit(0);
+    });
+  });
+  req.on('error', function () { process.exit(0); });
+  req.on('timeout', function () { req.destroy(); process.exit(0); });
+  req.end(body);
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,66 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"MEMORY: (1) Did you learn anything new? Call memory_write. (2) Are you about to work on a topic you might have prior knowledge about? Call memory_recall. (3) Switching tasks? Call memory_task_begin.\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/awm-checkpoint.cjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/awm-checkpoint.cjs\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/awm-prime.cjs\"",
+            "timeout": 6
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/awm-db-mutation-reminder.cjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}