agent-working-memory 0.14.1 → 0.14.5

package/src/mcp.ts

@@ -124,6 +124,15 @@ function deriveAgentFromDir(): string {
 }
 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).
+const HOOK_PORT_RANGE = Math.max(1, parseInt(process.env.AWM_HOOK_PORT_RANGE ?? '10', 10) || 10);
+// Set once the sidecar starts; whoami reads the bound port from it.
+let sidecarHandle: { boundPort: () => number | null } | null = null;
+function sidecarPortLabel(): string {
+  const p = sidecarHandle?.boundPort() ?? null;
+  if (p === null) return `not bound (preferred ${HOOK_PORT}; hooks disabled)`;
+  return p === HOOK_PORT ? `127.0.0.1:${p}` : `127.0.0.1:${p} (preferred ${HOOK_PORT} was busy)`;
+}
 const HOOK_SECRET = process.env.AWM_HOOK_SECRET ?? null;
 
 initLogger(DB_PATH);
@@ -521,10 +530,15 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
       };
     }
 
+    // 0.14.3: surface the activation event id once, so memory_feedback can join
+    // to this recall. Rendered after the token footer; cheap (one short line).
+    const evId = results[0]?.activationEventId;
+    const evFooter = evId ? `\n[recall_id: ${evId}]` : '';
+
     return {
       content: [{
         type: 'text' as const,
-        text: packed.lines.join('\n') + peerSuffix + formatTokenFooter(packed, params.max_tokens),
+        text: packed.lines.join('\n') + peerSuffix + formatTokenFooter(packed, params.max_tokens) + evFooter,
       }],
     };
   }
@@ -539,9 +553,19 @@ Always call this after using a recalled memory so the system learns what's valua
     engram_id: z.string().describe('ID of the memory (from memory_recall results)'),
     useful: z.boolean().describe('Was this memory actually helpful?'),
     context: z.string().optional().describe('Brief note on why it was/wasn\'t useful'),
+    recall_id: z.string().optional().describe(
+      'The [recall_id: …] printed at the end of the memory_recall output that returned this memory. '
+      + 'Pass it so the feedback is joined to that recall; omitted, it defaults to the most recent recall in this session.',
+    ),
   },
   async (params) => {
-    await store.logRetrievalFeedback(null, params.engram_id, params.useful, params.context ?? '');
+    // 0.14.3: join feedback to the recall that produced it. Explicit recall_id
+    // wins; otherwise fall back to the engine's most recent logged activation —
+    // the common case is "recall, use, feedback" in one turn. Before this the
+    // MCP path hardcoded null (the HTTP route already accepted the id), which
+    // is why every retrieval_feedback row in the live store was orphaned.
+    const eventId = params.recall_id ?? activationEngine.lastActivationEventId ?? null;
+    await store.logRetrievalFeedback(eventId, params.engram_id, params.useful, params.context ?? '');
 
     const engram = await store.getEngram(params.engram_id);
     if (engram) {
@@ -645,7 +669,7 @@ server.tool(
   `Identify THIS AWM instance — agent id, mode (standalone/hive), backend, store path, code provenance, ports, and the sibling agent spaces present in the same store. Call when unsure which AWM instance or memory space you are talking to.`,
   {},
   async () => {
-    const info = await buildWhoami(store, AGENT_ID, 'mcp');
+    const info = await buildWhoami(store, AGENT_ID, 'mcp', sidecarHandle ? sidecarHandle.boundPort() : undefined);
     return { content: [{ type: 'text', text: formatWhoami(info) }] };
   },
 );
@@ -658,6 +682,11 @@ Also shows the activity log path so the user can tail it to see what's happening
   async () => {
     const metrics = await evalEngine.computeMetrics(AGENT_ID);
     const checkpoint = await store.getCheckpoint(AGENT_ID);
+    // 0.14.3: outcome numbers, not activity counters. "Edge utility" (share of
+    // edges ever activated) was monotone — it could only rise — and read as
+    // health when it was not. Latency was a mean over a column that mixes cold
+    // loads and stalls (live store: mean 20 s, median 1.6 s); medians only now.
+    const usage = await evalEngine.computeUsage(AGENT_ID);
     const lines = [
       `Agent: ${AGENT_ID}`,
       `Active memories: ${metrics.activeEngramCount}`,
@@ -665,9 +694,12 @@ Also shows the activity log path so the user can tail it to see what's happening
       `Retracted: ${metrics.retractedCount}`,
       `Avg confidence: ${metrics.avgConfidence.toFixed(3)}`,
       `Total edges: ${metrics.totalEdges}`,
-      `Edge utility: ${(metrics.edgeUtilityRate * 100).toFixed(1)}%`,
+      ``,
+      `Write:recall (30d): 1 : ${usage.recallsPerWrite30d.toFixed(2)}  (${usage.writes30d} writes, ${usage.recalls30d} recalls)`,
+      `Never recalled: ${(usage.neverRecalledShare * 100).toFixed(0)}% of active memories`,
+      `Recall→use (7d): ${usage.feedbackLinked7d > 0 ? (usage.usefulShare7d * 100).toFixed(0) + '% useful of ' + usage.feedbackLinked7d + ' judged' : 'no linked feedback yet'}`,
       `Activations (24h): ${metrics.activationCount}`,
-      `Avg latency: ${metrics.avgLatencyMs.toFixed(1)}ms`,
+      `Recall latency (24h): p50 ${metrics.p50LatencyMs.toFixed(0)}ms  p90 ${metrics.p90LatencyMs.toFixed(0)}ms`,
       ``,
       `Session writes: ${checkpoint?.auto.writeCountSinceConsolidation ?? 0}`,
       `Session recalls: ${checkpoint?.auto.recallCountSinceConsolidation ?? 0}`,
@@ -675,7 +707,10 @@ Also shows the activity log path so the user can tail it to see what's happening
       `Checkpoint: ${checkpoint?.executionState ? checkpoint.executionState.currentTask : 'none'}`,
       ``,
       `Activity log: ${getLogPath() ?? 'not configured'}`,
-      `Hook sidecar: 127.0.0.1:${HOOK_PORT}`,
+      // Report the port actually BOUND, not the one configured. Before 0.14.2
+      // this line said 8401 in every session, including the ones whose sidecar
+      // had lost the port and silently disabled hooks.
+      `Hook sidecar: ${sidecarPortLabel()}`,
     ];
 
     return {
@@ -1336,6 +1371,8 @@ async function main() {
     agentId: AGENT_ID,
     secret: HOOK_SECRET,
     port: HOOK_PORT,
+    portRange: HOOK_PORT_RANGE,
+    version: VERSION,
     // 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
@@ -1419,7 +1456,8 @@ async function main() {
 
   // Log to stderr (stdout is reserved for MCP protocol)
   console.error(`AgentWorkingMemory MCP server started (agent: ${AGENT_ID}, db: ${DB_PATH})`);
-  console.error(`Hook sidecar on 127.0.0.1:${HOOK_PORT}${HOOK_SECRET ? ' (auth enabled)' : ' (no auth — set AWM_HOOK_SECRET)'}`);
+  sidecarHandle = sidecar;
+  console.error(`Hook sidecar preferred 127.0.0.1:${HOOK_PORT} (range ${HOOK_PORT_RANGE})${HOOK_SECRET ? ' (auth enabled)' : ' (no auth — set AWM_HOOK_SECRET)'}`);
 
   // Clean shutdown
   const cleanup = async () => {

package/src/storage/pglite.ts

@@ -1020,7 +1020,7 @@ export class PGliteEngramStore {
     };
   }
 
-  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p95LatencyMs: number }> {
+  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p50LatencyMs: number; p90LatencyMs: number; p95LatencyMs: number }> {
     await this.readyPromise;
     // Flush any buffered activation events so stats reflect the latest writes.
     await this.flushActivationEvents();
@@ -1031,17 +1031,35 @@ export class PGliteEngramStore {
        ORDER BY latency_ms ASC`,
       [agentId, since],
     );
-    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
+    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p50LatencyMs: 0, p90LatencyMs: 0, p95LatencyMs: 0 };
     const latencies = result.rows.map((r) => Number(r.latency_ms));
     const total = latencies.reduce((s, l) => s + l, 0);
-    const p95Idx = Math.min(Math.floor(latencies.length * 0.95), latencies.length - 1);
+    // 0.14.3: p50/p90 — see sqlite.ts for why the mean is not usable here.
+    const pct = (q: number) => latencies[Math.min(Math.floor(latencies.length * q), latencies.length - 1)];
     return {
       count: latencies.length,
       avgLatencyMs: total / latencies.length,
-      p95LatencyMs: latencies[p95Idx],
+      p50LatencyMs: pct(0.5),
+      p90LatencyMs: pct(0.9),
+      p95LatencyMs: pct(0.95),
     };
   }
 
+  /** 0.14.3: feedback rows joined to an activation event — see sqlite.ts. */
+  async getLinkedFeedbackStats(agentId: string, windowHours: number = 24 * 7): Promise<{ total: number; useful: number }> {
+    await this.readyPromise;
+    const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
+    const result = await this.db.query<any>(
+      `SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = TRUE THEN 1 END) AS useful
+       FROM retrieval_feedback rf
+       JOIN activation_events ae ON ae.id = rf.activation_event_id
+       WHERE ae.agent_id = $1 AND rf.timestamp > $2`,
+      [agentId, since],
+    );
+    const row = result.rows[0] ?? { total: 0, useful: 0 };
+    return { total: Number(row.total), useful: Number(row.useful) };
+  }
+
   async getConsolidatedCount(agentId: string): Promise<number> {
     await this.readyPromise;
     const result = await this.db.query<any>(

package/src/storage/postgres.ts

@@ -1119,7 +1119,7 @@ export class PostgresEngramStore {
     };
   }
 
-  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p95LatencyMs: number }> {
+  async getActivationStats(agentId: string, windowHours: number = 24): Promise<{ count: number; avgLatencyMs: number; p50LatencyMs: number; p90LatencyMs: number; p95LatencyMs: number }> {
     await this.readyPromise;
     // Flush any buffered activation events so stats reflect the latest writes.
     await this.flushActivationEvents();
@@ -1130,17 +1130,35 @@ export class PostgresEngramStore {
        ORDER BY latency_ms ASC`,
       [agentId, since],
     );
-    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
+    if (result.rows.length === 0) return { count: 0, avgLatencyMs: 0, p50LatencyMs: 0, p90LatencyMs: 0, p95LatencyMs: 0 };
     const latencies = result.rows.map((r) => Number(r.latency_ms));
     const total = latencies.reduce((s, l) => s + l, 0);
-    const p95Idx = Math.min(Math.floor(latencies.length * 0.95), latencies.length - 1);
+    // 0.14.3: p50/p90 — see sqlite.ts for why the mean is not usable here.
+    const pct = (q: number) => latencies[Math.min(Math.floor(latencies.length * q), latencies.length - 1)];
     return {
       count: latencies.length,
       avgLatencyMs: total / latencies.length,
-      p95LatencyMs: latencies[p95Idx],
+      p50LatencyMs: pct(0.5),
+      p90LatencyMs: pct(0.9),
+      p95LatencyMs: pct(0.95),
     };
   }
 
+  /** 0.14.3: feedback rows joined to an activation event — see sqlite.ts. */
+  async getLinkedFeedbackStats(agentId: string, windowHours: number = 24 * 7): Promise<{ total: number; useful: number }> {
+    await this.readyPromise;
+    const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
+    const result = await this.q<any>(
+      `SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = TRUE THEN 1 END) AS useful
+       FROM retrieval_feedback rf
+       JOIN activation_events ae ON ae.id = rf.activation_event_id
+       WHERE ae.agent_id = $1 AND rf.timestamp > $2`,
+      [agentId, since],
+    );
+    const row = result.rows[0] ?? { total: 0, useful: 0 };
+    return { total: Number(row.total), useful: Number(row.useful) };
+  }
+
   async getConsolidatedCount(agentId: string): Promise<number> {
     await this.readyPromise;
     const result = await this.q<any>(

package/src/storage/sqlite.ts

@@ -1348,7 +1348,7 @@ export class EngramStore {
   }
 
   getActivationStats(agentId: string, windowHours: number = 24): {
-    count: number; avgLatencyMs: number; p95LatencyMs: number;
+    count: number; avgLatencyMs: number; p50LatencyMs: number; p90LatencyMs: number; p95LatencyMs: number;
   } {
     const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
     const rows = this.db.prepare(`
@@ -1357,17 +1357,39 @@ export class EngramStore {
       ORDER BY latency_ms ASC
     `).all(agentId, since) as { latency_ms: number }[];
 
-    if (rows.length === 0) return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
+    if (rows.length === 0) return { count: 0, avgLatencyMs: 0, p50LatencyMs: 0, p90LatencyMs: 0, p95LatencyMs: 0 };
 
+    // 0.14.3: p50/p90 added. The column mixes warm recalls with cold model loads
+    // and stalls (live store: mean 20 s, median 1.6 s, max 38 min), so the mean
+    // is not a usable number; percentiles are. Rows are already sorted ASC.
+    const pct = (q: number) => rows[Math.min(Math.floor(rows.length * q), rows.length - 1)].latency_ms;
     const total = rows.reduce((s, r) => s + r.latency_ms, 0);
-    const p95Index = Math.min(Math.floor(rows.length * 0.95), rows.length - 1);
     return {
       count: rows.length,
       avgLatencyMs: total / rows.length,
-      p95LatencyMs: rows[p95Index].latency_ms,
+      p50LatencyMs: pct(0.5),
+      p90LatencyMs: pct(0.9),
+      p95LatencyMs: pct(0.95),
     };
   }
 
+  /**
+   * 0.14.3: feedback rows in the window that are JOINED to an activation event.
+   * Unlinked rows (activation_event_id IS NULL — all 872 rows written before
+   * 0.14.3) are excluded on purpose: this is the recall→use signal, and a row
+   * that cannot be traced to a recall does not measure it.
+   */
+  getLinkedFeedbackStats(agentId: string, windowHours: number = 24 * 7): { total: number; useful: number } {
+    const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
+    const row = this.db.prepare(`
+      SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = 1 THEN 1 END) AS useful
+      FROM retrieval_feedback rf
+      JOIN activation_events ae ON ae.id = rf.activation_event_id
+      WHERE ae.agent_id = ? AND rf.timestamp > ?
+    `).get(agentId, since) as { total: number; useful: number };
+    return { total: row.total, useful: row.useful };
+  }
+
   getConsolidatedCount(agentId: string): number {
     const row = this.db.prepare(
       `SELECT COUNT(*) as cnt FROM engrams WHERE agent_id = ? AND stage = 'consolidated'`

package/src/types/engram.ts

@@ -219,6 +219,13 @@ export interface ActivationResult {
    * See `src/engine/confidence.ts` for the formula.
    */
   confidence?: number;
+  /**
+   * Id of the activation_events row this recall logged (0.14.3). Same value on
+   * every result in the same recall. Hand it back on memory_feedback so the
+   * feedback joins to the recall that produced it — before this, the id was
+   * generated and dropped, and every retrieval_feedback row was orphaned.
+   */
+  activationEventId?: string;
   /**
    * Confidence-adaptive content preview (Paper 3: cognitive teaming).
    * Set when the query opts in via `granularity: 'compact' | 'auto'`.
@@ -310,6 +317,15 @@ export interface ActivationQuery {
    * something different on every run.
    */
   asOf?: number;
+  /**
+   * 0.14.4: clock for ACT-R decay. Defaults to Date.now(). `asOf` pinned the
+   * temporal PARSER but decay still read the wall clock, so a "frozen" eval
+   * snapshot scored differently every day — a 300-query benchmark read 70.0%
+   * s@1 one evening and 67.0% the next afternoon on byte-identical data and
+   * code. Evals must pass the snapshot's own timestamp here. Production leaves
+   * it unset.
+   */
+  now?: number;
   bm25Only?: boolean;          // Skip embedding — fast text-only retrieval for bulk/benchmark scenarios
   /**
    * Output granularity (Paper 3: cognitive teaming, Brill 2018 ACT-R collaboration).

package/src/types/eval.ts

@@ -54,7 +54,9 @@ export interface EvalMetrics {
   // Retrieval quality
   activationCount: number;
   avgPrecisionAtK: number;    // Of returned results, % judged useful
-  avgLatencyMs: number;
+  avgLatencyMs: number;       // kept for callers; misleading on the live store (mixes cold loads) — prefer p50/p90
+  p50LatencyMs: number;       // 0.14.3
+  p90LatencyMs: number;       // 0.14.3
   p95LatencyMs: number;
 
   // Connection quality