@seanhogg/builderforce-memory 2026.10.26 → 2026.10.28

package/dist/working/transcript.js

@@ -46,49 +46,81 @@ function messageTokens(m) {
     return handoffMessageTokens(m, defaultEstimateTokens);
 }
 /**
- * Trim the in-memory transcript to the history window before sending it to the
- * model. Slicing the last N can leave the window starting on an `assistant`
- * tool-call turn or an orphaned `tool` result (whose owning call fell off the
- * front). That payload is invalid for strict vendors: Gemini rejects a request
- * whose conversation does not begin with a user turn — surfaced as the cascade
- * `[googleai] 400 INVALID_ARGUMENT` after a long tool-loop crossed the window
- * boundary. So anchor the window at a user turn.
- *
- * If the last-N slice contains no user turn (a tool loop longer than the
- * window), fall back to the most recent user turn in the FULL transcript and
- * keep everything after it — correctness over the size cap.
+ * How far the message window's front moves at a time — a quarter of
+ * {@link HISTORY_WINDOW}. See {@link windowed}.
  */
-export function windowed(convo) {
-    let w = convo.slice(-HISTORY_WINDOW);
-    while (w.length > 0 && w[0].role !== 'user')
-        w = w.slice(1);
-    if (w.length === 0) {
-        const lastUser = convo.map((m) => m.role).lastIndexOf('user');
-        w = lastUser >= 0 ? convo.slice(lastUser) : convo.slice();
+export const HISTORY_WINDOW_DROP_CHUNK = HISTORY_WINDOW / 4;
+/**
+ * How far (in tokens) the token window's front moves at a time — a quarter of
+ * {@link HISTORY_TOKEN_BUDGET}, so a drop leaves the window at ~75% of the budget and
+ * the next one waits for ~16k tokens of new work. See {@link windowed}.
+ */
+export const HISTORY_TOKEN_DROP_CHUNK = HISTORY_TOKEN_BUDGET / 4;
+/**
+ * Where the message-count window begins: 0 while the transcript fits
+ * {@link HISTORY_WINDOW}, else the first multiple of {@link HISTORY_WINDOW_DROP_CHUNK}
+ * that brings it back under. The cut points are fixed positions in the transcript, so
+ * the front stays put while new messages arrive and jumps a whole chunk when it moves.
+ */
+function messageWindowStart(length) {
+    if (length <= HISTORY_WINDOW)
+        return 0;
+    return Math.ceil((length - HISTORY_WINDOW) / HISTORY_WINDOW_DROP_CHUNK) * HISTORY_WINDOW_DROP_CHUNK;
+}
+/**
+ * Where the token window begins: 0 while the transcript fits
+ * {@link HISTORY_TOKEN_BUDGET}, else the first cut point that brings it back under. A
+ * cut point is the message after which the transcript's running total crosses a multiple
+ * of {@link HISTORY_TOKEN_DROP_CHUNK} — counted from the transcript's own start, so a
+ * cut point never moves as the transcript grows at the end.
+ */
+function tokenWindowStart(convo) {
+    const sizes = convo.map(messageTokens);
+    let remaining = sizes.reduce((sum, n) => sum + n, 0);
+    if (remaining <= HISTORY_TOKEN_BUDGET)
+        return 0;
+    let dropped = 0;
+    let nextCut = HISTORY_TOKEN_DROP_CHUNK;
+    for (let i = 0; i < convo.length; i++) {
+        dropped += sizes[i];
+        remaining -= sizes[i];
+        if (dropped < nextCut)
+            continue;
+        while (dropped >= nextCut)
+            nextCut += HISTORY_TOKEN_DROP_CHUNK;
+        if (remaining <= HISTORY_TOKEN_BUDGET)
+            return i + 1;
     }
-    return tokenBounded(w);
+    return convo.length;
 }
 /**
- * Enforce the token budget on an already message-count-windowed slice. Drops the
- * OLDEST turns first, then re-anchors on a user turn (a strict vendor rejects a window
- * that doesn't start on `user`, and dropping a turn can orphan a `tool` result whose
- * `assistant` tool-call fell off the front). The most recent user turn is never
- * dropped: correctness over the budget when a single turn is itself oversized.
+ * Trim the in-memory transcript to the history window — the message-count window
+ * ({@link HISTORY_WINDOW}) and the token budget ({@link HISTORY_TOKEN_BUDGET}) — before
+ * sending it to the model.
+ *
+ * The OLDEST turns go first, in CHUNKS with hysteresis: once over, the front jumps to
+ * the next fixed cut point ({@link HISTORY_WINDOW_DROP_CHUNK} messages /
+ * {@link HISTORY_TOKEN_DROP_CHUNK} tokens), leaving room the following turns fill before
+ * it moves again. Dropping exactly to the limit slid the front by a message or two on
+ * every turn, so the request's prefix changed every turn and no provider prefix cache
+ * could hit past the system prompt.
+ *
+ * The window is then anchored at a user turn: a window starting on an `assistant`
+ * tool-call turn or an orphaned `tool` result (whose owning call fell off the front) is
+ * invalid for strict vendors — Gemini rejects a request whose conversation does not
+ * begin with a user turn (the cascade `[googleai] 400 INVALID_ARGUMENT` after a long
+ * tool loop crossed the window boundary). The most recent user turn is never dropped:
+ * correctness over the size cap, when a tool loop outgrows the window or a single turn
+ * is itself oversized.
  */
-function tokenBounded(w) {
-    let total = transcriptTokens(w);
-    if (total <= HISTORY_TOKEN_BUDGET)
-        return w;
-    const lastUser = w.map((m) => m.role).lastIndexOf('user');
-    let start = 0;
-    while (total > HISTORY_TOKEN_BUDGET && start < lastUser) {
-        total -= messageTokens(w[start]);
+export function windowed(convo) {
+    const lastUser = convo.map((m) => m.role).lastIndexOf('user');
+    if (lastUser < 0)
+        return transcriptTokens(convo) <= HISTORY_TOKEN_BUDGET ? convo.slice() : convo.slice(-1);
+    let start = Math.min(Math.max(messageWindowStart(convo.length), tokenWindowStart(convo)), lastUser);
+    while (convo[start].role !== 'user')
         start += 1;
-    }
-    let trimmed = w.slice(start);
-    while (trimmed.length > 1 && trimmed[0].role !== 'user')
-        trimmed = trimmed.slice(1);
-    return trimmed;
+    return convo.slice(start);
 }
 /**
  * Is a transcript message still part of what the model sees? False once auto-compaction
@@ -109,11 +141,11 @@ export function stillInWorkingContext(state, anchor) {
 // ---------------------------------------------------------------------------
 // Auto-compaction — summarize the bulky MIDDLE instead of dropping it.
 //
-// `tokenBounded` keeps the request inside the window by DROPPING the oldest turns. That
+// `windowed` keeps the request inside the window by DROPPING the oldest turns. That
 // never 413s, but it silently LOSES context — which made a weak model re-read files and
 // thrash ("LOOP EXHAUSTED", chat #50). When a summarizer is available the older turns are
 // compressed into ONE memory note instead, so the model keeps working from a distilled
-// memory. Falls back to `tokenBounded` when no summarizer is reachable.
+// memory. Falls back to `windowed` when no summarizer is reachable.
 //
 // Why this fold is NOT `packHandoff` (`../handoff`): the packer is stateless and gives the
 // verbatim tail priority, handing the note whatever room the tail leaves. The working

package/dist/working/transcript.js.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/working/transcript.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/working/transcript.ts"],"names":[],"mappings":"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"}

package/dist/working/types.d.ts

@@ -29,5 +29,11 @@ export interface ConsolidateOptions {
     at?: Date;
     /** The workspace root — absolute paths under it are kept, made relative. */
     root?: string;
+    /**
+     * Distinct files (changed, deleted and read together) a run must touch for its map to
+     * be kept. Defaults to `MIN_CONSOLIDATED_FILES`; the same floor applies to a run that
+     * changed files as to one that only read.
+     */
+    minFiles?: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/working/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/working/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,wFAAwF;AACxF,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/working/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,wFAAwF;AACxF,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.10.26",
-  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, enterprise RAG (ingestion pipelines, vector-store adapters, tenant/ACL-scoped hybrid retrieval), multi-agent graph orchestration, LLM telemetry and cost accounting, and persistent agent memory for BuilderForce.ai agents.",
+  "version": "2026.10.28",
+  "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, enterprise RAG (ingestion pipelines, vector-store adapters, tenant/ACL-scoped hybrid retrieval), multi-agent graph orchestration, LLM telemetry and cost accounting, persistent agent memory, and token-saving agent-run memory (code maps, a prompt-cache-safe working memory, chunked transcript windowing) for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -85,7 +85,13 @@
     "multi-agent",
     "observability",
     "enterprise-ai",
-    "langgraph-alternative"
+    "langgraph-alternative",
+    "code-map",
+    "working-memory",
+    "prompt-caching",
+    "context-window",
+    "token-optimization",
+    "coding-agent"
   ],
   "author": {
     "name": "Sean Hogg",
@@ -103,7 +109,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.10.26"
+    "@seanhogg/builderforce-memory-engine": "^2026.10.28"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -117,7 +123,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory-engine": "2026.10.26"
+    "@seanhogg/builderforce-memory-engine": "2026.10.28"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/working/codemap.test.ts

@@ -0,0 +1,144 @@
+/**
+ * src/working/codemap.test.ts
+ * Code maps (2026.10.27): the 3-file floor for every run, the root area, reading a
+ * stored map back, and which maps a run is handed.
+ */
+
+import {
+  CONSOLIDATED_ROOT_AREA,
+  areaOfPath,
+  areasNamedIn,
+  areasOfPathsIn,
+  consolidate,
+  consolidatedArea,
+  consolidatedFactsFor,
+  consolidatedFiles,
+  mergeConsolidated,
+  withoutConsolidatedFiles,
+  type WorkingMemorySnapshot,
+} from './index.js';
+
+const AT = new Date('2026-10-26T12:00:00Z');
+
+function snap(partial: Partial<WorkingMemorySnapshot>): WorkingMemorySnapshot {
+  return { created: [], edited: [], deleted: [], read: [], searched: [], ...partial };
+}
+
+describe('consolidate — the minimum holds for every run', () => {
+  it('skips a one- or two-file run that changed files', () => {
+    expect(consolidate(snap({ edited: ['api/src/r/x.ts'] }))).toBeNull();
+    expect(consolidate(snap({ edited: ['api/src/r/x.ts'], read: ['api/src/r/y.ts'] }))).toBeNull();
+    expect(consolidate(snap({ created: ['api/src/r/x.ts'], deleted: ['api/src/r/old.ts'] }))).toBeNull();
+  });
+
+  it('counts changed and read files together', () => {
+    const c = consolidate(snap({ edited: ['api/src/r/x.ts'], read: ['api/src/r/y.ts', 'api/src/r/z.ts'] }), { at: AT });
+    expect(c?.key).toBe('codemap:api/src/r');
+  });
+
+  it('counts a file once however it was touched', () => {
+    expect(consolidate(snap({ edited: ['a/b/x.ts'], read: ['a/b/x.ts', 'a/b/x.ts', 'a/b/y.ts'] }))).toBeNull();
+  });
+
+  it('does not count noise it drops', () => {
+    expect(consolidate(snap({ edited: ['a/b/x.ts'], read: ['pnpm-lock.yaml', 'node_modules/p/i.js', 'a/b/y.ts'] }))).toBeNull();
+  });
+});
+
+describe('consolidate — root files', () => {
+  it('files a root-only run under the root area', () => {
+    const c = consolidate(snap({ edited: ['DONE.md', 'ROADMAP.md'], read: ['package.json'] }), { at: AT })!;
+    expect(c.key).toBe(`codemap:${CONSOLIDATED_ROOT_AREA}`);
+  });
+
+  it('maps a root file to the same area a reader resolves it to', () => {
+    const c = consolidate(snap({ read: ['README.md', 'package.json', 'tsconfig.json'] }), { at: AT })!;
+    expect(consolidatedArea(c.key)).toBe(areaOfPath('README.md'));
+    expect(consolidatedFactsFor([c], [areaOfPath('package.json')])).toEqual([c]);
+  });
+});
+
+describe('areaOfPath', () => {
+  it('is a file\'s directory, a directory itself, or the root area', () => {
+    expect(areaOfPath('web/src/a.ts')).toBe('web/src');
+    expect(areaOfPath('.\\web\\src\\a.ts')).toBe('web/src');
+    expect(areaOfPath('clients/vscode/src')).toBe('clients/vscode/src');
+    expect(areaOfPath('DONE.md')).toBe(CONSOLIDATED_ROOT_AREA);
+    expect(areaOfPath('  ')).toBe('');
+  });
+});
+
+describe('areasOfPathsIn', () => {
+  it('takes the areas of the repo-relative paths a text names', () => {
+    expect(areasOfPathsIn('Touches `brain-embedded/src/runStore/dispatchTool.ts` and C:/abs/x.ts, see (docs/specs/35.md).')).toEqual([
+      'brain-embedded/src/runStore',
+      'docs/specs',
+    ]);
+  });
+
+  it('maps a root file to the root area and skips what is not a repo path', () => {
+    expect(areasOfPathsIn('bump package.json, e.g. now')).toEqual([CONSOLIDATED_ROOT_AREA]);
+    expect(areasOfPathsIn('see https://x.dev/a/b.ts and /etc/hosts and ../up/x.ts')).toEqual([]);
+  });
+});
+
+describe('reading a stored map back', () => {
+  const map = consolidate(snap({ read: ['w/s/a.ts', 'w/s/b.ts'], edited: ['w/s/c.ts'] }), { at: AT })!;
+
+  it('lists the files a map names, never a deletion', () => {
+    expect(consolidatedFiles(map.content)).toEqual(['w/s/c.ts', 'w/s/a.ts', 'w/s/b.ts']);
+    expect(consolidatedFiles('Code map\n- x/y.ts (deleted)\n- x/z.ts')).toEqual(['x/z.ts']);
+  });
+
+  it('drops a changed file from the map and keeps the rest', () => {
+    const out = withoutConsolidatedFiles(map.content, ['W\\S\\A.ts'])!;
+    expect(out).not.toContain('w/s/a.ts');
+    expect(out).toContain('- w/s/c.ts (changed)');
+    expect(out).toContain('- w/s/b.ts');
+    expect(out.split('\n')[0]).toBe(map.content.split('\n')[0]);
+  });
+
+  it('returns null once no file is left', () => {
+    expect(withoutConsolidatedFiles(map.content, ['w/s/a.ts', 'w/s/b.ts', 'w/s/c.ts'])).toBeNull();
+  });
+
+  it('leaves the map as it was when nothing named is in it', () => {
+    expect(withoutConsolidatedFiles(map.content, ['other.ts'])).toBe(map.content);
+  });
+
+  it('reads a merged map the same way', () => {
+    const next = consolidate(snap({ edited: ['w/s/d.ts', 'w/s/e.ts', 'w/s/f.ts'] }), { at: AT })!;
+    expect(consolidatedFiles(mergeConsolidated(next.key, map.content, next.content))).toEqual([
+      'w/s/d.ts', 'w/s/e.ts', 'w/s/f.ts', 'w/s/c.ts', 'w/s/a.ts', 'w/s/b.ts',
+    ]);
+  });
+});
+
+describe('which maps a run is handed', () => {
+  const facts = [
+    { key: 'codemap:brain-embedded/src', content: 'wide' },
+    { key: 'learned:x', content: 'not a map' },
+    { key: 'codemap:brain-embedded/src/runStore', content: 'narrow' },
+    { key: 'codemap:api/src', content: 'elsewhere' },
+    { key: 'codemap:(root)', content: 'root' },
+  ];
+
+  it('keeps overlapping maps only, most specific first, capped', () => {
+    expect(consolidatedFactsFor(facts, ['brain-embedded/src/runStore']).map((f) => f.content)).toEqual(['narrow', 'wide']);
+    expect(consolidatedFactsFor(facts, ['brain-embedded/src/runStore'], 1).map((f) => f.content)).toEqual(['narrow']);
+    expect(consolidatedFactsFor(facts, ['(root)']).map((f) => f.content)).toEqual(['root']);
+    expect(consolidatedFactsFor(facts, [])).toEqual([]);
+  });
+
+  it('finds the areas a request names by word', () => {
+    const areas = facts.map((f) => consolidatedArea(f.key)).filter((a): a is string => !!a);
+    expect(areasNamedIn('the run store drops a steer', areas)).toEqual(['brain-embedded/src/runStore']);
+    expect(areasNamedIn('Why does runStore retry?', areas)).toEqual(['brain-embedded/src/runStore']);
+    expect(areasNamedIn('brain-embedded build is slow', areas)).toEqual(['brain-embedded/src/runStore', 'brain-embedded/src']);
+  });
+
+  it('never matches on a generic or short directory name', () => {
+    expect(areasNamedIn('fix the src api', ['api/src', 'web/src'])).toEqual([]);
+    expect(areasNamedIn('', ['api/src'])).toEqual([]);
+  });
+});

package/src/working/codemapAreas.ts

@@ -0,0 +1,142 @@
+/**
+ * Code-map RECALL — which `codemap:<area>` memories a run should be handed.
+ *
+ * {@link consolidate} writes one map per code area. A map only saves a search when the
+ * next run on that area is GIVEN it, so the read side lives here beside the write side,
+ * and every host (editor, cloud, on-prem) picks maps with the same rules:
+ *
+ *   - {@link areaOfPath} — the area a named file or directory belongs to. A file at the
+ *     repository root belongs to {@link CONSOLIDATED_ROOT_AREA}, the same area
+ *     {@link consolidate} files a root-only run under, so that map is reachable.
+ *   - {@link areasOfPathsIn} — the areas of the repo-relative paths a text names.
+ *   - {@link areasNamedIn} — the stored areas a request names by WORD ("fix the run
+ *     store" names `brain-embedded/src/runStore`), for a request that names no path.
+ *   - {@link consolidatedFactsFor} — the maps whose area overlaps the areas a run is
+ *     about, most specific first.
+ *
+ * Pure: no I/O.
+ */
+
+/** Key prefix every consolidated code map carries. */
+export const CONSOLIDATED_KEY_PREFIX = 'codemap:';
+/** The area of files at the repository root (`codemap:(root)`). */
+export const CONSOLIDATED_ROOT_AREA = '(root)';
+/** Maps a run is handed, at most. */
+export const MAX_RECALLED_MAPS = 6;
+
+/** Too generic to say which area a request is about: nearly every area has one. */
+const GENERIC_SEGMENTS: ReadonlySet<string> = new Set([
+  'src', 'lib', 'libs', 'app', 'apps', 'package', 'packages', 'component', 'components', 'util', 'utils',
+  'test', 'tests', 'index', 'main', 'core', 'common', 'shared', 'source', 'internal', 'client', 'clients',
+  'server', 'docs', 'scripts', 'public', 'assets',
+]);
+/** A word shorter than this matches too much to name an area. */
+const MIN_AREA_WORD = 4;
+/** Areas one request may name by word, at most. */
+const MAX_WORD_AREAS = 8;
+
+/**
+ * The area a repo-relative path belongs to: a file's directory, a directory itself (a
+ * path with no extension), and {@link CONSOLIDATED_ROOT_AREA} for a file at the root.
+ * `''` for an empty path.
+ */
+export function areaOfPath(p: string): string {
+  const norm = p.trim().replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '');
+  if (!norm) return '';
+  if (!/\.[A-Za-z][A-Za-z0-9]{0,7}$/.test(norm)) return norm;
+  const i = norm.lastIndexOf('/');
+  return i > 0 ? norm.slice(0, i) : CONSOLIDATED_ROOT_AREA;
+}
+
+/** The area a `codemap:` key is for, or undefined for any other key. */
+export function consolidatedArea(key: string): string | undefined {
+  return key.startsWith(CONSOLIDATED_KEY_PREFIX) ? key.slice(CONSOLIDATED_KEY_PREFIX.length) : undefined;
+}
+
+/** True when `area` and `dir` are the same directory or one contains the other. */
+function overlaps(area: string, dir: string): boolean {
+  return area === dir || dir.startsWith(`${area}/`) || area.startsWith(`${dir}/`);
+}
+
+/** The `codemap:` facts whose area overlaps a named area, most specific first, capped. */
+export function consolidatedFactsFor<F extends { key: string }>(
+  facts: readonly F[],
+  areas: readonly string[],
+  max: number = MAX_RECALLED_MAPS,
+): F[] {
+  if (areas.length === 0) return [];
+  const scored: Array<{ fact: F; depth: number }> = [];
+  const seen = new Set<string>();
+  for (const fact of facts) {
+    const area = consolidatedArea(fact.key);
+    if (area === undefined || seen.has(fact.key)) continue;
+    if (!areas.some((d) => overlaps(area, d))) continue;
+    seen.add(fact.key);
+    scored.push({ fact, depth: area.split('/').length });
+  }
+  return scored.sort((a, b) => b.depth - a.depth).slice(0, max).map((s) => s.fact);
+}
+
+/** A repo-relative path token: has a `/` or a file extension, and is not absolute. */
+const PATH_TOKEN = /[A-Za-z0-9_.@()\-\\/]+/g;
+/** Paths one text may name, at most. */
+const MAX_PATH_AREAS = 24;
+
+/**
+ * The areas of the repo-relative paths a text names (`api/src/run.ts` → `api/src`,
+ * `package.json` → the root area). Absolute paths are somebody else's machine and are
+ * skipped, as are URLs.
+ */
+export function areasOfPathsIn(text: string): string[] {
+  const out: string[] = [];
+  for (const raw of text.replace(/[a-z][a-z0-9+.-]*:\/\/\S+/gi, ' ').match(PATH_TOKEN) ?? []) {
+    // A drive letter (`C:`) is not part of a token, so `C:/x/y.ts` arrives as `/x/y.ts`
+    // and is skipped as absolute below.
+    const token = raw.replace(/^[(]+|[.)]+$/g, '');
+    if (!token || /^[\\/]/.test(token) || token.split(/[\\/]/).includes('..')) continue;
+    // A bare file name needs a stem of two or more characters, so `e.g` is not a file.
+    const isPath = /[\\/]/.test(token) || /^[^.]{2,}.*\.[A-Za-z][A-Za-z0-9]{0,7}$/.test(token);
+    if (!isPath) continue;
+    const area = areaOfPath(token);
+    if (area && !out.includes(area)) out.push(area);
+    if (out.length >= MAX_PATH_AREAS) break;
+  }
+  return out;
+}
+
+/** `runStore`, `run-store`, `run_store` and `run store` all read `runstore`. */
+function squash(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/** The request's words and adjacent pairs, squashed — `context pack` also reads `contextpack`. */
+function requestTerms(text: string): Set<string> {
+  const words = text
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+  const out = new Set<string>();
+  for (let i = 0; i < words.length; i++) {
+    out.add(words[i]!);
+    if (words[i]!.endsWith('s') && words[i]!.length > MIN_AREA_WORD) out.add(words[i]!.slice(0, -1));
+    if (i + 1 < words.length) out.add(words[i]! + words[i + 1]!);
+  }
+  return out;
+}
+
+/**
+ * The stored areas a request names by word: an area matches when one of its directory
+ * names (generic ones like `src` and short ones aside) is a word, or two adjacent words,
+ * of the request. Deepest areas first, capped.
+ */
+export function areasNamedIn(text: string, areas: readonly string[]): string[] {
+  const terms = requestTerms(text);
+  if (terms.size === 0) return [];
+  const hits = [...new Set(areas)].filter((area) =>
+    area.split('/').some((seg) => {
+      const s = squash(seg);
+      return s.length >= MIN_AREA_WORD && !GENERIC_SEGMENTS.has(s) && terms.has(s);
+    }));
+  return hits.sort((a, b) => b.split('/').length - a.split('/').length).slice(0, MAX_WORD_AREAS);
+}

package/src/working/consolidate.ts

@@ -10,15 +10,21 @@
  *
  * {@link mergeConsolidated} is the WRITE-side rule a keyed store applies, so a small run
  * ADDS to an area's map instead of overwriting the twelve files an earlier one found,
- * and a file this run deleted leaves the map.
+ * and a file this run deleted leaves the map. {@link consolidatedFiles} and
+ * {@link withoutConsolidatedFiles} read the stored format back, so a store can anchor a
+ * map to its files and drop one that changed since without hiding the rest.
  */
 
+import { CONSOLIDATED_KEY_PREFIX, CONSOLIDATED_ROOT_AREA } from './codemapAreas.js';
 import { rankByCount } from './rank.js';
 import type { ConsolidateOptions, ConsolidatedMemory, WorkingMemorySnapshot } from './types.js';
 
-/** Key prefix every consolidated code map carries. */
-export const CONSOLIDATED_KEY_PREFIX = 'codemap:';
-/** Fewer distinct files than this, with nothing changed, is a lookup — not a map worth keeping. */
+/**
+ * Fewer distinct files than this — changed, deleted and read together — is a lookup,
+ * not a map worth keeping. It holds for EVERY run, a run that changed files included: a
+ * one-file fix keyed to its own directory would otherwise write (or, once merged, keep
+ * re-dating) a map that tells the next run nothing a search would not.
+ */
 export const MIN_CONSOLIDATED_FILES = 3;
 const MAX_FILES = 12;
 const MIN_AREA_SEGMENTS = 2;
@@ -77,7 +83,7 @@ function dirSegments(file: string): string[] {
  */
 function areaOf(files: readonly string[]): string {
   const placed = files.map(dirSegments).filter((d) => d.length > 0);
-  if (placed.length === 0) return '(root)';
+  if (placed.length === 0) return CONSOLIDATED_ROOT_AREA;
   const prefixes = (depth: number): [string, number][] =>
     rankByCount(placed.filter((d) => d.length >= depth).map((d) => d.slice(0, depth).join('/')));
   for (let depth = MAX_AREA_SEGMENTS; depth >= MIN_AREA_SEGMENTS; depth--) {
@@ -107,8 +113,8 @@ export function consolidate(snapshot: WorkingMemorySnapshot, opts: ConsolidateOp
   const reads = rankByCount(kept(snapshot.read)).filter(([p]) => !changedSet.has(p) && !deletedSet.has(p));
   const readCounts = new Map(reads);
   const ranked = [...changed, ...reads.map(([p]) => p)];
+  if (ranked.length + deleted.length < (opts.minFiles ?? MIN_CONSOLIDATED_FILES)) return null;
   if (ranked.length === 0 && deleted.length === 0) return null;
-  if (changed.length === 0 && deleted.length === 0 && ranked.length < MIN_CONSOLIDATED_FILES) return null;
 
   const shown = ranked.slice(0, MAX_FILES);
   const area = areaOf(ranked.length > 0 ? ranked : deleted);
@@ -179,3 +185,31 @@ export function mergeConsolidated(key: string, prior: string | null | undefined,
   const more = merged.length - shown.length;
   return [...header, ...shown, ...(more > 0 ? [`(+${more} more file(s) touched)`] : [])].join('\n');
 }
+
+/** The files a stored map lists, in order — never a `(deleted)` line. */
+export function consolidatedFiles(content: string): string[] {
+  return entriesOf(content).filter((e) => e.note !== 'deleted').map((e) => e.path);
+}
+
+/** Paths compare as the store and the filesystem do: slashes normalised, case ignored. */
+function samePathKey(p: string): string {
+  return canonical(p).toLowerCase();
+}
+
+/**
+ * The map with `paths` taken out — for a store whose files changed since the map was
+ * written: the changed file's line goes, the rest of the map stays. `null` when no file
+ * is left to list, so the caller drops the map rather than serving a bare header.
+ */
+export function withoutConsolidatedFiles(content: string, paths: Iterable<string>): string | null {
+  const drop = new Set([...paths].map(samePathKey));
+  let left = 0;
+  const lines = content.split('\n').filter((line) => {
+    const m = ENTRY.exec(line);
+    if (!m) return true;
+    if (drop.has(samePathKey(m[1]!))) return false;
+    left++;
+    return true;
+  });
+  return left > 0 ? lines.join('\n') : null;
+}

package/src/working/index.ts

@@ -24,7 +24,24 @@
  */
 
 export { WorkingMemory } from './workingMemory.js';
-export { consolidate, mergeConsolidated, consolidatedKey, CONSOLIDATED_KEY_PREFIX, MIN_CONSOLIDATED_FILES } from './consolidate.js';
+export {
+  consolidate,
+  mergeConsolidated,
+  consolidatedKey,
+  consolidatedFiles,
+  withoutConsolidatedFiles,
+  MIN_CONSOLIDATED_FILES,
+} from './consolidate.js';
+export {
+  CONSOLIDATED_KEY_PREFIX,
+  CONSOLIDATED_ROOT_AREA,
+  MAX_RECALLED_MAPS,
+  areaOfPath,
+  areasNamedIn,
+  areasOfPathsIn,
+  consolidatedArea,
+  consolidatedFactsFor,
+} from './codemapAreas.js';
 export { rankByCount } from './rank.js';
 export type { Observation, WorkingMemorySnapshot, ConsolidatedMemory, ConsolidateOptions } from './types.js';
 export {