@seanhogg/builderforce-memory 2026.10.22 → 2026.10.24

package/src/working/working.test.ts

@@ -0,0 +1,120 @@
+/**
+ * src/working/working.test.ts
+ * Short-term working memory (the per-turn brief) and its consolidation into a long-term
+ * code map, including the write-side merge a keyed store applies.
+ */
+
+import { consolidate, mergeConsolidated, WorkingMemory, type WorkingMemorySnapshot } from './index.js';
+
+const AT = new Date('2026-10-24T12:00:00Z');
+
+function snap(partial: Partial<WorkingMemorySnapshot>): WorkingMemorySnapshot {
+  return { created: [], edited: [], deleted: [], read: [], searched: [], ...partial };
+}
+
+describe('WorkingMemory.brief', () => {
+  it('stays silent while the run is still short enough to see its own results', () => {
+    const m = new WorkingMemory();
+    for (let i = 0; i < 9; i++) m.observe({ kind: 'read', path: `a/${i}.ts` });
+    expect(m.brief()).toBeNull();
+  });
+
+  it('restates changes, reads with counts and searches once the run is long', () => {
+    const m = new WorkingMemory();
+    m.observe({ kind: 'searched', query: 'search_code "canvas"' });
+    m.observe({ kind: 'searched', query: 'search_code "canvas"' });
+    for (let i = 0; i < 6; i++) m.observe({ kind: 'read', path: 'web/src/App.tsx' });
+    m.observe({ kind: 'edited', path: 'web/src/Surface.tsx' });
+    m.observe({ kind: 'deleted', path: 'web/src/Old.tsx' });
+    const brief = m.brief()!;
+    expect(brief).toContain('## What this run has already established');
+    expect(brief).toContain('Changed:\n- web/src/Surface.tsx');
+    expect(brief).toContain('Deleted:\n- web/src/Old.tsx');
+    expect(brief).toContain('- web/src/App.tsx (6×)');
+    expect(brief).toContain('- search_code "canvas" (2×)');
+    // Verification is not discouraged.
+    expect(brief).toMatch(/re-running a search to verify an edit is fine/);
+  });
+
+  it('lets the host count its own activity toward the threshold', () => {
+    const m = new WorkingMemory();
+    m.observe({ kind: 'read', path: 'a.ts' });
+    expect(m.brief({ observations: 12 })).toContain('- a.ts');
+  });
+});
+
+describe('consolidate', () => {
+  it('keys by where most of the work was, ranks changed then most-read', () => {
+    const c = consolidate(
+      snap({
+        task: 'Move the   canvas',
+        read: ['web/src/a/x.ts', 'web/src/a/x.ts', 'web/src/a/y.ts'],
+        edited: ['web/src/a/z.ts', 'DONE.md'],
+      }),
+      { at: AT },
+    )!;
+    expect(c.key).toBe('codemap:web/src/a');
+    expect(c.content).toContain('mapped 2026-10-24 by a run asked: "Move the canvas"');
+    const entries = c.content.split('\n').filter((l) => l.startsWith('- '));
+    expect(entries).toEqual(['- web/src/a/z.ts (changed)', '- DONE.md (changed)', '- web/src/a/x.ts (read 2×)', '- web/src/a/y.ts']);
+  });
+
+  it('resolves absolute, MSYS and dotted paths against the root and drops noise', () => {
+    const c = consolidate(
+      snap({
+        read: [
+          'C:\\code\\repo\\web\\src\\a.ts',
+          '/c/code/repo/web/src/b.ts',
+          'web/./src//c.ts',
+          'web/node_modules/x.js',
+          'web/dist/out.js',
+          'pnpm-lock.yaml',
+          '/elsewhere/d.ts',
+          'scripts/build/gen.ts',
+        ],
+      }),
+      { at: AT, root: 'C:\\code\\repo' },
+    )!;
+    expect(c.key).toBe('codemap:web/src');
+    expect(c.content).toContain('- web/src/c.ts');
+    expect(c.content).toContain('- scripts/build/gen.ts');
+    expect(c.content).not.toMatch(/node_modules|dist|lock|elsewhere/);
+  });
+
+  it('skips a short lookup but keeps any change', () => {
+    expect(consolidate(snap({ read: ['a/b/c.ts', 'a/b/d.ts'] }))).toBeNull();
+    expect(consolidate(snap({ edited: ['api/src/r/x.ts'] }))?.key).toBe('codemap:api/src/r');
+  });
+});
+
+describe('mergeConsolidated', () => {
+  const prior = consolidate(snap({ read: ['w/s/a.ts', 'w/s/b.ts'], edited: ['w/s/c.ts'] }), { at: AT })!;
+
+  it('adds a small run to the area map, restating the earlier run\'s edits', () => {
+    const next = consolidate(snap({ task: 'fix d', edited: ['w/s/d.ts'] }), { at: AT })!;
+    const merged = mergeConsolidated(next.key, prior.content, next.content);
+    expect(merged).toContain('asked: "fix d"');
+    const entries = merged.split('\n').filter((l) => l.startsWith('- '));
+    expect(entries).toEqual(['- w/s/d.ts (changed)', '- w/s/c.ts (changed earlier)', '- w/s/a.ts', '- w/s/b.ts']);
+  });
+
+  it('removes a file this run deleted and never stores the deletion line', () => {
+    const next = consolidate(snap({ deleted: ['w/s/a.ts'], edited: ['w/s/e.ts'] }), { at: AT })!;
+    const merged = mergeConsolidated(next.key, prior.content, next.content);
+    expect(merged).not.toContain('w/s/a.ts');
+    expect(merged).not.toContain('(deleted)');
+    expect(mergeConsolidated(next.key, null, next.content)).not.toContain('(deleted)');
+  });
+
+  it('caps the map and says how many more', () => {
+    const big = consolidate(snap({ read: Array.from({ length: 12 }, (_, i) => `w/s/f${i}.ts`) }), { at: AT })!;
+    const next = consolidate(snap({ edited: ['w/s/new.ts'] }), { at: AT })!;
+    const merged = mergeConsolidated(next.key, big.content, next.content);
+    expect(merged.split('\n').filter((l) => l.startsWith('- '))).toHaveLength(12);
+    expect(merged).toContain('(+1 more file(s) touched)');
+  });
+
+  it('leaves every other key as sent', () => {
+    expect(mergeConsolidated('learned:x', 'old', 'new')).toBe('new');
+  });
+});

package/src/working/workingMemory.ts

@@ -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';
+import type { Observation, WorkingMemorySnapshot } from './types.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 {
+  private task: string | undefined;
+  private readonly created: string[] = [];
+  private readonly edited: string[] = [];
+  private readonly deleted: string[] = [];
+  private readonly read: string[] = [];
+  private readonly searched: string[] = [];
+  private observations = 0;
+
+  /** What the run was asked — the consolidation names it, so a map is a lesson, not a list. */
+  setTask(task: string): void {
+    const asked = task.replace(/\s+/g, ' ').trim();
+    if (asked) this.task = asked;
+  }
+
+  observe(o: Observation): void {
+    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(): number {
+    return this.observations;
+  }
+
+  get snapshot(): WorkingMemorySnapshot {
+    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: { observations?: number } = {}): string | null {
+    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');
+  }
+}