agent-working-memory 0.14.5 → 0.15.4

package/src/adapters/types.ts

@@ -28,8 +28,12 @@ export interface SetupContext {
   hasDist: boolean;
   /** Hook sidecar secret token */
   hookSecret: string;
-  /** Hook sidecar port */
+  /** Hook sidecar port (preferred; the sidecar walks upward from here when busy) */
   hookPort: string;
+  /** How many ports upward from hookPort the sidecar may try (0.14.2) */
+  hookPortRange: string;
+  /** Install the UserPromptSubmit prime hook (0.14.6; `--no-prime` turns it off) */
+  installPrime: boolean;
   /** Whether to use global scope */
   isGlobal: boolean;
   /** Windows platform */
@@ -70,6 +74,13 @@ export interface CLIAdapter {
   /** Configure hooks (if supported). Returns action summary. */
   writeHooks(ctx: SetupContext, skip: boolean): string;
 
-  /** Validate that the setup is healthy. */
-  diagnose(ctx: SetupContext): DiagnosticResult[];
+  /** Validate that the setup is healthy. May probe the network, hence possibly async. */
+  diagnose(ctx: SetupContext): DiagnosticResult[] | Promise<DiagnosticResult[]>;
+
+  /**
+   * The env block of an AWM server entry this adapter previously wrote, if any.
+   * `awm setup` re-runs preserve these values unless a flag overrides them, so an
+   * upgrade never repoints the database or renames the agent (0.14.6).
+   */
+  readExistingEnv?(isGlobal: boolean, cwd: string): Record<string, string> | null;
 }

package/src/cli.ts

@@ -47,6 +47,7 @@ AgentWorkingMemory — Cognitive memory for AI agents
 
 Usage:
   awm setup [target] [options]                      Configure AWM for an AI CLI
+  awm plugin                                        Install as a Claude Code plugin (local, no GitHub)
   awm doctor [target|--all]                         Validate AWM integrations
   awm mcp                                           Start MCP server (stdio)
   awm serve [--port <port>]                         Start HTTP API server
@@ -74,7 +75,10 @@ Setup options:
   --no-instructions   Skip instruction file (CLAUDE.md, AGENTS.md, etc.)
   --no-claude-md      Alias for --no-instructions
   --no-hooks          Skip hook installation
-  --hook-port PORT    Sidecar port for hooks (default: 8401)
+  --no-prime          Skip the UserPromptSubmit prime hook (auto-inject memories per prompt)
+  --hook-port PORT    Preferred sidecar port (default: 8401; each session walks upward when busy)
+  --hook-port-range N Ports to try upward from --hook-port (default: 10)
+  Re-running setup keeps your existing agent id, db path, port and any env you added.
 
 Examples:
   awm setup --global              Claude Code, global (recommended)
@@ -95,7 +99,9 @@ async function setup() {
   let skipInstructions = false;
   let isGlobal = false;
   let skipHooks = false;
-  let hookPort = '8401';
+  let installPrime = true;
+  let hookPort: string | undefined;
+  let hookPortRange: string | undefined;
 
   for (let i = 1; i < args.length; i++) {
     if (args[i] === '--agent-id' && args[i + 1]) {
@@ -106,8 +112,12 @@ async function setup() {
       skipInstructions = true;
     } else if (args[i] === '--no-hooks') {
       skipHooks = true;
+    } else if (args[i] === '--no-prime') {
+      installPrime = false;
     } else if (args[i] === '--hook-port' && args[i + 1]) {
       hookPort = args[++i];
+    } else if (args[i] === '--hook-port-range' && args[i + 1]) {
+      hookPortRange = args[++i];
     } else if (args[i] === '--global') {
       isGlobal = true;
     } else if (!args[i].startsWith('--')) {
@@ -133,8 +143,11 @@ async function setup() {
     isGlobal = true;
   }
 
-  // Build context
-  const ctx = buildSetupContext({ agentId, dbPath, isGlobal, hookPort });
+  // Build context. A previous install's values survive unless a flag overrides them
+  // (0.14.6) — an upgrade must never repoint the database or rename the agent.
+  const existingEnv = adapter.readExistingEnv?.(isGlobal, process.cwd()) ?? null;
+  // `awm setup claude-code` -> client=claude-code, cursor -> client=cursor, and so on.
+  const ctx = buildSetupContext({ agentId, dbPath, isGlobal, hookPort, hookPortRange, installPrime, existingEnv, client: target });
 
   // Run adapter
   const configAction = adapter.writeMcpConfig(ctx);
@@ -157,9 +170,62 @@ AWM configured for ${adapter.name}${isGlobal ? ' (global)' : ''}
 Next steps:
   1. Restart ${adapter.name} to pick up the MCP server
   2. Memory tools will appear automatically${adapter.id === 'codex' ? ' (verify with /mcp)' : ''}
+  3. \`awm doctor\` checks the install and lists the live sidecars
 `.trim());
 }
 
+// ─── PLUGIN ──────────────────────────────────────
+
+/**
+ * Print the two lines that install AWM as a Claude Code plugin FROM THIS INSTALL.
+ *
+ * Most users are on Windows and will never clone the repository, so
+ * `/plugin marketplace add CompleteIdeas/agent-working-memory` — which needs GitHub — is the
+ * wrong default for them. npm has already put a complete marketplace on their disk; they
+ * just have no way to know where it is. This tells them, with the real resolved path.
+ */
+function pluginInfo(): void {
+  // dist/cli.js -> package root
+  const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const marketplace = join(pkgRoot, '.claude-plugin', 'marketplace.json');
+
+  if (!existsSync(marketplace)) {
+    console.log(`
+AWM ${VERSION} — plugin not found in this install
+
+  Looked for: ${marketplace}
+
+  This happens when AWM is running from a source checkout that has not been built,
+  or from a package published before the plugin was bundled (< 0.15.3).
+
+  From a checkout:  npm run build && npm run build:plugin
+  Otherwise:        npm install -g agent-working-memory@latest
+`.trimStart());
+    return;
+  }
+
+  console.log(`
+AWM ${VERSION} — install as a Claude Code plugin
+
+  Paste these two lines into Claude Code:
+
+    /plugin marketplace add ${pkgRoot}
+    /plugin install awm@agent-working-memory
+
+  Then restart Claude Code. You get 19 memory tools, the session hooks, and the
+  usage guidance as a skill.
+
+  No GitHub access needed — the marketplace is this npm install, already on disk.
+
+  The store defaults to the same file \`awm setup --global\` uses, so a plugin
+  install and a CLI install share one memory rather than quietly keeping two.
+
+  Check it worked:  awm doctor claude-code
+  More:             https://github.com/CompleteIdeas/agent-working-memory/blob/master/docs/plugin.md
+`.trimStart());
+}
+
+
 // ─── DOCTOR ──────────────────────────────────────
 
 async function doctor() {
@@ -197,7 +263,9 @@ async function doctor() {
     }
 
     console.log(`  ${adapter.name}:`);
-    const results = adapter.diagnose(ctx);
+    const existingEnv = adapter.readExistingEnv?.(true, process.cwd()) ?? null;
+    const ctx = buildSetupContext({ isGlobal: true, existingEnv });
+    const results = await adapter.diagnose(ctx);
     for (const r of results) {
       const icon = r.status === 'ok' ? '+' : r.status === 'warn' ? '~' : 'x';
       console.log(`    [${icon}] ${r.check}: ${r.message}`);
@@ -789,6 +857,9 @@ switch (command) {
   case 'setup':
     await setup();
     break;
+    case 'plugin':
+      pluginInfo();
+      break;
   case 'doctor':
     await doctor();
     break;

package/src/core/agent-id.ts

@@ -0,0 +1,28 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Fallback agent identity when AWM_AGENT_ID / WORKER_NAME are unset.
+ *
+ * Derived from the project directory so a plain `claude` launch still binds to
+ * the right store: `Personal-Projects` → 'personal'; everything else → 'work'.
+ * The AWM package itself lives under Personal-Projects, so an AgentSynapse
+ * checkout is guarded first — a stray server cwd must not mis-bind.
+ *
+ * ONE definition, three consumers that must agree:
+ *   - src/mcp.ts — what the server actually binds to
+ *   - src/adapters/common.ts — what `awm setup` reports and seeds
+ *   - the shipped hook scripts (src/adapters/hook-scripts.ts) carry a
+ *     line-for-line JavaScript mirror, because a hook cannot import from dist.
+ *     tests/adapters/hook-scripts.test.ts asserts the mirror agrees with this.
+ */
+export function deriveAgentFromDir(dir: string): string {
+  const d = String(dir ?? '').replace(/\\/g, '/');
+  if (/\/AgentSynapse\//i.test(d)) return 'work';
+  return /\/Personal-Projects(\/|$)/i.test(d) ? 'personal' : 'work';
+}
+
+/** The agent id a server process would resolve to for `dir`, honouring the env first. */
+export function resolveAgentId(dir: string, env: NodeJS.ProcessEnv = process.env): string {
+  return env.AWM_AGENT_ID ?? env.WORKER_NAME ?? deriveAgentFromDir(dir);
+}

package/src/core/write-pipeline.ts

@@ -491,6 +491,24 @@ async function createNewEngram(
 
   const tags = [...(input.tags ?? [])];
   if (isLowSalience && !tags.includes('low-salience')) tags.push('low-salience');
+
+  // Which CLIENT wrote this: `client=claude-code`, `client=claude-desktop`, `client=cursor`.
+  //
+  // Deliberately not called `surface`: memory_whoami already reports a `surface` field
+  // meaning the TRANSPORT (mcp | http), and one word for two concepts is how you lose an
+  // hour six months from now. Transport is how the request arrived; client is which
+  // application it arrived from.
+  // AWM_CLIENT is set by the thing that launches the server (the Claude Code plugin, the
+  // Desktop extension, `awm setup`), never by the caller, so it records where a memory came
+  // from rather than what the writer claims.
+  //
+  // Captured by default rather than behind a flag, because provenance is one-way: a tag can
+  // be ignored or stripped later, but the origin of a memory written without one is gone for
+  // good. An explicit `client=` in the caller's tags always wins.
+  const client = (process.env.AWM_CLIENT ?? '').trim();
+  if (client && !tags.some(t => t.toLowerCase().startsWith('client='))) {
+    tags.push(`client=${client}`);
+  }
 
   // Auto-tag meta-tags (default-OFF, AWM_AUTOTAG=1). extractMetaTags emits
   // `entity:<ProperNoun>` and `cat:<category>` tags from concept+content. These

package/src/hooks/prime.ts

@@ -36,7 +36,12 @@ import { packRecallByBudget, estimateTokens, type PackedRecall } from '../core/t
 
 /** Shape returned by the sidecar's `activate` dependency. */
 export interface PrimeCandidate {
-  engram: { id: string; concept: string; content: string; memoryClass?: string; validTo?: string | null };
+  engram: {
+    id: string; concept: string; content: string; memoryClass?: string;
+    validTo?: string | null;
+    /** Used for the age label; Date from the store, string over HTTP. */
+    createdAt?: Date | string | null;
+  };
   score: number;
   summary?: string;
   confidence?: number;
@@ -64,21 +69,31 @@ export interface PrimeResult {
 export const PRIME_DEFAULTS = {
   maxTokens: 600,
   /**
-   * 0.25 = the "balanced" threshold AWM's own recall docs recommend for
-   * acting on a memory. Priming is acting on it without being asked, so it
-   * should not be looser than the value the docs suggest for deliberate use.
+   * 0.10 (was 0.25 until 0.14.6). The confidence this gates on describes the
+   * SHAPE of the score distribution — how far the top results stand out from
+   * the rest — not relevance. Measured 2026-09-11 on a 30k-memory store: at
+   * 0.25 two specific prompts with one clear winner (top score 0.26 and 0.38)
+   * were silenced while a vague prompt passed at 0.92. Those specific prompts
+   * are exactly what priming exists for. 0.10 passed all three and still
+   * abstains on the garbage case (confidence ≈ 0.05).
    */
-  minConfidence: 0.25,
+  minConfidence: 0.10,
   minScore: 0.10,
 } as const;
 
 /** One injected line. Deliberately terser than the MCP recall format — this is
  *  context the agent didn't ask for, so it should read as a brief note, not a
  *  report. The id is retained so the agent can act on it (feedback, supersede). */
-function formatPrimeLine(c: PrimeCandidate): string {
+function formatPrimeLine(c: PrimeCandidate, now: number = Date.now()): string {
   const body = c.summary ?? c.engram.content;
   const validity = c.engram.validTo ? ` [valid until ${c.engram.validTo}]` : '';
-  return `- ${c.engram.concept}${validity} [${c.engram.id}]: ${body}`;
+  // Class + age make the volatility rubric mechanical: a 90-day-old working
+  // memory reads differently from a 2-day-old canonical one, and the agent
+  // should not have to look either up before deciding how much to trust it.
+  const cls = c.engram.memoryClass ?? 'working';
+  const created = c.engram.createdAt ? new Date(c.engram.createdAt as any).getTime() : NaN;
+  const age = Number.isFinite(created) ? ` · ${Math.max(0, Math.round((now - created) / 86_400_000))}d` : '';
+  return `- [${cls}${age}] ${c.engram.concept}${validity} [${c.engram.id}]: ${body}`;
 }
 
 /**

package/src/mcp.ts

@@ -30,6 +30,7 @@
  */
 
 import { readFileSync } from 'node:fs';
+import { deriveAgentFromDir as deriveAgentFromDirShared } from './core/agent-id.js';
 import { resolve, basename } from 'node:path';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 
@@ -111,17 +112,10 @@ const BACKEND: StoreBackend = getConfiguredBackend();
 const DB_PATH = process.env.AWM_DB_PATH ?? (BACKEND === 'pglite' ? 'memory-pglite' : 'memory.db');
 
 // Fallback agent selection when AWM_AGENT_ID/WORKER_NAME are unset: derive from
-// the project directory so plain `claude` launches still bind to the right
-// store. Personal-Projects -> 'personal'; everything else -> 'work' (the
-// primary store). MUST stay in sync with the SessionStart hook
-// (~/.claude/hooks/awm-session-start.ps1) so the hook's restore and the
-// server's reads/writes never diverge. Guard the AWM package's own path
-// (it lives under Personal-Projects) so a stray server cwd can't mis-bind.
-function deriveAgentFromDir(): string {
-  const dir = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replace(/\\/g, '/');
-  if (/\/AgentSynapse\//i.test(dir)) return 'work';
-  return /\/Personal-Projects(\/|$)/i.test(dir) ? 'personal' : 'work';
-}
+// the project directory (core/agent-id.ts — one definition shared with `awm setup`
+// and mirrored in the shipped hook scripts, so the server, the installer and the
+// hooks always name the same pool for a given directory).
+const deriveAgentFromDir = () => deriveAgentFromDirShared(process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
 const AGENT_ID = process.env.AWM_AGENT_ID ?? process.env.WORKER_NAME ?? deriveAgentFromDir();
 const HOOK_PORT = parseInt(process.env.AWM_HOOK_PORT ?? '8401', 10);
 // 0.14.2: ports to try upward from HOOK_PORT when it is busy (see sidecar.ts).

package/src/plugin/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 __AWM_VERSION__.
+//
+// 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@__AWM_VERSION__', '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/src/storage/factory.ts

@@ -49,13 +49,25 @@ export type StoreBackend = 'sqlite' | 'pglite' | 'postgres';
 function detectBackendFromDisk(): StoreBackend | null {
   // 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
-    } catch { /* fall through */ }
-  }
+  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 */ }
+    }
+    // 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