agent-working-memory 0.14.5 → 0.14.6

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

@@ -74,7 +74,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 +98,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 +111,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 +142,10 @@ 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;
+  const ctx = buildSetupContext({ agentId, dbPath, isGlobal, hookPort, hookPortRange, installPrime, existingEnv });
 
   // Run adapter
   const configAction = adapter.writeMcpConfig(ctx);
@@ -157,6 +168,7 @@ 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());
 }
 
@@ -197,7 +209,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}`);

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/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).