agent-working-memory 0.10.0 → 0.12.0

package/src/core/whoami.ts

@@ -0,0 +1,92 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Instance identity (D3, 2026-07-30).
+ *
+ * Answers "which AWM am I talking to?" — the recurring confusion class where
+ * sessions mix up the hosted multi-agent connector with the local instance,
+ * or run blind to sibling agent spaces in the same store (an evaluation once
+ * analyzed this project without seeing the `personal` space that held its
+ * design decisions).
+ *
+ * Exposed as the `memory_whoami` MCP tool and the `GET /whoami` HTTP route.
+ * Read-only; additive module.
+ */
+
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VERSION } from '../version.js';
+import { getConfiguredBackend, getConfiguredPath } from '../storage/factory.js';
+
+export interface WhoamiInfo {
+  agentId: string;
+  workspace: string | null;
+  surface: 'mcp' | 'http';
+  mode: 'standalone' | 'hive';
+  backend: string;
+  storePath: string;
+  version: string;
+  codePath: string;
+  pid: number;
+  ports: { http: number | null; hookSidecar: number | null };
+  siblingAgents: string[];
+}
+
+/** Store subset whoami needs — every backend implements listAgentIds. */
+export interface WhoamiStore {
+  listAgentIds(): string[] | Promise<string[]>;
+}
+
+function packageRoot(): string {
+  // src/core/whoami.ts (dev) and dist/core/whoami.js (build) both sit two
+  // levels below the package root.
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(join(here, '..', '..'));
+}
+
+export async function buildWhoami(
+  store: WhoamiStore,
+  agentId: string,
+  surface: 'mcp' | 'http',
+): Promise<WhoamiInfo> {
+  const coordination = process.env.AWM_COORDINATION === 'true' || process.env.AWM_COORDINATION === '1';
+  let siblings: string[] = [];
+  try {
+    const all = await store.listAgentIds();
+    siblings = all.filter(a => a !== agentId).sort();
+  } catch { /* identity must never fail on a listing error */ }
+  const httpPort = Number(process.env.AWM_PORT ?? '');
+  const hookPort = Number(process.env.AWM_HOOK_PORT ?? '');
+  return {
+    agentId,
+    workspace: process.env.AWM_WORKSPACE ?? null,
+    surface,
+    mode: coordination ? 'hive' : 'standalone',
+    backend: getConfiguredBackend(),
+    storePath: getConfiguredPath(),
+    version: VERSION,
+    codePath: packageRoot(),
+    pid: process.pid,
+    ports: {
+      http: Number.isFinite(httpPort) && httpPort > 0 ? httpPort : null,
+      hookSidecar: Number.isFinite(hookPort) && hookPort > 0 ? hookPort : null,
+    },
+    siblingAgents: siblings,
+  };
+}
+
+/** Human-readable rendering for the MCP tool response. */
+export function formatWhoami(w: WhoamiInfo): string {
+  return [
+    `Agent: ${w.agentId}${w.workspace ? ` (workspace: ${w.workspace})` : ''}`,
+    `Mode: ${w.mode} · Surface: ${w.surface} · Version: ${w.version}`,
+    `Backend: ${w.backend}`,
+    `Store: ${w.storePath}`,
+    `Code: ${w.codePath} (pid ${w.pid})`,
+    `Ports: http=${w.ports.http ?? 'off'} hookSidecar=${w.ports.hookSidecar ?? 'off'}`,
+    w.siblingAgents.length
+      ? `Sibling agent spaces in this store: ${w.siblingAgents.join(', ')} — recall is scoped to '${w.agentId}'; other spaces need workspace recall, \`awm export --agent <id>\`, or a session configured for that agent.`
+      : 'Sibling agent spaces in this store: none',
+  ].join('\n');
+}

package/src/core/write-pipeline.ts

@@ -48,6 +48,8 @@ import {
 } from './salience.js';
 import { embed } from './embeddings.js';
 import { extractMetaTags } from './auto-tagger.js';
+import { extractEntitiesFromTags } from './entity-extract.js';
+import { reportWrite } from './write-telemetry.js';
 import { DEFAULT_AGENT_CONFIG } from '../types/agent.js';
 
 /** Confidence floor below which a matched engram is treated as "decaying out". */
@@ -98,6 +100,15 @@ export interface WriteInput {
    *  because it's deterministically retrieved; opt in if a caller wants
    *  cognitive recall over a structural engram. (0.8 Cluster A) */
   embed?: boolean;
+  /** Provenance (D5, log-only): 'user-stated' | 'tool-output' | 'inference' | 'recipe'. */
+  originClass?: string;
+  /** Provenance (D5): session/conversation id performing the write. */
+  writerSession?: string;
+  /** Provenance (D5): cognition-recipe id+version when originClass is 'recipe'. */
+  recipeId?: string;
+  /** Temporal validity (D8): ISO bounds on when the FACT holds. */
+  validFrom?: string;
+  validTo?: string;
 }
 
 export interface WriteResult {
@@ -163,7 +174,10 @@ export async function performWrite(
   // Profiling: AWM_PROFILE_WRITE=1 logs ms-per-phase to stderr (v0.8.2).
   // Off by default; zero cost when unset.
   const profile = process.env.AWM_PROFILE_WRITE === '1';
-  const startTotal = profile ? performance.now() : 0;
+  // Timings are collected unconditionally since D1 (2026-07-30): a handful of
+  // performance.now() calls are free, and the always-on slow-write telemetry
+  // (write-telemetry.ts) needs them to explain stalls in production.
+  const startTotal = performance.now();
   let tNovelty = 0, tCreate = 0, tEmbed = 0;
 
   // Pre-embed once (v0.8.5): the embedding is needed for cosine-based novelty
@@ -177,22 +191,22 @@ export async function performWrite(
   // hook below will retry).
   // Disable via AWM_NOVELTY_EMBED=0 to keep writes ultra-fast at the cost
   // of cross-backend novelty consistency.
-  const tStartEmbed = profile ? performance.now() : 0;
+  const tStartEmbed = performance.now();
   let prewriteEmbedding: number[] | null = null;
   if (process.env.AWM_NOVELTY_EMBED !== '0') {
     try {
       prewriteEmbedding = await embed(`${input.concept} ${input.content}`);
     } catch { /* fall through — async embed will retry later */ }
   }
-  if (profile) tEmbed = performance.now() - tStartEmbed;
+  tEmbed = performance.now() - tStartEmbed;
 
-  const tStartNovelty = profile ? performance.now() : 0;
+  const tStartNovelty = performance.now();
   const noveltyResult = await computeNoveltyWithMatch(
     store, input.agentId, input.concept, input.content,
     input.workspace ?? null,
     prewriteEmbedding,
   );
-  if (profile) tNovelty = performance.now() - tStartNovelty;
+  tNovelty = performance.now() - tStartNovelty;
 
   // Effective event type — auto-promote user-feedback content.
   const effectiveEventType: SalienceEventType =
@@ -216,8 +230,10 @@ export async function performWrite(
   });
 
   // -- Reinforce / Supersede branching --
-  const tStartCreate = profile ? performance.now() : 0;
+  const tStartCreate = performance.now();
+  let busyHit = false;
   let result: WriteResult | null = null;
+  try {
   if (enableReinforcement && noveltyResult.matchedEngramId) {
     const matched = await store.getEngram(noveltyResult.matchedEngramId);
     // Agent-scope guard: NEVER reinforce/supersede an engram that belongs to a DIFFERENT agent. A
@@ -285,10 +301,34 @@ export async function performWrite(
       supersedesId: input.supersedes,
     }, prewriteEmbedding);
   }
-  if (profile) tCreate = performance.now() - tStartCreate;
+  } catch (e) {
+    const es = `${(e as { code?: unknown })?.code ?? ''} ${(e as Error)?.message ?? ''}`;
+    busyHit = /busy/i.test(es);
+    reportWrite({
+      totalMs: performance.now() - startTotal,
+      embedMs: tEmbed,
+      noveltyMs: tNovelty,
+      persistMs: performance.now() - tStartCreate,
+      action: 'error',
+      agentId: input.agentId,
+      busyHit,
+    });
+    throw e;
+  }
+  tCreate = performance.now() - tStartCreate;
+
+  const total = performance.now() - startTotal;
+  reportWrite({
+    totalMs: total,
+    embedMs: tEmbed,
+    noveltyMs: tNovelty,
+    persistMs: tCreate,
+    action: result.action,
+    agentId: input.agentId,
+    busyHit,
+  });
 
   if (profile) {
-    const total = performance.now() - startTotal;
     // Single-line stderr log; cheap to grep, easy to disable.
     // Format: [write] action=create novelty=42.1ms create=18.3ms total=60.4ms agent=x id=y
     // eslint-disable-next-line no-console
@@ -478,6 +518,11 @@ async function createNewEngram(
     supersedes: meta.supersedesId,
     sequence: input.sequence,
     references: input.references,
+    originClass: input.originClass,
+    writerSession: input.writerSession,
+    recipeId: input.recipeId,
+    validFrom: input.validFrom,
+    validTo: input.validTo,
     embedding: prewriteEmbedding && prewriteEmbedding.length > 0
       ? prewriteEmbedding
       : undefined,
@@ -487,6 +532,13 @@ async function createNewEngram(
     await store.updateStage(engram.id, 'staging');
   }
 
+  // Entity inverted index (D9): index structured entities from tags at write
+  // time. Best-effort — retrieval does not depend on it yet (D11).
+  try {
+    const entities = extractEntitiesFromTags(tags);
+    if (entities.length > 0) await store.recordEntityMentions(engram.id, input.agentId, entities);
+  } catch { /* non-fatal */ }
+
   // Supersession side-effects: mark the old engram, add causal edge.
   if (meta.supersedesId) {
     try {

package/src/core/write-telemetry.ts

@@ -0,0 +1,131 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Write-path telemetry (D1, 2026-07-30).
+ *
+ * Purpose: prove the mechanism behind slow writes before building the
+ * serialized write service. Captures, per write:
+ *   - phase wall times (embed / novelty / persist)
+ *   - event-loop lag at write completion (was this process's loop blocked?)
+ *   - whether a consolidation cycle was running IN THIS PROCESS
+ *   - whether SQLITE_BUSY was hit
+ *   - embed-model cold-load duration (first inference)
+ *
+ * Always-on slow-write warning: any write slower than AWM_SLOW_WRITE_MS
+ * (default 250ms; set 0 to disable) emits ONE structured stderr line.
+ * AWM_PROFILE_WRITE=1 continues to log every write as before.
+ *
+ * Design notes: additive module — no existing export changes (MWA vendors
+ * dist internals; nothing here alters existing paths). All timers are
+ * unref'd so they never hold the process open.
+ */
+
+const SLOW_WRITE_MS = (() => {
+  const v = Number(process.env.AWM_SLOW_WRITE_MS ?? '250');
+  return Number.isFinite(v) ? v : 250;
+})();
+
+// ---------- Event-loop lag monitor ----------
+
+const TICK_MS = 500;
+let lastTick = 0;
+let maxLagSinceRead = 0;
+let monitorStarted = false;
+
+/** Start the loop-lag heartbeat. Idempotent; call once at process boot. */
+export function startLoopLagMonitor(): void {
+  if (monitorStarted) return;
+  monitorStarted = true;
+  lastTick = performance.now();
+  const t = setInterval(() => {
+    const now = performance.now();
+    const lag = now - lastTick - TICK_MS;
+    if (lag > maxLagSinceRead) maxLagSinceRead = lag;
+    lastTick = now;
+  }, TICK_MS);
+  if (typeof t.unref === 'function') t.unref();
+}
+
+/**
+ * Max observed loop lag (ms beyond the expected tick) since the last read.
+ * Reading resets the max. A large value means this process's event loop was
+ * blocked (in-process ML, consolidation, sync SQL) during the window.
+ */
+export function readMaxLoopLag(): number {
+  const v = maxLagSinceRead;
+  maxLagSinceRead = 0;
+  return Math.max(0, Math.round(v));
+}
+
+// ---------- In-process consolidation state ----------
+
+let consolidationActive = false;
+let consolidationAgent: string | null = null;
+let consolidationStartedAt = 0;
+
+export function setConsolidationActive(active: boolean, agentId?: string): void {
+  consolidationActive = active;
+  consolidationAgent = active ? (agentId ?? null) : null;
+  consolidationStartedAt = active ? performance.now() : 0;
+}
+
+export function getConsolidationState(): { active: boolean; agentId: string | null; runningMs: number } {
+  return {
+    active: consolidationActive,
+    agentId: consolidationAgent,
+    runningMs: consolidationActive ? Math.round(performance.now() - consolidationStartedAt) : 0,
+  };
+}
+
+// ---------- Model cold-load record ----------
+
+let modelColdLoadMs: number | null = null;
+
+export function noteModelLoad(ms: number): void {
+  if (modelColdLoadMs === null) {
+    modelColdLoadMs = Math.round(ms);
+    process.stderr.write(`[awm] embed model cold load: ${modelColdLoadMs}ms\n`);
+  }
+}
+
+export function getModelColdLoadMs(): number | null {
+  return modelColdLoadMs;
+}
+
+// ---------- Slow-write reporter ----------
+
+export interface WriteTimings {
+  totalMs: number;
+  embedMs: number;
+  noveltyMs: number;
+  persistMs: number;
+  action: string;        // created | reinforced | superseded | discarded | ...
+  agentId: string;
+  busyHit: boolean;      // a SQLITE_BUSY was caught (and rethrown) during persist
+}
+
+/**
+ * Report a completed write. Emits one structured stderr line when the write
+ * exceeded the slow threshold (always-on) — including loop lag and in-process
+ * consolidation state, the two signals that distinguish "DB lock wait" from
+ * "my own event loop was blocked".
+ */
+export function reportWrite(t: WriteTimings): void {
+  if (SLOW_WRITE_MS <= 0) return;
+  if (t.totalMs < SLOW_WRITE_MS) return;
+  const consol = getConsolidationState();
+  const parts = [
+    `[awm] SLOW WRITE ${Math.round(t.totalMs)}ms`,
+    `agent=${t.agentId}`,
+    `action=${t.action}`,
+    `embed=${Math.round(t.embedMs)}ms`,
+    `novelty=${Math.round(t.noveltyMs)}ms`,
+    `persist=${Math.round(t.persistMs)}ms`,
+    `loopLagMax=${readMaxLoopLag()}ms`,
+    `consolidating=${consol.active ? `yes(${consol.agentId ?? '?'},${consol.runningMs}ms)` : 'no'}`,
+    `busy=${t.busyHit ? 'yes' : 'no'}`,
+    modelColdLoadMs !== null ? `modelColdLoad=${modelColdLoadMs}ms` : 'modelColdLoad=none',
+  ];
+  process.stderr.write(parts.join(' ') + '\n');
+}