agent-working-memory 0.13.1 → 0.14.1

package/src/core/whoami.ts

@@ -1,92 +1,110 @@
-// 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');
-}
+// 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';
+import { activeRecallConfig, recallConfigFingerprint } from './recall-config.js';
+import { embeddingHealth } from './embeddings.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 };
+  /**
+   * Effective recall configuration. `whoami` is the "what am I actually
+   * running" tool, and the version alone does not answer that: a build can be
+   * current while the recall flags that change its behaviour are unset, or set
+   * to something unintended. GET /health already reports this, but HTTP is off
+   * by default, so an MCP-only session had no way to see it.
+   */
+  recall: { fingerprint: string; flags: Record<string, string> };
+  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,
+    },
+    recall: { fingerprint: recallConfigFingerprint(), flags: activeRecallConfig() },
+    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'}`,
+    `Recall config: ${w.recall.fingerprint}`,
+    ...(embeddingHealth().dimensionMismatches > 0
+      ? [`\u26a0 EMBEDDING INTEGRITY: ${embeddingHealth().dimensionMismatches} dimension mismatches ` +
+         `(expected ${embeddingHealth().expectedDimensions}d). Affected memories score 0 on the ` +
+         `vector channel — the corpus is probably half-migrated. Re-embed the whole store or ` +
+         `revert AWM_EMBED_MODEL/AWM_EMBED_DIMS.`]
+      : []),
+    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

@@ -51,6 +51,7 @@ 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';
+import { buildRetrievalText } from './retrieval-text.js';
 
 /** Confidence floor below which a matched engram is treated as "decaying out". */
 export const HEALTHY_CONFIDENCE_FLOOR = 0.3;
@@ -195,7 +196,7 @@ export async function performWrite(
   let prewriteEmbedding: number[] | null = null;
   if (process.env.AWM_NOVELTY_EMBED !== '0') {
     try {
-      prewriteEmbedding = await embed(`${input.concept} ${input.content}`);
+      prewriteEmbedding = await embed(buildRetrievalText(input.concept, input.content, input.tags));
     } catch { /* fall through — async embed will retry later */ }
   }
   tEmbed = performance.now() - tStartEmbed;
@@ -434,7 +435,9 @@ async function reinforceMatched(
         // beyond 512 tokens but the topic anchor (early content) drives
         // the vector for retrieval purposes.
         const conceptForEmbed = newConceptHint || matched.concept;
-        const newVec = await embed(`${conceptForEmbed} ${mergedContent}`);
+        // The reinforced engram's OWN tags — `input` is not in scope here, and
+        // the stored tags are the right vocabulary for the stored memory anyway.
+        const newVec = await embed(buildRetrievalText(conceptForEmbed, mergedContent, matched.tags));
         await store.updateEmbedding(matched.id, newVec);
       } catch { /* merge is best-effort — confidence bump already landed */ }
     }
@@ -574,7 +577,7 @@ async function createNewEngram(
   const alreadyEmbedded = prewriteEmbedding != null && prewriteEmbedding.length > 0;
   const shouldEmbed = (!isStructural || input.embed === true) && !alreadyEmbedded;
   if (shouldEmbed) {
-    embed(`${input.concept} ${input.content}`)
+    embed(buildRetrievalText(input.concept, input.content, input.tags))
       .then(async vec => {
         try { await store.updateEmbedding(engram.id, vec); } catch { /* engram may be evicted */ }
       })