@seanhogg/builderforce-memory 2026.10.23 → 2026.10.24

package/dist/working/workingMemory.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Short-term memory for one run: what it has read, searched and changed so far.
+ *
+ * ## Why the brief exists
+ *
+ * A model's reasoning is stripped from the transcript it reads next (models copy
+ * reasoning markup instead of calling tools), and a bounded working window compacts old
+ * tool results away. So by turn forty a run cannot see what it concluded at turn ten,
+ * and re-derives the whole architecture in every turn's reasoning — measured: 8–10k
+ * completion tokens a turn for two tool calls each, the same files re-read a dozen
+ * times. {@link WorkingMemory.brief} is the run's own record, handed to EVERY turn on
+ * that request only (never into the transcript, so it neither grows history nor breaks
+ * prompt caching), so the model reasons from "here is what I have" instead of from
+ * scratch.
+ *
+ * Record SUCCESSFUL observations only: a memory claiming a file was written when the
+ * write failed grounds every later turn — and run — on a lie.
+ */
+import type { Observation, WorkingMemorySnapshot } from './types.js';
+export declare class WorkingMemory {
+    private task;
+    private readonly created;
+    private readonly edited;
+    private readonly deleted;
+    private readonly read;
+    private readonly searched;
+    private observations;
+    /** What the run was asked — the consolidation names it, so a map is a lesson, not a list. */
+    setTask(task: string): void;
+    observe(o: Observation): void;
+    /** Observations recorded so far (searches and file events alike). */
+    get size(): number;
+    get snapshot(): WorkingMemorySnapshot;
+    /**
+     * What this run has ALREADY established, to put in front of its next turn — or `null`
+     * until it has done enough for a restatement to be worth its tokens. `observations`
+     * lets a host count its own activity (every tool call, not only memory-relevant ones).
+     * Hosts deliver it inside the per-request volatile tail (`/handoff` `volatileTail`), so
+     * it never becomes the cached prefix nor "the latest user directive".
+     */
+    brief(opts?: {
+        observations?: number;
+    }): string | null;
+}
+//# sourceMappingURL=workingMemory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workingMemory.d.ts","sourceRoot":"","sources":["../../src/working/workingMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAUrE,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,YAAY,CAAK;IAEzB,6FAA6F;IAC7F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK3B,OAAO,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI;IAW7B,qEAAqE;IACrE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,QAAQ,IAAI,qBAAqB,CASpC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,MAAM,GAAG,IAAI;CAuB3D"}

package/dist/working/workingMemory.js

@@ -0,0 +1,103 @@
+/**
+ * Short-term memory for one run: what it has read, searched and changed so far.
+ *
+ * ## Why the brief exists
+ *
+ * A model's reasoning is stripped from the transcript it reads next (models copy
+ * reasoning markup instead of calling tools), and a bounded working window compacts old
+ * tool results away. So by turn forty a run cannot see what it concluded at turn ten,
+ * and re-derives the whole architecture in every turn's reasoning — measured: 8–10k
+ * completion tokens a turn for two tool calls each, the same files re-read a dozen
+ * times. {@link WorkingMemory.brief} is the run's own record, handed to EVERY turn on
+ * that request only (never into the transcript, so it neither grows history nor breaks
+ * prompt caching), so the model reasons from "here is what I have" instead of from
+ * scratch.
+ *
+ * Record SUCCESSFUL observations only: a memory claiming a file was written when the
+ * write failed grounds every later turn — and run — on a lie.
+ */
+import { rankByCount } from './rank.js';
+/**
+ * Below this many observations the run's own results are still in its window, so a
+ * restatement only costs tokens. Past it, compaction starts dropping them.
+ */
+const BRIEF_MIN_OBSERVATIONS = 10;
+const BRIEF_MAX_FILES = 25;
+const BRIEF_MAX_SEARCHES = 15;
+export class WorkingMemory {
+    task;
+    created = [];
+    edited = [];
+    deleted = [];
+    read = [];
+    searched = [];
+    observations = 0;
+    /** What the run was asked — the consolidation names it, so a map is a lesson, not a list. */
+    setTask(task) {
+        const asked = task.replace(/\s+/g, ' ').trim();
+        if (asked)
+            this.task = asked;
+    }
+    observe(o) {
+        this.observations++;
+        if (o.kind === 'searched') {
+            if (o.query.trim())
+                this.searched.push(o.query.trim());
+            return;
+        }
+        const p = o.path.trim();
+        if (!p)
+            return;
+        this[o.kind].push(p);
+    }
+    /** Observations recorded so far (searches and file events alike). */
+    get size() {
+        return this.observations;
+    }
+    get snapshot() {
+        return {
+            ...(this.task ? { task: this.task } : {}),
+            created: this.created,
+            edited: this.edited,
+            deleted: this.deleted,
+            read: this.read,
+            searched: this.searched,
+        };
+    }
+    /**
+     * What this run has ALREADY established, to put in front of its next turn — or `null`
+     * until it has done enough for a restatement to be worth its tokens. `observations`
+     * lets a host count its own activity (every tool call, not only memory-relevant ones).
+     * Hosts deliver it inside the per-request volatile tail (`/handoff` `volatileTail`), so
+     * it never becomes the cached prefix nor "the latest user directive".
+     */
+    brief(opts = {}) {
+        if ((opts.observations ?? this.observations) < BRIEF_MIN_OBSERVATIONS)
+            return null;
+        const changed = [...new Set([...this.created, ...this.edited])];
+        const changedSet = new Set(changed);
+        const deleted = [...new Set(this.deleted)];
+        const reads = rankByCount(this.read).filter(([p]) => !changedSet.has(p));
+        const searches = rankByCount(this.searched);
+        if (changed.length === 0 && deleted.length === 0 && reads.length === 0 && searches.length === 0)
+            return null;
+        const lines = [
+            '## What this run has already established',
+            'Your own record so far, kept by the runtime — not a new request. Build on it instead of re-deriving it: earlier results may have been compressed out of your context, but what you concluded from them still holds. Re-read a file only when it may have changed since (a command rewrote it) or you need a part you have not seen; re-running a search to verify an edit is fine. If you already know where the change goes, make it.',
+        ];
+        if (changed.length)
+            lines.push('', 'Changed:', ...changed.slice(0, BRIEF_MAX_FILES).map((p) => `- ${p}`));
+        if (deleted.length)
+            lines.push('', 'Deleted:', ...deleted.slice(0, BRIEF_MAX_FILES).map((p) => `- ${p}`));
+        if (reads.length) {
+            lines.push('', 'Read:', ...reads.slice(0, BRIEF_MAX_FILES).map(([p, n]) => `- ${p}${n > 1 ? ` (${n}×)` : ''}`));
+            if (reads.length > BRIEF_MAX_FILES)
+                lines.push(`- … ${reads.length - BRIEF_MAX_FILES} more`);
+        }
+        if (searches.length) {
+            lines.push('', 'Searched:', ...searches.slice(0, BRIEF_MAX_SEARCHES).map(([s, n]) => `- ${s}${n > 1 ? ` (${n}×)` : ''}`));
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=workingMemory.js.map

package/dist/working/workingMemory.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.10.23",
+  "version": "2026.10.24",
   "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.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -22,6 +22,10 @@
       "types": "./dist/handoff/index.d.ts",
       "import": "./dist/handoff/index.js"
     },
+    "./working": {
+      "types": "./dist/working/index.d.ts",
+      "import": "./dist/working/index.js"
+    },
     "./distillation": {
       "types": "./dist/distillation/index.d.ts",
       "import": "./dist/distillation/index.js"
@@ -99,7 +103,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.10.23"
+    "@seanhogg/builderforce-memory-engine": "^2026.10.24"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -113,7 +117,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.23"
+    "@seanhogg/builderforce-memory-engine": "2026.10.24"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/handoff/handoff.test.ts

@@ -6,7 +6,7 @@
  * the irreducible core overflows.
  */
 
-import { handoffBudget, packHandoff, type HandoffMessage, type HandoffPack } from './index.js';
+import { handoffBudget, packHandoff, volatileTail, isVolatileTail, type HandoffMessage, type HandoffPack } from './index.js';
 
 /** A message costing exactly 14 tokens under the default estimate (40 chars / 4 + 4). */
 function msg(role: HandoffMessage['role'], tag: string): HandoffMessage {
@@ -272,3 +272,30 @@ describe('packHandoff', () => {
     expect(exact.dropped).toBe(2);
   });
 });
+
+describe('the volatile tail', () => {
+  const SYS = msg('system', 'sys');
+  const TASK = msg('user', 'the real request');
+
+  it('builds one tagged message, or none for empty sections', () => {
+    expect(volatileTail(['', null, undefined])).toBeNull();
+    const tail = volatileTail(['brief', 'budget line'])!;
+    expect(isVolatileTail(tail)).toBe(true);
+    expect(tail.content).toBe('<run-state>\nbrief\n\nbudget line\n</run-state>');
+  });
+
+  it('is never taken for the directive — the real request survives and the tail stays last', async () => {
+    const tail = volatileTail(['x'.repeat(20)])!;
+    const messages: HandoffMessage[] = [SYS, TASK, msg('assistant', 'a1'), msg('user', 'u2'), msg('assistant', 'a2'), msg('assistant', 'a3'), tail];
+    const pack = await packHandoff({ messages, targetContextTokens: 90, reserveOutputTokens: 0 });
+    expect(pack.messages[pack.messages.length - 1]).toBe(tail);
+    expect(pack.messages.some((m) => m === messages[3])).toBe(true);
+    expect(pack.messages.filter(isVolatileTail)).toHaveLength(1);
+  });
+
+  it('is what goes when the history needs the whole budget', async () => {
+    const tail = volatileTail(['y'.repeat(400)])!;
+    const pack = await packHandoff({ messages: [SYS, TASK, tail], targetContextTokens: 40, reserveOutputTokens: 0 });
+    expect(pack.messages).toEqual([SYS, TASK]);
+  });
+});

package/src/handoff/index.ts

@@ -15,6 +15,7 @@
 export { packHandoff } from './pack.js';
 export { handoffBudget, defaultEstimateTokens, messageTokens, tokensOf } from './budget.js';
 export { handoffLine, elisionMarker } from './note.js';
+export { VOLATILE_TAIL_TAG, volatileTail, isVolatileTail, isVolatileContent } from './volatile.js';
 export type {
   HandoffMessage,
   HandoffPackInput,

package/src/handoff/pack.ts

@@ -27,6 +27,7 @@ import { defaultEstimateTokens, handoffBudget, messageTokens, tokensOf } from '.
 import { buildNote, composeNote, elisionMarker, handoffLine, noteTokens } from './note.js';
 import { segmentTranscript, type Segment } from './segments.js';
 import type { HandoffMessage, HandoffPack, HandoffPackInput, TokenEstimator } from './types.js';
+import { isVolatileTail } from './volatile.js';
 
 interface Tail {
   /** Index in the non-system transcript where the verbatim tail begins. */
@@ -46,12 +47,19 @@ function noteRole(next: HandoffMessage | undefined): 'user' | 'assistant' {
   return next === undefined || next.role === 'assistant' ? 'user' : 'assistant';
 }
 
-/** Index of the last `user` message, or -1. */
+/** Index of the last `user` message that is a real directive (never a volatile tail), or -1. */
 function latestDirectiveIndex(convo: readonly HandoffMessage[]): number {
-  for (let i = convo.length - 1; i >= 0; i--) if (convo[i]!.role === 'user') return i;
+  for (let i = convo.length - 1; i >= 0; i--) if (convo[i]!.role === 'user' && !isVolatileTail(convo[i]!)) return i;
   return -1;
 }
 
+/** Where the trailing run of volatile tails begins (`messages.length` when there is none). */
+function trailingVolatileStart(messages: readonly HandoffMessage[]): number {
+  let i = messages.length;
+  while (i > 0 && isVolatileTail(messages[i - 1]!)) i -= 1;
+  return i;
+}
+
 /** Convo indices the caller pinned (pinnable roles only), excluding the directive. */
 function pinnedIndices(
   convo: readonly HandoffMessage[],
@@ -119,9 +127,27 @@ function result(
 export async function packHandoff(input: HandoffPackInput): Promise<HandoffPack> {
   const estimate = input.estimateTokens ?? defaultEstimateTokens;
   const budget = handoffBudget(input);
-  const all = input.messages;
-
   // Under budget: hand the transcript over untouched.
+  if (tokensOf(input.messages, estimate) <= budget) return result(input.messages.slice(), 0, estimate);
+
+  // The volatile tail (`volatile.ts`) is set aside, the history packed into what is
+  // left, and the tail put back LAST — never the directive, never in the middle. When
+  // the history needs the whole budget, the tail is what goes: it is a per-turn aid,
+  // the history is the work.
+  const cut = trailingVolatileStart(input.messages);
+  const volatile = input.messages.slice(cut);
+  const volatileTokens = tokensOf(volatile, estimate);
+  if (volatile.length > 0) {
+    const history = input.messages.slice(0, cut);
+    const withTail = await packHistory({ ...input, messages: history }, budget - volatileTokens, estimate);
+    if (withTail.fits) return result([...withTail.messages, ...volatile], withTail.dropped, estimate, withTail);
+    return packHistory({ ...input, messages: history }, budget, estimate);
+  }
+  return packHistory(input, budget, estimate);
+}
+
+async function packHistory(input: HandoffPackInput, budget: number, estimate: TokenEstimator): Promise<HandoffPack> {
+  const all = input.messages;
   if (tokensOf(all, estimate) <= budget) return result(all.slice(), 0, estimate);
 
   const prefixLen = leadingSystemCount(all);

package/src/handoff/volatile.ts

@@ -0,0 +1,46 @@
+/**
+ * The per-request VOLATILE tail — everything that changes turn to turn (the run's
+ * working-memory brief, the affect block, the budget line, task state) in ONE `user`
+ * message appended AFTER the history and opened by {@link VOLATILE_TAIL_TAG}.
+ *
+ * Two readers depend on that one convention, which is why it lives here and every host
+ * builds its tail with {@link volatileTail}:
+ *
+ *   - The gateway's prompt caching places the history breakpoint BEFORE a tagged block,
+ *     so a tail that changes every turn never becomes the cached prefix. An untagged
+ *     trailing block is where the breakpoint lands — and then every turn re-bills the
+ *     whole transcript.
+ *   - {@link packHandoff} never treats a tagged block as "the latest user directive"
+ *     and keeps it LAST: an untagged one would be protected in place of the user's real
+ *     request, which could then be dropped into the summarised middle.
+ *
+ * A trailing user turn is valid after a tool-result turn on both the OpenAI and the
+ * Anthropic shape (Anthropic merges it into the tool_result user turn). It is built per
+ * request and never persisted into a transcript.
+ */
+
+import type { HandoffMessage } from './types.js';
+
+export const VOLATILE_TAIL_TAG = '<run-state>';
+const VOLATILE_TAIL_CLOSE = '</run-state>';
+
+/** True when `content` (a string or a content-part array) opens with the tag. */
+export function isVolatileContent(content: unknown): boolean {
+  if (typeof content === 'string') return content.startsWith(VOLATILE_TAIL_TAG);
+  if (Array.isArray(content)) {
+    const first = content[0] as { text?: unknown } | undefined;
+    return typeof first?.text === 'string' && first.text.startsWith(VOLATILE_TAIL_TAG);
+  }
+  return false;
+}
+
+/** True for a `user` message that is a volatile tail. */
+export function isVolatileTail(message: Pick<HandoffMessage, 'role' | 'content'>): boolean {
+  return message.role === 'user' && isVolatileContent(message.content);
+}
+
+/** The ONE tail message for these sections, or null when every section is empty. */
+export function volatileTail(sections: readonly (string | null | undefined)[]): { role: 'user'; content: string } | null {
+  const body = sections.map((s) => (s ?? '').trim()).filter(Boolean).join('\n\n');
+  return body ? { role: 'user', content: `${VOLATILE_TAIL_TAG}\n${body}\n${VOLATILE_TAIL_CLOSE}` } : null;
+}

package/src/working/consolidate.ts

@@ -0,0 +1,181 @@
+/**
+ * Consolidation — what survives a run, as ONE long-term memory per code AREA.
+ *
+ * A run that spends ninety turns locating the code behind a feature leaves with that
+ * knowledge in its transcript and nowhere else, so the next run asked about the same
+ * area repeats the whole search. {@link consolidate} turns the run's working memory
+ * into a map — the files that mattered, changed first, then reads ranked by how much
+ * the run leaned on them — under a key per area (the directory most of them share).
+ * Deterministic: built from what the run actually opened, it cannot invent a path.
+ *
+ * {@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.
+ */
+
+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. */
+export const MIN_CONSOLIDATED_FILES = 3;
+const MAX_FILES = 12;
+const MIN_AREA_SEGMENTS = 2;
+const MAX_AREA_SEGMENTS = 4;
+const MAX_TASK_CHARS = 200;
+const MAX_KEY_CHARS = 255;
+/** Dependencies, build output and the knowledge tree itself — never "where the code is". */
+const NOISE_SEGMENTS: ReadonlySet<string> = new Set(['node_modules', 'dist', '.next', '.turbo', 'coverage', '.git', '.builderforce']);
+const NOISE_FILES: ReadonlySet<string> = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb']);
+
+const DRIVE = /^[a-z]:\//i;
+/** MSYS / Git-Bash spelling of a drive path: `/c/code/x` ≡ `C:/code/x`. */
+const MSYS_DRIVE = /^\/([a-z])\//i;
+
+function canonical(raw: string): string {
+  let p = raw.trim().replace(/\\/g, '/');
+  const msys = MSYS_DRIVE.exec(p);
+  if (msys) p = `${msys[1]}:/${p.slice(3)}`;
+  // Collapse `a//b` and `a/./b`; leading `./` too.
+  p = p.replace(/\/{2,}/g, '/').replace(/(^|\/)(\.\/)+/g, '$1');
+  return p;
+}
+
+/**
+ * A repo-relative path, or undefined when the path is not a repo file worth mapping:
+ * outside the root (or absolute with no root to resolve it against), escaping with
+ * `..`, dependencies or build output, or a lockfile. Drive paths compare
+ * case-insensitively, as the filesystem does.
+ */
+function repoPath(raw: string, root?: string): string | undefined {
+  let p = canonical(raw);
+  if (p.startsWith('/') || DRIVE.test(p)) {
+    const base = root ? canonical(root).replace(/\/+$/, '') : '';
+    if (!base || base === '/') return undefined;
+    const under = DRIVE.test(base) ? p.toLowerCase().startsWith(`${base.toLowerCase()}/`) : p.startsWith(`${base}/`);
+    if (!under) return undefined;
+    p = p.slice(base.length + 1);
+  }
+  const segs = p.split('/');
+  if (!p || segs.includes('..')) return undefined;
+  if (segs.some((s) => NOISE_SEGMENTS.has(s)) || NOISE_FILES.has(segs[segs.length - 1]!)) return undefined;
+  return p;
+}
+
+function dirSegments(file: string): string[] {
+  const parts = file.split('/');
+  parts.pop();
+  return parts;
+}
+
+/**
+ * The area a set of files belongs to: the DEEPEST directory (to a bounded depth, so
+ * keys stay stable from run to run) holding a majority of them, else the depth-2
+ * directory holding the most. Root-level files (DONE.md, package.json — touched by
+ * many unrelated runs) never decide it.
+ */
+function areaOf(files: readonly string[]): string {
+  const placed = files.map(dirSegments).filter((d) => d.length > 0);
+  if (placed.length === 0) return '(root)';
+  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--) {
+    const [top] = prefixes(depth);
+    if (top && top[1] * 2 > placed.length) return top[0];
+  }
+  return prefixes(MIN_AREA_SEGMENTS)[0]?.[0] ?? prefixes(1)[0]![0];
+}
+
+/** The key for an area — stable across runs, so consolidations of one area meet in one memory. */
+export function consolidatedKey(area: string): string {
+  return `${CONSOLIDATED_KEY_PREFIX}${area}`.slice(0, MAX_KEY_CHARS);
+}
+
+/**
+ * The long-term memory for one finished run, or `null` when the run touched too little
+ * to be worth keeping. Files the run deleted are carried as `(deleted)` lines, which
+ * {@link mergeConsolidated} applies as removals and never stores.
+ */
+export function consolidate(snapshot: WorkingMemorySnapshot, opts: ConsolidateOptions = {}): ConsolidatedMemory | null {
+  const keep = (raw: string): string | undefined => repoPath(raw, opts.root);
+  const kept = (list: readonly string[]): string[] => list.map(keep).filter((p): p is string => !!p);
+  const deleted = [...new Set(kept(snapshot.deleted))];
+  const deletedSet = new Set(deleted);
+  const changed = [...new Set(kept([...snapshot.created, ...snapshot.edited]))].filter((p) => !deletedSet.has(p));
+  const changedSet = new Set(changed);
+  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 === 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);
+  const at = (opts.at ?? new Date()).toISOString().slice(0, 10);
+  const asked = (snapshot.task ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_TASK_CHARS);
+  const lines = [
+    `Code map for \`${area}\` (mapped ${at}${asked ? ` by a run asked: "${asked}"` : ''}).`,
+    'Open these first instead of searching:',
+    ...shown.map((p) => {
+      if (changedSet.has(p)) return `- ${p} (changed)`;
+      const n = readCounts.get(p) ?? 1;
+      return `- ${p}${n > 1 ? ` (read ${n}×)` : ''}`;
+    }),
+    ...deleted.map((p) => `- ${p} (deleted)`),
+  ];
+  if (ranked.length > shown.length) lines.push(`(+${ranked.length - shown.length} more file(s) touched)`);
+  return { key: consolidatedKey(area), content: lines.join('\n') };
+}
+
+/** `- <path> (<note>)` — the path is everything before the trailing parenthesised note. */
+const ENTRY = /^- (.+?)(?: \(([^()]*)\))?$/;
+const MORE = /^\(\+\d+ more file\(s\) touched\)$/;
+
+interface Entry { path: string; note: string | undefined }
+
+function entriesOf(content: string): Entry[] {
+  const out: Entry[] = [];
+  for (const line of content.split('\n')) {
+    const m = ENTRY.exec(line);
+    if (m) out.push({ path: m[1]!, note: m[2] });
+  }
+  return out;
+}
+
+function render(e: Entry): string {
+  return `- ${e.path}${e.note ? ` (${e.note})` : ''}`;
+}
+
+/**
+ * The content to STORE when a consolidated map lands on a key that already holds one:
+ * the new run's entries first, then the earlier map's entries it did not touch (an
+ * earlier run's `changed` is restated as `changed earlier`, so this run is not credited
+ * with edits it never made), minus every file this run deleted, capped. Any other key,
+ * or no prior, stores `next` without its `(deleted)` lines.
+ *
+ * The STORE decides whether `prior` is still live — pass it only when the stored memory
+ * has not expired or been superseded, or a retired map comes back to life.
+ */
+export function mergeConsolidated(key: string, prior: string | null | undefined, next: string): string {
+  if (!key.startsWith(CONSOLIDATED_KEY_PREFIX)) return next;
+  const nextLines = next.split('\n');
+  const header = nextLines.filter((l) => !ENTRY.test(l) && !MORE.test(l));
+  const fresh = entriesOf(next);
+  const removed = new Set(fresh.filter((e) => e.note === 'deleted').map((e) => e.path));
+  const seen = new Set<string>(removed);
+  const merged: string[] = [];
+  for (const e of fresh) {
+    if (seen.has(e.path)) continue;
+    seen.add(e.path);
+    merged.push(render(e));
+  }
+  for (const e of prior?.trim() ? entriesOf(prior) : []) {
+    if (seen.has(e.path) || e.note === 'deleted') continue;
+    seen.add(e.path);
+    merged.push(render(e.note === 'changed' ? { ...e, note: 'changed earlier' } : e));
+  }
+  const shown = merged.slice(0, MAX_FILES);
+  const more = merged.length - shown.length;
+  return [...header, ...shown, ...(more > 0 ? [`(+${more} more file(s) touched)`] : [])].join('\n');
+}

package/src/working/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Working memory — the `@seanhogg/builderforce-memory/working` subpath.
+ *
+ * A run has two memories, and they do different jobs:
+ *
+ *   - SHORT-TERM: {@link WorkingMemory}, what THIS run has read, searched and changed.
+ *     Restated before every turn ({@link WorkingMemory.brief}), because a model's own
+ *     reasoning is not carried into its next turn and old tool results are compacted
+ *     out of its window — without it a long run re-derives the codebase every turn.
+ *   - LONG-TERM: {@link consolidate}, what survives the run — a map of where the code
+ *     for that area lives, keyed per area so the next run on it (any surface) opens the
+ *     right files first. {@link mergeConsolidated} is the write-side rule that makes
+ *     consolidations of one area accumulate instead of overwriting each other.
+ *
+ * The memory knows observations ("read this file", "changed that one"), never tool
+ * names — a host maps its own tool vocabulary onto {@link Observation}.
+ *
+ * Pure: no `node:*`, no I/O — runs in a Cloudflare Worker, a browser page and Node alike.
+ */
+
+export { WorkingMemory } from './workingMemory.js';
+export { consolidate, mergeConsolidated, consolidatedKey, CONSOLIDATED_KEY_PREFIX, MIN_CONSOLIDATED_FILES } from './consolidate.js';
+export { rankByCount } from './rank.js';
+export type { Observation, WorkingMemorySnapshot, ConsolidatedMemory, ConsolidateOptions } from './types.js';

package/src/working/rank.ts

@@ -0,0 +1,10 @@
+/**
+ * Each distinct item with how often it occurs, most frequent first, ties by name — the
+ * one ranking the brief, the consolidation and its area all use (and that hosts reuse
+ * for their own renderings of a run, so a run reads the same everywhere).
+ */
+export function rankByCount(items: readonly string[]): [string, number][] {
+  const counts = new Map<string, number>();
+  for (const i of items) counts.set(i, (counts.get(i) ?? 0) + 1);
+  return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+}

package/src/working/types.ts

@@ -0,0 +1,32 @@
+/**
+ * The working-memory contract — pure data, so the subpath stays Worker/browser/Node safe.
+ */
+
+/** One thing a run did that is worth remembering, in the memory's own terms. */
+export type Observation =
+  | { kind: 'read' | 'created' | 'edited' | 'deleted'; path: string }
+  | { kind: 'searched'; query: string };
+
+/** What a run's working memory holds. Lists keep duplicates — how often is a signal. */
+export interface WorkingMemorySnapshot {
+  /** What the run was asked. */
+  task?: string;
+  created: readonly string[];
+  edited: readonly string[];
+  deleted: readonly string[];
+  read: readonly string[];
+  searched: readonly string[];
+}
+
+/** One long-term memory, ready for a keyed store: the same key replaces (or merges). */
+export interface ConsolidatedMemory {
+  key: string;
+  content: string;
+}
+
+export interface ConsolidateOptions {
+  /** Dates the memory so a reader can judge its age. */
+  at?: Date;
+  /** The workspace root — absolute paths under it are kept, made relative. */
+  root?: string;
+}