@vellumai/assistant 0.8.11 → 0.8.12-staging.2

package/src/plugins/defaults/memory-v3-shadow/learned-edges.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Tests for the learned-edge lane (`learned-edges.ts`).
+ *
+ * `computeLearnedEdgeGraph` takes the db handle directly (no module mocks):
+ * each test seeds an in-memory SQLite db with `memory_v3_selections` rows
+ * (via the real migration) and asserts the NPMI association graph. Rows
+ * sharing a `(conversation_id, created_at)` form one selector call.
+ */
+
+import { Database } from "bun:sqlite";
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import { migrateAddMemoryV3Selections } from "../../../memory/migrations/268-add-memory-v3-selections.js";
+import * as schema from "../../../memory/schema.js";
+import {
+  computeLearnedEdgeGraph,
+  type LearnedEdgesOptions,
+} from "./learned-edges.js";
+
+const HALF_LIFE_MS = 1_000_000;
+const NOW = 100_000;
+
+let sqlite: Database;
+let db: ReturnType<typeof drizzle<typeof schema>>;
+
+beforeEach(() => {
+  sqlite = new Database(":memory:");
+  db = drizzle(sqlite, { schema });
+  migrateAddMemoryV3Selections(db);
+});
+
+let nextTurn = 0;
+/** Insert one selector call: every slug shares the same (conv, created_at). */
+function seedCall(slugs: string[], createdAt = NOW, conv = "conv-1"): void {
+  const stmt = sqlite.query(
+    `INSERT INTO memory_v3_selections (conversation_id, turn, slug, source, pinned, created_at) VALUES (?, ?, ?, ?, ?, ?)`,
+  );
+  const turn = nextTurn++;
+  for (const slug of slugs) {
+    stmt.run(conv, turn, slug, "needle", 0, createdAt);
+  }
+}
+
+function graphOf(overrides: Partial<LearnedEdgesOptions> = {}) {
+  return computeLearnedEdgeGraph(
+    { db },
+    {
+      halfLifeMs: HALF_LIFE_MS,
+      minCount: 2,
+      npmiFloor: 0.2,
+      maxPerPage: 6,
+      now: NOW,
+      windowMs: NOW,
+      knownSlugs: new Set([
+        "page-a",
+        "page-b",
+        "page-c",
+        "page-d",
+        "skills/widget",
+      ]),
+      ...overrides,
+    },
+  );
+}
+
+const peersOf = (
+  graph: ReturnType<typeof computeLearnedEdgeGraph>,
+  slug: string,
+): string[] => [...(graph.adjacency.get(slug)?.keys() ?? [])];
+
+describe("computeLearnedEdgeGraph", () => {
+  test("pages selected together (and rarely apart) form a symmetric edge", () => {
+    // a+b co-select twice; c selects alone twice (so a/b are not ubiquitous).
+    seedCall(["page-a", "page-b"], NOW, "conv-1");
+    seedCall(["page-a", "page-b"], NOW, "conv-2");
+    seedCall(["page-c"], NOW, "conv-3");
+    seedCall(["page-c"], NOW, "conv-4");
+
+    const graph = graphOf();
+    expect(peersOf(graph, "page-a")).toEqual(["page-b"]);
+    expect(peersOf(graph, "page-b")).toEqual(["page-a"]);
+    expect(graph.hubs.size).toBe(0);
+  });
+
+  test("a page selected in every call forms no edges (NPMI → 0)", () => {
+    // page-a rides every call; page-b/page-c each appear half the time.
+    seedCall(["page-a", "page-b"], NOW, "conv-1");
+    seedCall(["page-a", "page-b"], NOW, "conv-2");
+    seedCall(["page-a", "page-c"], NOW, "conv-3");
+    seedCall(["page-a", "page-c"], NOW, "conv-4");
+
+    const graph = graphOf();
+    // p(a) = 1 ⇒ p(a,b) = p(b) ⇒ npmi = 0, floored out — for every pairing.
+    expect(peersOf(graph, "page-a")).toEqual([]);
+    expect(peersOf(graph, "page-b")).toEqual([]);
+  });
+
+  test("pairs below the co-occurrence mass floor form no edge", () => {
+    seedCall(["page-a", "page-b"], NOW, "conv-1"); // mass ≈ 1 < minCount 2
+    seedCall(["page-c"], NOW, "conv-2");
+    seedCall(["page-d"], NOW, "conv-3");
+
+    const graph = graphOf();
+    expect(peersOf(graph, "page-a")).toEqual([]);
+  });
+
+  test("decay pushes old co-selections below the mass floor", () => {
+    // Two co-selections ten half-lives ago: decayed mass ≈ 0.002 < 2.
+    seedCall(["page-a", "page-b"], NOW - 10 * HALF_LIFE_MS, "conv-1");
+    seedCall(["page-a", "page-b"], NOW - 10 * HALF_LIFE_MS, "conv-2");
+    seedCall(["page-c"], NOW, "conv-3");
+
+    const graph = graphOf({ windowMs: 20 * HALF_LIFE_MS });
+    expect(peersOf(graph, "page-a")).toEqual([]);
+  });
+
+  test("maxPerPage keeps the strongest associations first", () => {
+    // page-a co-selects with b twice and with c once alongside others, making
+    // a↔b the stronger association; cap page-a to one edge.
+    seedCall(["page-a", "page-b"], NOW, "conv-1");
+    seedCall(["page-a", "page-b"], NOW, "conv-2");
+    seedCall(["page-a", "page-c", "page-d"], NOW, "conv-3");
+    seedCall(["page-a", "page-c", "page-d"], NOW, "conv-4");
+    seedCall(["page-d"], NOW, "conv-5");
+    seedCall(["page-d"], NOW, "conv-6");
+
+    const graph = graphOf({ maxPerPage: 1 });
+    expect(peersOf(graph, "page-a")).toEqual(["page-b"]);
+  });
+
+  test("capability slugs participate like any page", () => {
+    seedCall(["skills/widget", "page-a"], NOW, "conv-1");
+    seedCall(["skills/widget", "page-a"], NOW, "conv-2");
+    seedCall(["page-b"], NOW, "conv-3");
+    seedCall(["page-b"], NOW, "conv-4");
+
+    const graph = graphOf();
+    expect(peersOf(graph, "skills/widget")).toEqual(["page-a"]);
+    expect(peersOf(graph, "page-a")).toEqual(["skills/widget"]);
+  });
+
+  test("slugs outside knownSlugs never form edges", () => {
+    seedCall(["page-a", "deleted-page"], NOW, "conv-1");
+    seedCall(["page-a", "deleted-page"], NOW, "conv-2");
+    seedCall(["page-b"], NOW, "conv-3");
+
+    const graph = graphOf();
+    expect(peersOf(graph, "page-a")).toEqual([]);
+    expect(graph.adjacency.has("deleted-page")).toBe(false);
+  });
+
+  test("maxPerPage = 0 disables the lane", () => {
+    seedCall(["page-a", "page-b"], NOW, "conv-1");
+    seedCall(["page-a", "page-b"], NOW, "conv-2");
+
+    const graph = graphOf({ maxPerPage: 0 });
+    expect(graph.adjacency.size).toBe(0);
+  });
+
+  test("rows outside the scan window are ignored", () => {
+    seedCall(["page-a", "page-b"], NOW - 50_000, "conv-1");
+    seedCall(["page-a", "page-b"], NOW - 60_000, "conv-2");
+
+    const graph = graphOf({ windowMs: 10_000 });
+    expect(graph.adjacency.size).toBe(0);
+  });
+});

package/src/plugins/defaults/memory-v3-shadow/learned-edges.ts

@@ -0,0 +1,178 @@
+/**
+ * Learned-edge lane: a co-selection association graph over
+ * `memory_v3_selections`, scored by NPMI (normalized pointwise mutual
+ * information).
+ *
+ * Two pages that keep getting SELECTED together are associated in how the
+ * corpus is actually used, whether or not any authored `[[link]]` connects
+ * them. That behavioral signal is exactly what the static edge lane cannot
+ * see, and it reaches the candidate class no other lane can: pages relevant
+ * by association, with no lexical/semantic overlap with the query and no
+ * curated link from any seed. Capability slugs (skills / CLI commands)
+ * participate like any page — a skill co-selected with a topic page is a
+ * real association worth following.
+ *
+ * Scoring: selections are grouped into selector calls
+ * (`conversation_id` + `created_at`); each call contributes a
+ * recency-decayed weight `2^(−age / halfLifeMs)` to every slug (unigram) and
+ * unordered slug-pair (co-occurrence) it selected. NPMI per pair:
+ *
+ *     npmi(a,b) = ln(p(a,b) / (p(a)·p(b))) / −ln(p(a,b))
+ *
+ * NPMI is what makes the lane safe around the stable-prefix pages: a page
+ * selected in (nearly) every call has p(a) ≈ 1, so p(a,b) ≈ p(b) and the
+ * numerator collapses to ~0 — ubiquitous pages form no edges, mathematically,
+ * rather than by special-casing. The `minCount` mass floor suppresses
+ * rare-pair noise (NPMI explodes on coincidences), and `maxPerPage` bounds
+ * each page's out-degree, which is the lane's real noise control.
+ *
+ * The result is emitted as an {@link EdgeGraph} so expansion REUSES
+ * `edgeExpand` unchanged. Neighbors are inserted in NPMI-descending order —
+ * `edgeExpand` takes neighbors in insertion order, so its `perSeed` budget
+ * consumes the strongest associations first. The graph carries no hubs
+ * (the per-page cap is the degree control) and no curated descriptions
+ * (the orchestrator falls back to a section descriptor).
+ *
+ * Like the other computed lanes, the graph is built at lane init and rebuilt
+ * on lane invalidation (the consolidation cadence). The selections table is
+ * the persistence; nothing else is stored.
+ */
+
+import {
+  type DrizzleDb,
+  getSqliteFrom,
+} from "../../../memory/db-connection.js";
+import type { EdgeGraph } from "./edge.js";
+import type { Slug } from "./types.js";
+
+export interface LearnedEdgesDeps {
+  /** Handle to the database containing `memory_v3_selections`. */
+  db: DrizzleDb;
+}
+
+export interface LearnedEdgesOptions {
+  /** Decay half-life in milliseconds: a selector call this old contributes
+   *  half the weight of one made now. */
+  halfLifeMs: number;
+  /** Minimum decayed co-occurrence mass for a pair to form an edge — the
+   *  rare-pair noise floor (NPMI explodes on coincidences). */
+  minCount: number;
+  /** Minimum NPMI for a pair to form an edge. */
+  npmiFloor: number;
+  /** Maximum out-edges kept per page (strongest-NPMI first); `0` disables
+   *  the lane (empty graph). */
+  maxPerPage: number;
+  /** Reference timestamp (ms epoch) ages are measured against. */
+  now: number;
+  /** Only selections younger than this window are read. At a 30-day
+   *  half-life, rows beyond ~90 days carry negligible weight anyway — the
+   *  window bounds the scan, not the math. */
+  windowMs: number;
+  /** Slugs that may form edges — the live section-index membership, so
+   *  selections of since-deleted pages can never surface a dangling
+   *  candidate. */
+  knownSlugs: Set<string>;
+}
+
+interface SelectionRow {
+  conversation_id: string;
+  slug: string;
+  created_at: number;
+}
+
+/**
+ * Build the learned-edge {@link EdgeGraph} from the selection log.
+ *
+ * Deterministic for fixed inputs: per-page neighbors order by NPMI desc, then
+ * peer slug asc. Symmetric by construction — an edge contributes to BOTH
+ * endpoints' neighbor lists (each independently subject to `maxPerPage`).
+ */
+export function computeLearnedEdgeGraph(
+  deps: LearnedEdgesDeps,
+  opts: LearnedEdgesOptions,
+): EdgeGraph {
+  const { halfLifeMs, minCount, npmiFloor, maxPerPage, now, windowMs } = opts;
+  const empty: EdgeGraph = {
+    adjacency: new Map(),
+    hubs: new Set(),
+    slugs: opts.knownSlugs,
+  };
+  if (maxPerPage <= 0) return empty;
+
+  const rows = getSqliteFrom(deps.db)
+    .query(
+      /*sql*/ `
+      SELECT conversation_id, slug, created_at FROM memory_v3_selections
+      WHERE created_at >= ?
+    `,
+    )
+    .all(now - windowMs) as SelectionRow[];
+  if (rows.length === 0) return empty;
+
+  // Group into selector calls; one decayed weight per call.
+  const calls = new Map<string, { weight: number; slugs: Set<Slug> }>();
+  for (const row of rows) {
+    if (!opts.knownSlugs.has(row.slug)) continue;
+    const key = `${row.conversation_id}|${row.created_at}`;
+    let call = calls.get(key);
+    if (!call) {
+      const age = Math.max(0, now - row.created_at);
+      call = { weight: 2 ** (-age / halfLifeMs), slugs: new Set() };
+      calls.set(key, call);
+    }
+    call.slugs.add(row.slug);
+  }
+
+  // Decayed unigram and pair masses. Pair keys order endpoints
+  // lexicographically so (a,b) and (b,a) accumulate together.
+  const uni = new Map<Slug, number>();
+  const pair = new Map<string, number>();
+  let total = 0;
+  for (const { weight, slugs } of calls.values()) {
+    total += weight;
+    const arr = [...slugs];
+    for (const slug of arr) uni.set(slug, (uni.get(slug) ?? 0) + weight);
+    for (let i = 0; i < arr.length; i++) {
+      for (let j = i + 1; j < arr.length; j++) {
+        const key =
+          arr[i]! < arr[j]! ? `${arr[i]}\t${arr[j]}` : `${arr[j]}\t${arr[i]}`;
+        pair.set(key, (pair.get(key) ?? 0) + weight);
+      }
+    }
+  }
+  if (total <= 0) return empty;
+
+  // Score pairs and collect each endpoint's qualifying neighbors.
+  const neighbors = new Map<Slug, Array<{ peer: Slug; npmi: number }>>();
+  const addNeighbor = (from: Slug, peer: Slug, npmi: number): void => {
+    let list = neighbors.get(from);
+    if (!list) {
+      list = [];
+      neighbors.set(from, list);
+    }
+    list.push({ peer, npmi });
+  };
+  for (const [key, mass] of pair) {
+    if (mass < minCount) continue;
+    const [a, b] = key.split("\t") as [Slug, Slug];
+    const pab = mass / total;
+    const pa = uni.get(a)! / total;
+    const pb = uni.get(b)! / total;
+    const npmi = Math.log(pab / (pa * pb)) / -Math.log(pab);
+    if (npmi <= npmiFloor) continue;
+    addNeighbor(a, b, npmi);
+    addNeighbor(b, a, npmi);
+  }
+
+  // Emit adjacency with neighbors in NPMI-desc order (edgeExpand consumes
+  // insertion order), capped per page.
+  const adjacency = new Map<Slug, Map<Slug, string | undefined>>();
+  for (const [slug, list] of neighbors) {
+    list.sort((x, y) => y.npmi - x.npmi || (x.peer < y.peer ? -1 : 1));
+    const out = new Map<Slug, string | undefined>();
+    for (const { peer } of list.slice(0, maxPerPage)) out.set(peer, undefined);
+    adjacency.set(slug, out);
+  }
+
+  return { adjacency, hubs: new Set(), slugs: opts.knownSlugs };
+}

package/src/plugins/defaults/memory-v3-shadow/orchestrate.ts

@@ -2,21 +2,29 @@
  * Memory v3 — orchestrator composing the candidate lanes into one turn.
  *
  * Each turn runs:
- *   1. Candidate generation over three deterministic finder lanes:
+ *   1. Candidate generation over the deterministic finder lanes:
  *        - the section-grain BM25 needle (`SectionNeedle.query`, KB articles),
- *        - the dense lane (`denseLane`, KD articles), and
- *        - link-graph edge expansion (`edgeExpand`) over the top needle+dense
- *          article seeds.
+ *        - the dense lane (`denseLane`, KD articles),
+ *        - the reply-query pass — needle + dense re-run over the assistant's
+ *          PREVIOUS message as separate queries at a smaller budget
+ *          (`replyQueryK` per lane), surfacing the threads the assistant is
+ *          actively developing that the user's message references without
+ *          naming — and
+ *        - link-graph edge expansion (`edgeExpand`) over the top
+ *          user-message needle+dense article seeds, and
+ *        - learned-edge expansion (`edgeExpand` over the co-selection NPMI
+ *          graph from `learned-edges.ts`) over the same seeds — behavioral
+ *          associations the authored link graph does not record.
  *      Each lane only ever ADDS candidates, so the pool is recall-safe by
  *      construction.
  *   2. Build the candidate pool in CACHE ORDER: the stable prefix —
- *      `[...core (file order), ...hot (score order)]`, both computed at lane
- *      init — followed by the finder candidates (needle → dense → edge
- *      surfacing order). The stable prefix is identical across consecutive
- *      turns while the lanes are unchanged (lane invalidation at consolidation
- *      is the recompute cadence), so the selector input's leading segment
- *      rides the provider KV cache (the cache breakpoint itself lives in
- *      `pool-select.ts`).
+ *      `[...core (file order), ...hot (score order), ...fresh (recency
+ *      order)]`, all computed at lane init — followed by the finder
+ *      candidates (needle → dense → edge surfacing order). The stable prefix
+ *      is identical across consecutive turns while the lanes are unchanged
+ *      (lane invalidation at consolidation is the recompute cadence), so the
+ *      selector input's leading segment rides the provider KV cache (the
+ *      cache breakpoint itself lives in `pool-select.ts`).
  *
  *      Stable-prefix candidates render as FULL CARDS (`renderCard` — head
  *      section + TOC), pre-rendered at lane init (`prefixCards`) so the
@@ -71,16 +79,23 @@ export interface OrchestrateDeps {
   /** The frecency hot set in score order (computed at lane init with the core
    *  set excluded). Follows core in the stable prefix. */
   hotSlugs: Slug[];
+  /** The modification-recency fresh set in recency order (computed at lane
+   *  init with core and hot excluded). Follows hot in the stable prefix. */
+  freshSlugs: Slug[];
   /** Pre-rendered FULL cards for the stable-prefix slugs, keyed by slug.
    *  Rendered ONCE at lane init so the selector's stable prefix is
-   *  byte-identical across turns (the cache contract). Every core/hot slug
-   *  MUST have an entry — a missing card is a lane-init bug and throws
+   *  byte-identical across turns (the cache contract). Every core/hot/fresh
+   *  slug MUST have an entry — a missing card is a lane-init bug and throws
    *  (silently degrading would violate the byte-stable-prefix contract). */
   prefixCards: ReadonlyMap<Slug, string>;
   /** Number of BM25 needle articles. Defaults to {@link DEFAULT_NEEDLE_K}. */
   needleK?: number;
   /** Number of dense-lane articles. Defaults to {@link DEFAULT_DENSE_K}. */
   denseK?: number;
+  /** Per-lane article budget for the reply-query pass (needle + dense re-run
+   *  over `turn.previousAssistantMessage` as separate queries). `0` or
+   *  omitted disables the pass (canonical value: `memory.v3.replyQueryK`). */
+  replyQueryK?: number;
   /** Number of top needle+dense seeds expanded. When omitted, the edge lane's
    *  own default applies (canonical value: `memory.v3.edge.seedCount`). */
   edgeSeeds?: number;
@@ -90,6 +105,15 @@ export interface OrchestrateDeps {
   /** Hard cap on total edge-lane surfaced articles. When omitted, the edge
    *  lane's own default applies (canonical value: `memory.v3.edge.cap`). */
   edgeCap?: number;
+  /** The learned-edge graph (co-selection NPMI associations, built at lane
+   *  init). Omitted or empty → no learned pass. */
+  learnedGraph?: EdgeGraph;
+  /** Learned neighbours surfaced per expanded seed (canonical value:
+   *  `memory.v3.learnedEdges.perSeed`). */
+  learnedPerSeed?: number;
+  /** Hard cap on total learned-lane surfaced articles; `0` disables the pass
+   *  (canonical value: `memory.v3.learnedEdges.cap`). */
+  learnedCap?: number;
 }
 
 /** A finder-lane candidate: the slug, the descriptor that justified it, and
@@ -101,16 +125,19 @@ export interface FinderCandidate {
 }
 
 /**
- * The three candidate lanes in cache order. `core` and `hot` are the stable
- * prefix (byte-identical across turns while lanes are unchanged); `finder` is
- * the dynamic tail and MAY repeat a stable-prefix slug (a finder hit on a
- * core/hot page is kept so its current relevance stays visible downstream).
+ * The candidate lanes in cache order. `core`, `hot`, and `fresh` are the
+ * stable prefix (byte-identical across turns while lanes are unchanged);
+ * `finder` is the dynamic tail and MAY repeat a stable-prefix slug (a finder
+ * hit on a stable-prefix page is kept so its current relevance stays visible
+ * downstream).
  */
 export interface OrchestrateLanes {
   /** Curated core set, file order. */
   core: Slug[];
   /** Frecency hot set, score order (never overlaps core). */
   hot: Slug[];
+  /** Modification-recency fresh set, recency order (never overlaps core/hot). */
+  fresh: Slug[];
   /** Finder candidates in surfacing order, deduped among themselves only. */
   finder: FinderCandidate[];
 }
@@ -144,19 +171,34 @@ export async function orchestrate(
   const denseK = deps.denseK ?? DEFAULT_DENSE_K;
   const { sections } = deps.sectionIndex;
 
-  // The stable prefix: core (file order) then hot (score order). Hot is
-  // computed with core excluded at lane init; the filter here is a cheap
-  // defensive dedup so a misbehaving lane can never double-list a slug.
+  // The stable prefix: core (file order), hot (score order), fresh (recency
+  // order). Hot is computed with core excluded at lane init, fresh with both
+  // excluded; the filters here are a cheap defensive dedup so a misbehaving
+  // lane can never double-list a slug.
   const core = deps.coreSlugs;
   const hot = deps.hotSlugs.filter((slug) => !core.includes(slug));
-  const stablePrefix = new Set<Slug>([...core, ...hot]);
+  const coreHot = new Set<Slug>([...core, ...hot]);
+  const fresh = deps.freshSlugs.filter((slug) => !coreHot.has(slug));
+  const stablePrefix = new Set<Slug>([...coreHot, ...fresh]);
 
   // Step 1: needle (sync BM25) and dense (async embed + Qdrant) lanes run in
   // parallel. Both return distinct articles each tagged with their best-scoring
-  // section index/ordinal.
-  const [needled, densed] = await Promise.all([
+  // section index/ordinal. The reply-query pass re-runs both lanes over the
+  // assistant's previous message as SEPARATE queries (concatenating the two
+  // speakers would average their retrieval intents into a vector that matches
+  // neither) at its own, smaller budget; it runs in the same parallel batch.
+  const replyK = deps.replyQueryK ?? 0;
+  const replyQuery =
+    replyK > 0 ? (turn.previousAssistantMessage ?? "").trim() : "";
+  const [needled, densed, replyNeedled, replyDensed] = await Promise.all([
     Promise.resolve(deps.needle.query(turn.currentMessage, needleK)),
     denseLane(deps.denseConfig, turn.currentMessage, denseK),
+    Promise.resolve(
+      replyQuery.length > 0 ? deps.needle.query(replyQuery, replyK) : [],
+    ),
+    replyQuery.length > 0
+      ? denseLane(deps.denseConfig, replyQuery, replyK)
+      : Promise.resolve([]),
   ]);
 
   // `matchedSections` records the matched `Section` (when one is known) for
@@ -211,6 +253,24 @@ export async function orchestrate(
     );
   }
 
+  // Step 1b': reply-query hits — candidates the user-message lanes already
+  // surfaced keep their primary attribution (`addFinder`'s first-lane-wins
+  // dedup); only genuinely reply-surfaced articles tag `"reply"`. Matched
+  // sections are recorded the same way as the primary lanes', so injection
+  // and the spotlight render the reply-matched section.
+  for (const hit of replyNeedled) {
+    addFinder(hit.article, sections[hit.section], undefined, "reply");
+  }
+  for (const hit of replyDensed) {
+    if (!deps.sectionIndex.byArticle.has(hit.article)) continue;
+    addFinder(
+      hit.article,
+      sectionByOrdinal(deps.sectionIndex, hit.article, hit.section),
+      undefined,
+      "reply",
+    );
+  }
+
   // Step 1c: edge expansion over the top needle+dense article seeds. `alive`
   // skips slugs already in the pool — finder-surfaced AND stable-prefix slugs
   // (an edge hit carries no matched section, so re-surfacing a core/hot page
@@ -245,8 +305,36 @@ export async function orchestrate(
     );
   }
 
+  // Step 1d: learned-edge expansion over the SAME seeds, through the
+  // co-selection NPMI graph. Mirrors the static edge pass — no matched
+  // section (association, not lexical relevance, surfaced the page; injection
+  // falls back to the full page), `bestSection` text as the descriptor
+  // fallback — but tags `"learned"` so the lane's selection rate is
+  // measurable. Runs after the static lane: an association that duplicates an
+  // authored link keeps its `"edge"` attribution.
+  if (deps.learnedGraph && (deps.learnedCap ?? 0) > 0) {
+    const learned = edgeExpand(deps.learnedGraph, seeds, {
+      seedCount: deps.edgeSeeds,
+      perSeed: deps.learnedPerSeed,
+      cap: deps.learnedCap,
+      alive: (slug) => !finderSeen.has(slug) && !stablePrefix.has(slug),
+    });
+    for (const neighbor of learned) {
+      const best = deps.needle.bestSection(
+        neighbor.article,
+        turn.currentMessage,
+      );
+      addFinder(
+        neighbor.article,
+        undefined,
+        best >= 0 ? sections[best]?.text : undefined,
+        "learned",
+      );
+    }
+  }
+
   // Step 2: assemble the selector pool in cache order — the stable prefix
-  // (core then hot) as FULL CARDS, then the finder tail. Cards are
+  // (core, hot, fresh) as FULL CARDS, then the finder tail. Cards are
   // pre-rendered at lane init (`prefixCards`): query- AND
   // conversation-state-INDEPENDENT by design, so the rendered prefix is
   // byte-identical across turns while the lanes are unchanged. The tail is
@@ -254,7 +342,7 @@ export async function orchestrate(
   // its own snippet line so its CURRENT relevance stays visible; `selectPool`
   // dedupes selections by slug. Finder candidates with no match text fall
   // back to the page's lead-section snippet.
-  const stable: StableCandidate[] = [...core, ...hot].map((slug) => {
+  const stable: StableCandidate[] = [...core, ...hot, ...fresh].map((slug) => {
     const card = deps.prefixCards.get(slug);
     if (card === undefined) {
       // Lane init renders a card for every core/hot slug; a hole here means
@@ -269,6 +357,7 @@ export async function orchestrate(
   });
   const finderTail: PoolCandidate[] = finder.map((c) => ({
     slug: c.slug,
+    lane: c.lane,
     descriptor:
       c.descriptor.trim().length > 0
         ? c.descriptor
@@ -283,7 +372,7 @@ export async function orchestrate(
   return {
     selections,
     matchedSections,
-    lanes: { core, hot, finder },
+    lanes: { core, hot, fresh, finder },
   };
 }
 

package/src/plugins/defaults/memory-v3-shadow/pool-select.ts

@@ -62,10 +62,12 @@ const log = getLogger("memory-v3-pool-select");
 
 /** A dynamic-tail (finder) candidate: the slug plus the descriptor that
  *  justifies it — a matched section for a needle/dense hit, or a curated link
- *  description for an edge page. Rendered as a one-line snippet. */
+ *  description for an edge page. Rendered as a one-line snippet, prefixed
+ *  with the surfacing lane when one is supplied. */
 export interface PoolCandidate {
   slug: Slug;
   descriptor: string;
+  lane?: string;
 }
 
 /** A stable-prefix candidate: the slug plus its pre-rendered FULL card
@@ -127,13 +129,13 @@ const SELECT_PAGES_TOOL: ToolDefinition = {
   },
 };
 
-const SYSTEM_PROMPT = `You are given the candidate memory pages for an assistant's next reply, in two segments that share one numbering: full page cards first (the curated core and recently-recurring pages, shown every turn), then this turn's search hits as one-line snippets.
+const SYSTEM_PROMPT = `You are given the candidate memory pages for an assistant's next reply, in two segments that share one numbering: full page cards first (the curated core, recently-recurring, and recently-modified pages, shown every turn), then this turn's search hits as one-line snippets. Cards carry a \`[lane: …]\` annotation — core is curated, hot recurs by selection frequency, fresh was recently modified (with its last-update time) — and search hits are tagged with the lane that surfaced them.
 
-Select EVERY candidate whose content the upcoming reply would draw on. That includes facts the reply needs, but equally register, established framing, calibration rules, and relationship/person/project texture — pages that shape HOW to reply, not only what to say. There is no limit on how many you may select; recall matters more than precision, so when a candidate could plausibly inform the reply, keep it. For a list or an "all of X" request, keep EVERY candidate that belongs to X rather than guessing a representative subset.
+Select EVERY candidate whose content the upcoming reply would draw on. That includes facts the reply needs, current task and event state (open items, deadlines, schedules, recent activity), and equally register, established framing, calibration rules, and relationship/person/project texture — pages that shape HOW to reply, not only what to say. There is no limit on how many you may select; recall matters more than precision, so when a candidate could plausibly inform the reply, keep it. For a list or an "all of X" request, keep EVERY candidate that belongs to X rather than guessing a representative subset.
 
 Pages you select persist in the conversation automatically, and re-selecting a page that is already in context is harmless (duplicates are removed downstream) — so never withhold a candidate because it might have been selected before. Judge each candidate only by whether the upcoming reply would draw on it.
 
-A page can be relevant because of the current situation — the date or the live scratchpad — not only the message: keep a page the situation makes pertinent (e.g. a person whose anniversary is today).
+A page can be relevant because of the current situation — the date or the live scratchpad — not only the message: keep a page the situation makes pertinent (e.g. a person whose anniversary is today). When the message asks about status, plans, schedule, or what's pending, treat pages carrying current task/event state — especially recently-updated (fresh) ones — as first-class candidates.
 
 If the conversation is centrally ABOUT a page (rather than only peripherally relevant to it), mark that page as pinned. Call \`select_pages\` with the chosen IDs. Omit \`ids\` only as a recall-safe fallback when you cannot judge the pool (keeps every candidate); return \`[]\` when candidates are present but none are relevant.`;
 
@@ -153,17 +155,19 @@ function renderCardSegment(stable: StableCandidate[]): string {
 }
 
 /**
- * Render the finder tail: one `[m+i] slug — snippet` line per candidate,
- * numbered continuing after the `offset` stable-prefix cards. A candidate
- * with an empty descriptor renders without the dash.
+ * Render the finder tail: one `[m+i] (lane) slug — snippet` line per
+ * candidate, numbered continuing after the `offset` stable-prefix cards. The
+ * lane tag is omitted for a candidate without one; a candidate with an empty
+ * descriptor renders without the dash.
  */
 function renderFinderSegment(finder: PoolCandidate[], offset: number): string {
   const lines = finder.map((c, i) => {
     const snippet = renderSnippet(c.descriptor);
     const id = offset + i + 1;
+    const lane = c.lane !== undefined ? `(${c.lane}) ` : "";
     return snippet.length > 0
-      ? `[${id}] ${c.slug} — ${snippet}`
-      : `[${id}] ${c.slug}`;
+      ? `[${id}] ${lane}${c.slug} — ${snippet}`
+      : `[${id}] ${lane}${c.slug}`;
   });
   return `<candidates>\n${lines.join("\n")}\n</candidates>`;
 }