@cmetech/otto 1.1.1 → 1.2.4

package/packages/coworker-memory/src/errors.test.ts

@@ -0,0 +1,45 @@
+// packages/coworker-memory/src/errors.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  MemoryNotInitialized, BackendUnavailable, DrawerKindRejected,
+  LayerAWriteBlocked, RecallQueryMalformed, MemoryEntryMalformed,
+} from './errors.js';
+
+describe('memory errors', () => {
+  it('MemoryNotInitialized carries reason', () => {
+    const e = new MemoryNotInitialized('workspace.json corrupted');
+    assert.equal(e.name, 'MemoryNotInitialized');
+    assert.equal(e.reason, 'workspace.json corrupted');
+    assert.ok(e.message.includes('workspace.json corrupted'));
+  });
+  it('BackendUnavailable carries reason', () => {
+    const e = new BackendUnavailable('SQLITE_BUSY after retries');
+    assert.equal(e.name, 'BackendUnavailable');
+    assert.equal(e.reason, 'SQLITE_BUSY after retries');
+  });
+  it('DrawerKindRejected carries kind', () => {
+    const e = new DrawerKindRejected('mystery');
+    assert.equal(e.name, 'DrawerKindRejected');
+    assert.equal(e.kind, 'mystery');
+    assert.ok(e.message.includes('mystery'));
+  });
+  it('LayerAWriteBlocked carries secret_kind', () => {
+    const e = new LayerAWriteBlocked('anthropic_api_key');
+    assert.equal(e.name, 'LayerAWriteBlocked');
+    assert.equal(e.secretKind, 'anthropic_api_key');
+    assert.ok(e.message.includes('anthropic_api_key'));
+    assert.ok(e.message.includes('/connect'));
+  });
+  it('RecallQueryMalformed carries reason', () => {
+    const e = new RecallQueryMalformed('empty query');
+    assert.equal(e.name, 'RecallQueryMalformed');
+    assert.equal(e.reason, 'empty query');
+  });
+  it('MemoryEntryMalformed carries path', () => {
+    const e = new MemoryEntryMalformed('/tmp/profile.md', 'bad frontmatter');
+    assert.equal(e.name, 'MemoryEntryMalformed');
+    assert.equal(e.path, '/tmp/profile.md');
+    assert.equal(e.reason, 'bad frontmatter');
+  });
+});

package/packages/coworker-memory/src/errors.ts

@@ -0,0 +1,42 @@
+// packages/coworker-memory/src/errors.ts
+export class MemoryNotInitialized extends Error {
+  constructor(public readonly reason: string) {
+    super(`Memory not initialized: ${reason}. /memory status to inspect.`);
+    this.name = 'MemoryNotInitialized';
+  }
+}
+
+export class BackendUnavailable extends Error {
+  constructor(public readonly reason: string) {
+    super(`Memory backend unavailable: ${reason}.`);
+    this.name = 'BackendUnavailable';
+  }
+}
+
+export class DrawerKindRejected extends Error {
+  constructor(public readonly kind: string) {
+    super(`Drawer kind '${kind}' is not in v1 vocabulary. Allowed: turn, paste, file_load, ticket, email, rca, note.`);
+    this.name = 'DrawerKindRejected';
+  }
+}
+
+export class LayerAWriteBlocked extends Error {
+  constructor(public readonly secretKind: string) {
+    super(`Refused to store: contains secret-shaped value (kind: ${secretKind}). Remove the secret and retry. Vault entries should land in /connect, not memorize.`);
+    this.name = 'LayerAWriteBlocked';
+  }
+}
+
+export class RecallQueryMalformed extends Error {
+  constructor(public readonly reason: string) {
+    super(`Bad recall query: ${reason}.`);
+    this.name = 'RecallQueryMalformed';
+  }
+}
+
+export class MemoryEntryMalformed extends Error {
+  constructor(public readonly path: string, public readonly reason: string) {
+    super(`Layer A file ${path} is malformed: ${reason}. Move it aside and re-create.`);
+    this.name = 'MemoryEntryMalformed';
+  }
+}

package/packages/coworker-memory/src/index.test.ts

@@ -0,0 +1,21 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import * as memory from './index.js';
+
+describe('@otto/coworker-memory barrel', () => {
+  it('exports the key surface', () => {
+    assert.equal(typeof memory.LocalSqliteBackend, 'function');
+    assert.equal(typeof memory.LayerAStore, 'function');
+    assert.equal(typeof memory.MemoryRecorder, 'function');
+    assert.equal(typeof memory.resolveWorkspaceId, 'function');
+    assert.equal(typeof memory.resolveScope, 'function');
+    assert.equal(typeof memory.detectPaste, 'function');
+    assert.equal(typeof memory.formatRecall, 'function');
+    assert.equal(typeof memory.buildLayerAContext, 'function');
+    assert.equal(typeof memory.applyPersonaSeed, 'function');
+  });
+  it('exports error classes', () => {
+    assert.equal(typeof memory.LayerAWriteBlocked, 'function');
+    assert.equal(typeof memory.RecallQueryMalformed, 'function');
+  });
+});

package/packages/coworker-memory/src/index.ts

@@ -0,0 +1,12 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './memory-backend.js';
+export * from './workspace-id.js';
+export * from './scope-resolver.js';
+export * from './paste-detector.js';
+export * from './layer-a-store.js';
+export * from './local-sqlite-backend.js';
+export * from './memory-recorder.js';
+export * from './recall-formatter.js';
+export * from './context-injection.js';
+export * from './persona-seed.js';

package/packages/coworker-memory/src/layer-a-store.test.ts

@@ -0,0 +1,85 @@
+// packages/coworker-memory/src/layer-a-store.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AuditLog, SecretScanner } from '@otto/coworker-utils';
+import { LayerAStore } from './layer-a-store.js';
+import { LayerAWriteBlocked, MemoryEntryMalformed } from './errors.js';
+
+function ctx() {
+  const root = mkdtempSync(join(tmpdir(), 'la-'));
+  return {
+    root,
+    audit: new AuditLog({ path: join(root, 'audit.jsonl') }),
+    scanner: new SecretScanner(),
+    dir: join(root, 'memory'),
+  };
+}
+
+describe('LayerAStore', () => {
+  it('append lesson creates lessons.md with frontmatter and bullet', async () => {
+    const c = ctx();
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    await store.append({ kind: 'lesson', text: 'MTTR target is 30 minutes for P1', source: 'user', ts: '2026-06-02T10:00:00Z' });
+    const md = readFileSync(join(c.dir, 'lessons.md'), 'utf8');
+    assert.match(md, /^---\nschema_version: 1\n/);
+    assert.match(md, /- \(2026-06-02T10:00:00Z\) MTTR target is 30 minutes for P1/);
+  });
+  it('append profile uses timestamped section', async () => {
+    const c = ctx();
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    await store.append({ kind: 'profile', text: 'Prefers polars over pandas.', source: 'user', ts: '2026-06-02T10:00:00Z' });
+    const md = readFileSync(join(c.dir, 'profile.md'), 'utf8');
+    assert.match(md, /## 2026-06-02T10:00:00Z\nPrefers polars over pandas\./);
+  });
+  it('throws LayerAWriteBlocked when text contains a secret pattern', async () => {
+    const c = ctx();
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    await assert.rejects(
+      () => store.append({ kind: 'rule', text: 'use AKIAABCDEFGHIJKLMNOP', source: 'user', ts: '2026-06-02T10:00:00Z' }),
+      LayerAWriteBlocked,
+    );
+    assert.equal(existsSync(join(c.dir, 'rules.md')), false);
+  });
+  it('read returns parsed content with frontmatter stripped', async () => {
+    const c = ctx();
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    await store.append({ kind: 'rule', text: 'Always include MTTR in RCA.', source: 'user', ts: '2026-06-02T10:00:00Z' });
+    const body = await store.read('rule');
+    assert.match(body, /Always include MTTR in RCA\./);
+    assert.equal(body.startsWith('---'), false);
+  });
+  it('read returns empty string when file missing', async () => {
+    const c = ctx();
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    assert.equal(await store.read('lesson'), '');
+  });
+  it('emits write-layer-a audit on success', async () => {
+    const c = ctx();
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    await store.append({ kind: 'lesson', text: 'short lesson', source: 'user', ts: '2026-06-02T10:00:00Z' });
+    const rows: { action: string }[] = [];
+    for await (const r of c.audit.read({ producer: 'memory', action: 'write-layer-a' })) rows.push(r as never);
+    assert.equal(rows.length, 1);
+  });
+  it('re-appending to the same kind does not duplicate the title heading', async () => {
+    const c = ctx();
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    await store.append({ kind: 'lesson', text: 'first lesson', source: 'user', ts: '2026-06-02T10:00:00Z' });
+    await store.append({ kind: 'lesson', text: 'second lesson', source: 'user', ts: '2026-06-02T10:05:00Z' });
+    const raw = readFileSync(join(c.dir, 'lessons.md'), 'utf8');
+    const titleCount = (raw.match(/^# Lessons$/gm) ?? []).length;
+    assert.equal(titleCount, 1, 'duplicate title heading after re-append');
+    assert.match(raw, /first lesson/);
+    assert.match(raw, /second lesson/);
+  });
+  it('read throws MemoryEntryMalformed on unterminated frontmatter', async () => {
+    const c = ctx();
+    mkdirSync(c.dir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(c.dir, 'rules.md'), '---\nbroken-yaml: [\n', { mode: 0o600 });
+    const store = new LayerAStore({ scopeDir: c.dir, scope: 'workspace', audit: c.audit, scanner: c.scanner });
+    await assert.rejects(() => store.read('rule'), MemoryEntryMalformed);
+  });
+});

package/packages/coworker-memory/src/layer-a-store.ts

@@ -0,0 +1,88 @@
+// packages/coworker-memory/src/layer-a-store.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { AuditLog, SecretScanner } from '@otto/coworker-utils';
+import type { LayerAEntry, LayerAKind } from './types.js';
+import { LayerAWriteBlocked, MemoryEntryMalformed } from './errors.js';
+
+const FILE_FOR: Record<LayerAKind, string> = {
+  profile: 'profile.md',
+  rule: 'rules.md',
+  lesson: 'lessons.md',
+};
+
+const TITLE_FOR: Record<LayerAKind, string> = {
+  profile: 'Profile',
+  rule: 'Rules',
+  lesson: 'Lessons',
+};
+
+export interface LayerAStoreOptions {
+  scopeDir: string;             // absolute path to scope's memory dir
+  scope: 'global' | 'workspace';
+  audit: AuditLog;
+  scanner: SecretScanner;
+}
+
+export class LayerAStore {
+  constructor(private readonly opts: LayerAStoreOptions) {}
+
+  async append(entry: LayerAEntry): Promise<void> {
+    const hits = this.opts.scanner.scan(entry.text);
+    if (hits.length > 0) {
+      this.opts.audit.append({
+        _schema: 1, ts: new Date().toISOString(), producer: 'memory', action: 'block', severity: 'warn',
+        detail: { scope: this.opts.scope, kind: entry.kind, reason: 'secret', secret_kind: hits[0]!.kind },
+      });
+      throw new LayerAWriteBlocked(hits[0]!.kind);
+    }
+    mkdirSync(this.opts.scopeDir, { recursive: true, mode: 0o700 });
+    const path = join(this.opts.scopeDir, FILE_FOR[entry.kind]);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    const { body } = existing ? this.split(existing, path) : { body: '' };
+    const addition = entry.kind === 'lesson'
+      ? `- (${entry.ts}) ${entry.text}\n`
+      : `## ${entry.ts}\n${entry.text}\n\n`;
+    const newBody = (body && !body.endsWith('\n') ? body + '\n' : body) + addition;
+    const newFile = this.composeFile(entry.kind, newBody, entry.ts, entry.source);
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, newFile, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    this.opts.audit.append({
+      _schema: 1, ts: new Date().toISOString(), producer: 'memory', action: 'write-layer-a',
+      detail: { scope: this.opts.scope, kind: entry.kind, source: entry.source, byte_count: Buffer.byteLength(entry.text, 'utf8') },
+    });
+  }
+
+  async read(kind: LayerAKind): Promise<string> {
+    const path = join(this.opts.scopeDir, FILE_FOR[kind]);
+    if (!existsSync(path)) return '';
+    const raw = readFileSync(path, 'utf8');
+    const { body } = this.split(raw, path);
+    return body.trim();
+  }
+
+  private split(raw: string, path: string): { frontmatter: Record<string, unknown>; body: string } {
+    if (!raw.startsWith('---')) {
+      return { frontmatter: {}, body: raw };
+    }
+    const end = raw.indexOf('\n---\n', 4);
+    if (end < 0) throw new MemoryEntryMalformed(path, 'unterminated frontmatter');
+    try {
+      const fm = parseYaml(raw.slice(4, end)) as Record<string, unknown>;
+      const body = raw.slice(end + 5);
+      return { frontmatter: fm ?? {}, body };
+    } catch (err) {
+      throw new MemoryEntryMalformed(path, `frontmatter parse: ${(err as Error).message}`);
+    }
+  }
+
+  private composeFile(kind: LayerAKind, body: string, ts: string, source: LayerAEntry['source']): string {
+    const fm = { schema_version: 1, last_modified_at: ts, source };
+    const fmStr = stringifyYaml(fm).trimEnd();
+    const header = `---\n${fmStr}\n---\n\n# ${TITLE_FOR[kind]}\n\n`;
+    return header + body.replace(new RegExp(`^\\n?# ${TITLE_FOR[kind]}\\n\\n?`), '');
+  }
+}

package/packages/coworker-memory/src/local-sqlite-backend.test.ts

@@ -0,0 +1,110 @@
+// packages/coworker-memory/src/local-sqlite-backend.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { LocalSqliteBackend } from './local-sqlite-backend.js';
+
+function tmp(): string { return mkdtempSync(join(tmpdir(), 'lb-')); }
+
+describe('LocalSqliteBackend', () => {
+  it('bootstraps schema and is ready', async () => {
+    const dir = tmp();
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    const st = await be.status();
+    assert.equal(st.ready, true);
+    assert.equal(st.drawer_count, 0);
+    assert.equal(st.schema_version, 2);
+    await be.close();
+  });
+  it('retain + recall round-trip; result includes snippet with <mark>', async () => {
+    const dir = tmp();
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    await be.retain({ wing: 'global', room: 'inbox', kind: 'paste',
+      content: 'customer said the load balancer started returning 503s around 14:00 UTC',
+      metadata: {}, redacted: false });
+    const results = await be.recall({ query: 'load balancer' });
+    assert.equal(results.length, 1);
+    assert.equal(results[0]!.drawer.kind, 'paste');
+    assert.match(results[0]!.snippet, /<mark>load<\/mark>/);
+    assert.ok(results[0]!.score > 0);
+    await be.close();
+  });
+  it('filters by wing, room, kind, days_back', async () => {
+    const dir = tmp();
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    await be.retain({ wing: 'a', room: 'r1', kind: 'turn', content: 'red apples', metadata: {}, redacted: false });
+    await be.retain({ wing: 'b', room: 'r2', kind: 'paste', content: 'red apples', metadata: {}, redacted: false });
+    const filteredWing = await be.recall({ query: 'apples', wing: 'a' });
+    assert.equal(filteredWing.length, 1);
+    assert.equal(filteredWing[0]!.drawer.wing, 'a');
+    const filteredKind = await be.recall({ query: 'apples', kind: 'paste' });
+    assert.equal(filteredKind.length, 1);
+    assert.equal(filteredKind[0]!.drawer.kind, 'paste');
+    await be.close();
+  });
+  it('escapes FTS5 special characters in query', async () => {
+    const dir = tmp();
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    await be.retain({ wing: 'g', room: 'r', kind: 'note', content: 'CIDR is 10.0.0.0/24', metadata: {}, redacted: false });
+    const r = await be.recall({ query: '10.0.0.0/24 "AND" *' });   // would otherwise blow up
+    assert.equal(r.length, 1);
+    await be.close();
+  });
+  it('listWings + listRooms reflect inserted data', async () => {
+    const dir = tmp();
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    await be.retain({ wing: 'w1', room: 'r1', kind: 'turn', content: 'a', metadata: {}, redacted: false });
+    await be.retain({ wing: 'w2', room: 'r2', kind: 'turn', content: 'b', metadata: {}, redacted: false });
+    assert.deepEqual((await be.listWings()).sort(), ['w1', 'w2']);
+    assert.deepEqual(await be.listRooms('w1'), ['r1']);
+    await be.close();
+  });
+  it('clear({wing}) deletes only that wing\'s drawers', async () => {
+    const dir = tmp();
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    await be.retain({ wing: 'w1', room: 'r1', kind: 'turn', content: 'a', metadata: {}, redacted: false });
+    await be.retain({ wing: 'w2', room: 'r2', kind: 'turn', content: 'b', metadata: {}, redacted: false });
+    const out = await be.clear({ wing: 'w1', confirm: true });
+    assert.equal(out.deleted, 1);
+    assert.deepEqual(await be.listWings(), ['w2']);
+    await be.close();
+  });
+  it('retain preserves redacted flag', async () => {
+    const dir = tmp();
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    const d = await be.retain({ wing: 'g', room: 'r', kind: 'paste', content: 'x [REDACTED:aws_access_key_id] y', metadata: {}, redacted: true });
+    assert.equal(d.redacted, true);
+    const r = await be.recall({ query: 'REDACTED' });
+    assert.equal(r[0]!.drawer.redacted, true);
+    await be.close();
+  });
+});
+
+describe('Local backend migrations (Phase 4 Task 8)', () => {
+  it('migration 002 lets us insert kind:artifact', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'be-mig-'));
+    const be = new LocalSqliteBackend({ dbPath: join(dir, 'layer-b.db') });
+    await be.open();
+    const st = await be.status();
+    assert.equal(st.schema_version, 2);
+    const drawer = await be.retain({
+      wing: 'g', room: 'r', kind: 'artifact',
+      content: JSON.stringify({ slug: 'rca-1', kind: 'report', uri: 'artifact://rca-1' }),
+      metadata: { scratchpad: 'p1' }, redacted: false,
+    });
+    assert.equal(drawer.kind, 'artifact');
+    const r = await be.recall({ query: 'rca', kind: 'artifact' });
+    assert.equal(r.length, 1);
+    assert.equal(r[0]!.drawer.kind, 'artifact');
+    await be.close();
+  });
+});

package/packages/coworker-memory/src/local-sqlite-backend.ts

@@ -0,0 +1,185 @@
+// packages/coworker-memory/src/local-sqlite-backend.ts
+import Database, { type Database as DB } from 'better-sqlite3';
+import { readFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { v4 as uuid } from 'uuid';
+import type { MemoryBackend } from './memory-backend.js';
+import type { Drawer, RecallQuery, RecallResult, BackendStatus, Wing, Room } from './types.js';
+import { RecallQueryMalformed, BackendUnavailable } from './errors.js';
+
+export interface LocalSqliteBackendOptions {
+  dbPath: string;
+  now?: () => string;
+  busyTimeoutMs?: number;
+}
+
+function migrationDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), 'migrations');
+}
+
+function escapeFts5(q: string): string {
+  // Wrap each word containing special chars in double quotes; doubled internal quotes.
+  // Empty query → throw upstream.
+  const tokens = q.match(/\S+/g) ?? [];
+  return tokens.map(t => `"${t.replace(/"/g, '""')}"`).join(' OR ');
+}
+
+export class LocalSqliteBackend implements MemoryBackend {
+  private db: DB | null = null;
+  private readonly path: string;
+  private readonly now: () => string;
+  private readonly busyTimeoutMs: number;
+
+  constructor(opts: LocalSqliteBackendOptions) {
+    this.path = opts.dbPath;
+    this.now = opts.now ?? (() => new Date().toISOString());
+    this.busyTimeoutMs = opts.busyTimeoutMs ?? 2000;
+  }
+
+  async open(): Promise<void> {
+    if (this.db) return;
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    try {
+      this.db = new Database(this.path);
+      this.db.pragma(`busy_timeout = ${this.busyTimeoutMs}`);
+      const dir = migrationDir();
+      const migrations = [
+        { version: 1, file: '001-init.sql' },
+        { version: 2, file: '002-artifact-kind.sql' },
+      ];
+      const userVersion = this.db.pragma('user_version', { simple: true }) as number;
+      for (const m of migrations) {
+        if (userVersion < m.version) {
+          const sql = readFileSync(join(dir, m.file), 'utf8');
+          this.db.exec(sql);
+        }
+      }
+    } catch (err) {
+      throw new BackendUnavailable(`open failed: ${(err as Error).message}`);
+    }
+  }
+
+  async close(): Promise<void> {
+    this.db?.close();
+    this.db = null;
+  }
+
+  private requireDb(): DB {
+    if (!this.db) throw new BackendUnavailable('not opened');
+    return this.db;
+  }
+
+  async retain(input: Omit<Drawer, 'id' | 'created_at'>): Promise<Drawer> {
+    const db = this.requireDb();
+    const id = uuid();
+    const created_at = this.now();
+    const stmt = db.prepare(`
+      INSERT INTO drawers (id, wing, room, kind, content, metadata_json, parent_id, redacted, created_at)
+      VALUES (@id, @wing, @room, @kind, @content, @metadata_json, @parent_id, @redacted, @created_at)
+    `);
+    stmt.run({
+      id, wing: input.wing, room: input.room, kind: input.kind, content: input.content,
+      metadata_json: JSON.stringify(input.metadata ?? {}),
+      parent_id: input.parent_id ?? null,
+      redacted: input.redacted ? 1 : 0,
+      created_at,
+    });
+    return { id, created_at, ...input };
+  }
+
+  async recall(query: RecallQuery): Promise<RecallResult[]> {
+    if (!query.query || !query.query.trim()) throw new RecallQueryMalformed('empty query');
+    const db = this.requireDb();
+    const matchExpr = escapeFts5(query.query.trim());
+    const conditions: string[] = ['drawers_fts MATCH ?'];
+    const params: unknown[] = [matchExpr];
+
+    if (query.wing) {
+      if (Array.isArray(query.wing)) {
+        conditions.push(`d.wing IN (${query.wing.map(() => '?').join(',')})`);
+        params.push(...query.wing);
+      } else {
+        conditions.push('d.wing = ?');
+        params.push(query.wing);
+      }
+    }
+    if (query.room) { conditions.push('d.room = ?'); params.push(query.room); }
+    if (query.kind) {
+      const kinds = Array.isArray(query.kind) ? query.kind : [query.kind];
+      conditions.push(`d.kind IN (${kinds.map(() => '?').join(',')})`);
+      params.push(...kinds);
+    }
+    if (query.days_back && query.days_back > 0) {
+      const cutoff = new Date(Date.now() - query.days_back * 86400_000).toISOString();
+      conditions.push('d.created_at >= ?');
+      params.push(cutoff);
+    }
+    const limit = Math.min(Math.max(query.max_results ?? 8, 1), 64);
+    params.push(limit);
+
+    const sql = `
+      SELECT d.id, d.wing, d.room, d.kind, d.content, d.metadata_json, d.parent_id, d.redacted, d.created_at,
+             bm25(drawers_fts) AS rank,
+             snippet(drawers_fts, 0, '<mark>', '</mark>', '...', 16) AS snippet
+      FROM drawers_fts
+      JOIN drawers d ON d.rowid = drawers_fts.rowid
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY rank
+      LIMIT ?
+    `;
+    const rows = db.prepare(sql).all(...params) as Array<{
+      id: string; wing: string; room: string; kind: Drawer['kind']; content: string;
+      metadata_json: string; parent_id: string | null; redacted: number; created_at: string;
+      rank: number; snippet: string;
+    }>;
+    return rows.map(r => ({
+      drawer: {
+        id: r.id, wing: r.wing, room: r.room, kind: r.kind, content: r.content,
+        metadata: JSON.parse(r.metadata_json) as Record<string, unknown>,
+        parent_id: r.parent_id ?? undefined, redacted: r.redacted === 1,
+        created_at: r.created_at,
+      },
+      score: -r.rank, // BM25 lower=better in sqlite; invert for descending
+      snippet: r.snippet,
+    }));
+  }
+
+  async listRooms(wing?: Wing): Promise<Room[]> {
+    const db = this.requireDb();
+    const sql = wing
+      ? `SELECT DISTINCT room FROM drawers WHERE wing = ? ORDER BY room`
+      : `SELECT DISTINCT room FROM drawers ORDER BY room`;
+    const rows = wing ? db.prepare(sql).all(wing) : db.prepare(sql).all();
+    return (rows as Array<{ room: string }>).map(r => r.room);
+  }
+
+  async listWings(): Promise<Wing[]> {
+    const db = this.requireDb();
+    const rows = db.prepare(`SELECT DISTINCT wing FROM drawers ORDER BY wing`).all() as Array<{ wing: string }>;
+    return rows.map(r => r.wing);
+  }
+
+  async status(): Promise<BackendStatus> {
+    const db = this.requireDb();
+    const { c } = db.prepare(`SELECT COUNT(*) AS c FROM drawers`).get() as { c: number };
+    const { user_version } = db.prepare(`PRAGMA user_version`).get() as { user_version: number };
+    return {
+      ready: true,
+      workspace_wing: '',  // caller (memory-singleton) overlays this from scope info
+      drawer_count: c,
+      layer_b_db_path: this.path,
+      schema_version: user_version,
+    };
+  }
+
+  async clear(args: { wing?: Wing; confirm: true }): Promise<{ deleted: number }> {
+    if (args.confirm !== true) throw new RecallQueryMalformed('confirm must be true');
+    const db = this.requireDb();
+    const stmt = args.wing
+      ? db.prepare(`DELETE FROM drawers WHERE wing = ?`)
+      : db.prepare(`DELETE FROM drawers`);
+    const result = args.wing ? stmt.run(args.wing) : stmt.run();
+    return { deleted: result.changes };
+  }
+}

package/packages/coworker-memory/src/memory-backend.ts

@@ -0,0 +1,10 @@
+import type { Drawer, RecallQuery, RecallResult, BackendStatus, Wing, Room } from './types.js';
+
+export interface MemoryBackend {
+  recall(query: RecallQuery): Promise<RecallResult[]>;
+  retain(input: Omit<Drawer, 'id' | 'created_at'>): Promise<Drawer>;
+  listRooms(wing?: Wing): Promise<Room[]>;
+  listWings(): Promise<Wing[]>;
+  status(): Promise<BackendStatus>;
+  clear(args: { wing?: Wing; confirm: true }): Promise<{ deleted: number }>;
+}