agent-working-memory 0.14.5 → 0.15.4

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
+          }
+        ]
+      }
+    ]
+  }
+}