agent-working-memory 0.12.0 → 0.12.3

package/src/adapters/common.ts

@@ -300,6 +300,29 @@ and entity-bridge boosts at recall time.
 - \`person=<Name>\` for stakeholder quotes / decisions
 - \`version=<X.Y.Z>\` for release-specific findings
 
+### Entity index — exact-match recall for named things (default off)
+Structured identifier tags (\`ticket=\`, \`person=\`, \`horse=\`, \`member=\`, bare 4+ digit
+ids, etc.) feed a dedicated entity inverted index, separate from BM25/embedding scoring.
+A query naming an entity ("ticket 19252", "Kaleigh Collett") can reach the memory through
+this index even when the wording doesn't lexically match — it's a deterministic exact
+lookup, immune to vocabulary mismatch. Keep identifier tags exact and consistent for
+this reason, not just for the BM25 boost described above.
+
+Off by default; opt in with \`AWM_ENTITY_INDEX_FETCH=1\` (bounded by
+\`AWM_ENTITY_INDEX_CAP\`, default 12). Matched entities get no score boost — they're
+guaranteed a reranker audition instead, so the cross-encoder alone decides whether they
+surface. Worth trialing on identifier-heavy workloads (ticket/event numbers, named
+people/things you refer to by name often); not yet the default pending evaluation.
+
+### Temporal validity — memories that expire or start in the future
+\`memory_write\` accepts \`valid_from\` / \`valid_to\` (ISO dates). Use \`valid_to\` on
+**operational** facts with a real shelf life — a deploy state, "waiting on X's reply",
+a ticket status — so the memory expires instead of relying on you to remember it's
+stale. Recall renders \`[valid until …]\` on results carrying this field. Use
+\`valid_from\` for a fact that becomes true on a known future date (a policy change, a
+season that hasn't started yet). Don't set either for durable facts — most memories
+don't need them.
+
 ### Memory classes (controls how strictly the salience filter gates the write)
 - \`memory_class: canonical\` — source-of-truth memories. Floor 0.7 salience, never staged.
   Use for: user-stated decisions, project requirements, verified architectural facts,
@@ -456,8 +479,14 @@ memory_write(
 
 ### Also:
 - To track work items: memory_task_add, memory_task_update, memory_task_list, memory_task_next
+- \`memory_whoami\` (MCP tool) / \`GET /whoami\` — identify the instance you're actually
+  talking to: agent id, workspace, mode, backend, store path, code provenance, sibling
+  agent spaces sharing the store. Call this FIRST whenever you're unsure which store,
+  which agent identity, or which running code you're dealing with — before reasoning
+  about AWM's own state from a stale memory or an assumed port number.
 - AWM is shared across all agents in real time. When any agent writes or supersedes a
-  memory, every other agent can recall it immediately.
+  memory, every other agent can recall it immediately — but only within the same
+  workspace and agent scope.
 
 ### Output compression (token efficiency, output-only)
 When a tool returns a LARGE STRUCTURED result you need to keep in context — a JSON
@@ -500,11 +529,7 @@ for A/B testing if a regression appears in your workload:
 Recall pipeline (0.7.x):
 - \`AWM_DISABLE_POOL_FILTER=1\` — disables the candidate pool reduction
   pre-filter in recall. Reverts to scoring all active candidates.
-- \`AWM_SLOW_WRITE_MS\` — slow-write telemetry threshold in ms (default 250;
-  0 disables the always-on slow-write stderr line).
-- \`memory_whoami\` (MCP) / \`GET /whoami\` — identify the instance (agent, mode,
-  backend, store path, code provenance, sibling agent spaces) when unsure
-  which AWM you are talking to.
+- \`AWM_ENTITY_INDEX_FETCH=1\` — see "Entity index" above (0.12.x, default off).
 - \`AWM_DISABLE_SLIM_CACHE=1\` — disables the in-memory slim cache.
   Reverts to per-recall SQL fetch + Buffer→Float32Array conversion.
 - \`AWM_DISABLE_RERANK_SKIP=1\` — disables the cross-encoder skip on
@@ -512,7 +537,11 @@ Recall pipeline (0.7.x):
 - \`AWM_DISABLE_EXPANSION_CACHE=1\` — disables the query expansion skip
   heuristic + LRU cache. Forces every recall through flan-t5-small.
 
-Write pipeline + lifecycle (0.8.x):
+Write pipeline + lifecycle (0.8.x, plus 0.12.x telemetry):
+- \`AWM_SLOW_WRITE_MS=250\` (0.12.x) — any write slower than this logs one stderr
+  line with a phase-time breakdown (embed/novelty/persist, event-loop lag,
+  embed-model cold-load ms). \`0\` disables. Useful for diagnosing why a session's
+  first write/recall feels slow.
 - \`AWM_REINFORCE_MAX_CONTENT_LEN=1500\` — max chars an engram's content
   can grow to via merge-on-reinforce (drop-oldest on overflow). Higher =
   preserves more reinforced detail; lower = leaner recall output.

package/src/core/embeddings.ts

@@ -37,7 +37,7 @@ async function loadInProcess(): Promise<FeatureExtractionPipeline> {
   inProcessInitPromise = pipeline('feature-extraction', MODEL_ID, { dtype: 'fp32' }).then(pipe => {
     inProcessInstance = pipe;
     noteModelLoad(performance.now() - tLoadStart);
-    console.log(`Embedding model loaded in-process: ${MODEL_ID} (${DIMENSIONS}d)`);
+    console.error(`Embedding model loaded in-process: ${MODEL_ID} (${DIMENSIONS}d)`);
     return pipe;
   });
   return inProcessInitPromise;

package/src/core/format-recall.ts

@@ -0,0 +1,25 @@
+import type { ActivationResult } from '../types/engram.js';
+
+/**
+ * Formats one memory_recall result line for the MCP text response.
+ *
+ * Extracted out of the inline closure in mcp.ts (0.12.1) so the format itself
+ * — specifically, that every result carries its engram id — can be unit
+ * tested without booting the MCP server (mcp.ts has a top-level `await` and
+ * opens the store as a side effect of import, so it cannot be imported by a
+ * test directly).
+ *
+ * The id is placed right after the score, not at the end of the line: result
+ * bodies can be long, and a consumer scanning for `[id: ...]` shouldn't have
+ * to read past a paragraph of content to find it.
+ */
+export function formatRecallResultLine(r: ActivationResult, index: number): string {
+  const body = r.summary ?? r.engram.content;
+  const chain = r.engram.supersededBy
+    ? ` ⚠ SUPERSEDED by ${r.engram.supersededBy} — treat as historical; recall/fetch the successor before relying on this.`
+    : '';
+  const validity = r.engram.validTo
+    ? ` [valid until ${r.engram.validTo}]`
+    : '';
+  return `${index + 1}. **${r.engram.concept}** (${r.score.toFixed(3)}) [id: ${r.engram.id}]${validity}: ${body}${chain}`;
+}

package/src/core/query-expander.ts

@@ -30,7 +30,7 @@ async function loadInProcess(): Promise<Text2TextGenerationPipeline> {
   if (inProcessInitPromise) return inProcessInitPromise;
   inProcessInitPromise = pipeline('text2text-generation', MODEL_ID, { dtype: 'fp32' }).then(pipe => {
     inProcessInstance = pipe as Text2TextGenerationPipeline;
-    console.log(`Query expander loaded in-process: ${MODEL_ID}`);
+    console.error(`Query expander loaded in-process: ${MODEL_ID}`);
     return inProcessInstance;
   });
   return inProcessInitPromise;

package/src/core/reranker.ts

@@ -35,7 +35,7 @@ async function ensureLoaded(): Promise<void> {
   initPromise = (async () => {
     tokenizer = await AutoTokenizer.from_pretrained(MODEL_ID);
     model = await AutoModelForSequenceClassification.from_pretrained(MODEL_ID, { dtype: 'fp32' });
-    console.log(`Re-ranker model loaded in-process: ${MODEL_ID}`);
+    console.error(`Re-ranker model loaded in-process: ${MODEL_ID}`);
   })();
   return initPromise;
 }

package/src/hooks/sidecar.ts

@@ -28,6 +28,28 @@ export interface SidecarDeps {
   secret: string | null;
   port: number;
   onConsolidate?: (agentId: string, reason: string) => void;
+  /**
+   * 0.12.2: warm recall for hooks. The sidecar runs in the same process as
+   * the MCP server's activation engine and its loaded ML models, so exposing
+   * recall here gives Claude Code hooks (e.g. a UserPromptSubmit PRIME hook)
+   * warm-latency recall with no standing server — the process lifecycle is
+   * owned by the session that spawned it. Optional so older callers and
+   * tests keep working unchanged.
+   */
+  activate?: (q: {
+    context: string;
+    limit?: number;
+    requireConfidence?: number;
+    granularity?: 'full' | 'compact' | 'auto';
+  }) => Promise<Array<{
+    engram: {
+      id: string; concept: string; content: string;
+      createdAt?: string; memoryClass?: string; validTo?: string | null;
+    };
+    score: number;
+    summary?: string;
+    confidence?: number;
+  }>>;
 }
 
 interface HookInput {
@@ -187,6 +209,39 @@ export function startSidecar(deps: SidecarDeps): { close: () => void } {
       return;
     }
 
+    // POST /memory/activate — warm recall for hooks (0.12.2). Behind the auth
+    // gate above. Returns a trimmed subset of the HTTP API's response shape
+    // ({results: [{engram, score, summary, confidence}]}) so a hook written
+    // against either endpoint needs no branching.
+    if (req.url === '/memory/activate' && req.method === 'POST') {
+      if (!deps.activate) {
+        json(res, 501, { error: 'activate not wired on this sidecar' });
+        return;
+      }
+      try {
+        const body = JSON.parse((await readBody(req)) || '{}') as {
+          context?: string; query?: string; limit?: number;
+          requireConfidence?: number; granularity?: 'full' | 'compact' | 'auto';
+        };
+        const context = body.context ?? body.query;
+        if (!context) {
+          json(res, 400, { error: 'context (or query) is required' });
+          return;
+        }
+        const results = await deps.activate({
+          context,
+          limit: body.limit,
+          requireConfidence: body.requireConfidence,
+          granularity: body.granularity,
+        });
+        log(agentId, 'hook:recall', `"${context.slice(0, 80)}" → ${results.length} results (sidecar)`);
+        json(res, 200, { results });
+      } catch (err) {
+        json(res, 500, { error: (err as Error).message });
+      }
+      return;
+    }
+
     // POST /hooks/checkpoint — auto-checkpoint from hook events
     if (req.url === '/hooks/checkpoint' && req.method === 'POST') {
       try {

package/src/mcp.ts

@@ -73,7 +73,9 @@ import type { ConsciousState } from './types/checkpoint.js';
 import type { SalienceEventType } from './core/salience.js';
 import type { TaskStatus, TaskPriority } from './types/engram.js';
 import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
-import { embed } from './core/embeddings.js';
+import { embed, getEmbedder } from './core/embeddings.js';
+import { getReranker } from './core/reranker.js';
+import { getExpander } from './core/query-expander.js';
 import { startSidecar } from './hooks/sidecar.js';
 import { initLogger, log, getLogPath } from './core/logger.js';
 import { VERSION } from './version.js';
@@ -83,6 +85,7 @@ import { queryPeerDecisions, formatPeerDecisions } from './coordination/peer-dec
 import { startLoopLagMonitor } from './core/write-telemetry.js';
 import { buildWhoami, formatWhoami } from './core/whoami.js';
 import { renderTaskEndInvitation, validateRecipeWrite, recipeSlug, getRecipe } from './recipes/index.js';
+import { formatRecallResultLine } from './core/format-recall.js';
 
 // --- Incognito Mode ---
 // When AWM_INCOGNITO=1, register zero tools. Claude won't see memory tools at all.
@@ -461,22 +464,11 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
       };
     }
 
-    const lines = results.map((r, i) => {
-      // Confidence-adaptive output (Paper 3: cognitive teaming). When the caller
-      // requested 'compact' or 'auto' granularity, surface the engine-computed
-      // summary instead of the full content — same engram, less to read.
-      const body = r.summary ?? r.engram.content;
-      // D8 (2026-07-30): conflict surfacing — a superseded memory that still
-      // ranks is shown WITH its replacement pointer instead of silently
-      // down-ranked. The model should trust the successor.
-      const chain = r.engram.supersededBy
-        ? ` ⚠ SUPERSEDED by ${r.engram.supersededBy} — treat as historical; recall/fetch the successor before relying on this.`
-        : '';
-      const validity = r.engram.validTo
-        ? ` [valid until ${r.engram.validTo}]`
-        : '';
-      return `${i + 1}. **${r.engram.concept}** (${r.score.toFixed(3)})${validity}: ${body}${chain}`;
-    });
+    // Confidence-adaptive output (Paper 3: cognitive teaming) and D8
+    // (2026-07-30) conflict surfacing both live in the shared formatter now —
+    // see core/format-recall.ts for why it's extracted (0.12.1: unit-testable
+    // without booting the server) and why the id sits after the score.
+    const lines = results.map(formatRecallResultLine);
 
     return {
       content: [{
@@ -564,7 +556,7 @@ Use this when:
 
 The old memory stays in the database (searchable for history) but is heavily down-ranked in recall so the current version dominates.`,
   {
-    old_engram_id: z.string().describe('ID of the outdated memory'),
+    old_engram_id: z.string().describe('ID of the outdated memory (from memory_recall results, or memory_write\'s own response if you just wrote it)'),
     new_engram_id: z.string().describe('ID of the replacement memory'),
     reason: z.string().optional().describe('Why the old memory is outdated'),
   },
@@ -1288,6 +1280,35 @@ async function main() {
     agentId: AGENT_ID,
     secret: HOOK_SECRET,
     port: HOOK_PORT,
+    // 0.12.2: warm recall for hooks — the sidecar shares this process's
+    // activation engine and loaded models, so a UserPromptSubmit hook can get
+    // warm-latency recall without any standing server. Trimmed result shape
+    // (no embeddings/phase scores — hooks don't need them and the vectors
+    // alone would 10x the payload).
+    activate: async (q) => {
+      const results = await activationEngine.activate({
+        agentId: AGENT_ID,
+        context: q.context,
+        limit: q.limit,
+        requireConfidence: q.requireConfidence,
+        granularity: q.granularity,
+      });
+      return results.map(r => ({
+        engram: {
+          id: r.engram.id,
+          concept: r.engram.concept,
+          content: r.engram.content,
+          createdAt: r.engram.createdAt instanceof Date
+            ? r.engram.createdAt.toISOString()
+            : (r.engram.createdAt as unknown as string | undefined),
+          memoryClass: r.engram.memoryClass,
+          validTo: r.engram.validTo,
+        },
+        score: r.score,
+        summary: r.summary,
+        confidence: r.confidence,
+      }));
+    },
     onConsolidate: async (agentId, reason) => {
       console.error(`[mcp] consolidation triggered: ${reason}`);
       const result = await consolidationEngine.consolidate(agentId);
@@ -1296,6 +1317,31 @@ async function main() {
     },
   });
 
+  // 0.12.2: eager warm — fire-and-forget, mirrors index.ts:208-218. Without
+  // this, every Claude Code session paid the full cold cost (~3s measured on
+  // a 29.7k-engram store: slim cache ~0.9s + three model loads ~1.8s) on its
+  // FIRST recall, which is exactly the "first recall is slow → recall gets
+  // avoided" failure mode. Warming here overlaps session startup instead.
+  // All output is stderr-safe (stdout carries JSON-RPC frames).
+  // Escape hatch: AWM_NO_EAGER_WARM=1 restores lazy loading.
+  if (process.env.AWM_NO_EAGER_WARM !== '1') {
+    getEmbedder().catch(err => console.error('Embedding model unavailable:', err.message));
+    getReranker().catch(err => console.error('Reranker model unavailable:', err.message));
+    getExpander().catch(err => console.error('Query expander model unavailable:', err.message));
+    if (BACKEND === 'sqlite') {
+      setImmediate(() => {
+        try {
+          const t0 = Date.now();
+          (store as unknown as EngramStore).warmSlimCache();
+          const stats = (store as unknown as EngramStore).getSlimCacheStats();
+          console.error(`Slim cache warmed: ${stats.size} entries in ${Date.now() - t0}ms`);
+        } catch (err) {
+          console.error(`Slim cache warm failed: ${(err as Error).message}`);
+        }
+      });
+    }
+  }
+
   // Coordination MCP tools (opt-in via AWM_COORDINATION=true)
   // AWM 0.8.x: coordination requires SQLite (uses store.getDb()). On PGlite,
   // coordination is auto-disabled with a warning; re-enable when coordination