@0xmaxma/claude-gateway 1.6.9 → 1.7.0

package/dist/ui/web-ui.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":";;AAIA,sDAq4BC;AAQD,8CAiFC;AAl+BD;;;GAGG;AACH,SAAgB,qBAAqB;IACnC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAm4BD,CAAC;AACT,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,cAAc,GAAG,EAAE;IACnD,MAAM,UAAU,GAAG,cAAc;SAC9B,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9F,+EAA+E;IAC/E,8EAA8E;IAC9E,MAAM,SAAS,GAAG,UAAU;QAC1B,CAAC,CAAC;uBACiB,UAAU,QAAQ;QACrC,CAAC,CAAC;;;;;;;YAOM,CAAC;IACX,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCP,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA6BH,CAAC;AACT,CAAC"}
+{"version":3,"file":"web-ui.js","sourceRoot":"","sources":["../../src/ui/web-ui.ts"],"names":[],"mappings":"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"}

package/mcp/package.json

@@ -4,7 +4,8 @@
   "type": "module",
   "bin": "./server.ts",
   "scripts": {
-    "start": "bun install --no-summary && bun server.ts"
+    "start": "bun install --no-summary && bun server.ts",
+    "test": "bun test"
   },
   "dependencies": {
     "@line/bot-sdk": "^11.0.2",

package/mcp/server.ts

@@ -23,6 +23,7 @@ import { ImageModule } from './tools/image/module';
 import { ShareImageModule } from './tools/share-image/module';
 import { AppsModule } from './tools/apps/module';
 import { ApiModule } from './tools/api/module';
+import { MemoryModule } from './tools/memory/module';
 import { buildChannelInstructions } from './instructions';
 import type { ChannelModule, ToolModule, McpToolDefinition } from './types';
 
@@ -46,6 +47,7 @@ const modules: AnyModule[] = [
   new ShareImageModule(),
   new AppsModule(),
   new ApiModule(),
+  new MemoryModule(),
 ];
 
 // Build tool-to-module mapping for enabled modules

package/mcp/tools/memory/archive-reader.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Bun tests for the knowledge-archive read path (planning-64 K1).
+ *
+ * Runs under Bun (`bun test`) because the reader uses `bun:sqlite` — the Node
+ * jest suite cannot load this module. The fixture DB is built with bun:sqlite
+ * using the SAME schema src/ writes under node:sqlite (external-content FTS5 +
+ * provenance/recall), so this exercises the real query path end to end.
+ */
+
+import { test, expect } from 'bun:test';
+import { Database } from 'bun:sqlite';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { searchArchive, getExcerpt, isMemoryScopedPath, archiveDbPath, sharedDbPathFromEnv, mergeHits } from './archive-reader';
+
+// Build a temp agent dir with a kb.sqlite carrying the given chunks.
+function mkAgentWithArchive(
+  chunks: Array<{ id: string; path: string; start: number; end: number; text: string; origin?: string; importance?: number }>,
+): { agentDir: string; workspaceDir: string; dbPath: string } {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(workspaceDir, { recursive: true });
+  const dbPath = archiveDbPath(workspaceDir); // agentDir/kb.sqlite
+
+  const db = new Database(dbPath);
+  db.exec('PRAGMA foreign_keys=ON');
+  db.exec(`
+    CREATE TABLE kb_chunks (rowid_id INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT UNIQUE, path TEXT,
+      start_line INTEGER, end_line INTEGER, text TEXT, updated_at INTEGER);
+    CREATE TABLE kb_chunk_recall (chunk_id TEXT PRIMARY KEY, importance INTEGER, triggers TEXT, project_key TEXT,
+      FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE);
+    CREATE TABLE kb_chunk_provenance (chunk_id TEXT PRIMARY KEY, origin_class TEXT, session_kind TEXT,
+      observed_at INTEGER, supersedes_key TEXT, FOREIGN KEY (chunk_id) REFERENCES kb_chunks(id) ON DELETE CASCADE);
+    CREATE VIRTUAL TABLE kb_chunks_fts USING fts5(text, content='kb_chunks', content_rowid='rowid_id');
+    CREATE TRIGGER kb_chunks_ai AFTER INSERT ON kb_chunks BEGIN
+      INSERT INTO kb_chunks_fts(rowid, text) VALUES (new.rowid_id, new.text);
+    END;
+  `);
+  const ins = db.prepare('INSERT INTO kb_chunks(id,path,start_line,end_line,text,updated_at) VALUES(?,?,?,?,?,?)');
+  const insR = db.prepare('INSERT INTO kb_chunk_recall(chunk_id,importance) VALUES(?,?)');
+  const insP = db.prepare('INSERT INTO kb_chunk_provenance(chunk_id,origin_class,session_kind,observed_at) VALUES(?,?,?,?)');
+  for (const c of chunks) {
+    ins.run(c.id, c.path, c.start, c.end, c.text, 1);
+    insR.run(c.id, c.importance ?? null);
+    insP.run(c.id, c.origin ?? 'agent', 'unknown', 1);
+  }
+  db.close();
+  return { agentDir, workspaceDir, dbPath };
+}
+
+test('isMemoryScopedPath: accepts memory-scoped, rejects traversal/abs/out-of-scope', () => {
+  expect(isMemoryScopedPath('MEMORY.md')).toBe(true);
+  expect(isMemoryScopedPath('USER.md')).toBe(true);
+  expect(isMemoryScopedPath('memory/foo.md')).toBe(true);
+  expect(isMemoryScopedPath('memory/sub/bar.md')).toBe(true);
+  expect(isMemoryScopedPath('../secret.md')).toBe(false);
+  // The discriminating case: ends in .md AND starts with memory/, so ONLY the
+  // ".." guard rejects it — proves that guard is load-bearing.
+  expect(isMemoryScopedPath('memory/../secret.md')).toBe(false);
+  expect(isMemoryScopedPath('memory/../../etc/passwd')).toBe(false);
+  expect(isMemoryScopedPath('/etc/passwd')).toBe(false);
+  expect(isMemoryScopedPath('notes/random.md')).toBe(false);
+  expect(isMemoryScopedPath('AGENTS.md')).toBe(false);
+});
+
+test('searchArchive: FTS match returns ranked hit with provenance + importance', () => {
+  const { workspaceDir, agentDir } = mkAgentWithArchive([
+    { id: 'memory/getpod.md#1-1', path: 'memory/getpod.md', start: 1, end: 1, text: 'Getpod ingress returns 401 before the gateway', origin: 'agent', importance: 7 },
+    { id: 'memory/apps.md#1-1', path: 'memory/apps.md', start: 1, end: 1, text: 'apps router mounts under gateway-router', origin: 'agent' },
+  ]);
+  try {
+    const hits = searchArchive(archiveDbPath(workspaceDir), 'ingress 401', 6);
+    expect(hits.length).toBe(1);
+    expect(hits[0].path).toBe('memory/getpod.md');
+    expect(hits[0].originClass).toBe('agent');
+    expect(hits[0].importance).toBe(7);
+    expect(hits[0].startLine).toBe(1);
+    expect(typeof hits[0].score).toBe('number');
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+// Regression (#351): a kb.sqlite built before the planning-66 `entry_hash`
+// column (exactly what `mkAgentWithArchive` produces) must not crash the read
+// path with `no such column: entry_hash`. searchArchive heals the column in
+// place and returns hits with entryHash=null. Proven to throw on pre-fix code.
+test('searchArchive: DB missing entry_hash column does not throw and heals it', () => {
+  const { workspaceDir, agentDir } = mkAgentWithArchive([
+    { id: 'memory/x.md#1-1', path: 'memory/x.md', start: 1, end: 1, text: 'ingress 401 token mismatch', origin: 'agent' },
+  ]);
+  const dbPath = archiveDbPath(workspaceDir);
+  const cols = (dbPath: string): string[] => {
+    const d = new Database(dbPath, { readonly: true });
+    try {
+      return (d.query(`PRAGMA table_info(kb_chunks)`).all() as Array<{ name: string }>).map((c) => c.name);
+    } finally {
+      d.close();
+    }
+  };
+  try {
+    // Precondition: the pre-#346 fixture genuinely lacks the column.
+    expect(cols(dbPath)).not.toContain('entry_hash');
+
+    let hits: ReturnType<typeof searchArchive> = [];
+    expect(() => {
+      hits = searchArchive(dbPath, 'ingress 401', 6);
+    }).not.toThrow();
+    expect(hits.length).toBe(1);
+    expect(hits[0].path).toBe('memory/x.md');
+    expect(hits[0].entryHash).toBeNull();
+
+    // The read path healed the DB in place so subsequent writers/readers are safe.
+    expect(cols(dbPath)).toContain('entry_hash');
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('searchArchive: missing DB → [], empty/punctuation query → []', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(workspaceDir, { recursive: true });
+  try {
+    expect(searchArchive(archiveDbPath(workspaceDir), 'anything', 6)).toEqual([]); // no kb.sqlite
+    const { workspaceDir: ws2, agentDir: dir2 } = mkAgentWithArchive([
+      { id: 'm#1-1', path: 'memory/a.md', start: 1, end: 1, text: 'hello world' },
+    ]);
+    expect(searchArchive(archiveDbPath(ws2), '   !!! ', 6)).toEqual([]); // no usable tokens
+    fs.rmSync(dir2, { recursive: true, force: true });
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('getExcerpt: bounded line range; out-of-scope/missing → null', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(path.join(workspaceDir, 'memory'), { recursive: true });
+  fs.writeFileSync(path.join(workspaceDir, 'memory/note.md'), 'l1\nl2\nl3\nl4\nl5');
+  try {
+    const ex = getExcerpt(workspaceDir, 'memory/note.md', 2, 2);
+    expect(ex).not.toBeNull();
+    expect(ex!.text).toBe('l2\nl3');
+    expect(ex!.from).toBe(2);
+    expect(ex!.to).toBe(3);
+    expect(ex!.totalLines).toBe(5);
+    expect(ex!.truncated).toBe(true);
+
+    // Whole file → not truncated.
+    expect(getExcerpt(workspaceDir, 'memory/note.md', 1, 100)!.truncated).toBe(false);
+    // Out-of-scope path and missing file → null.
+    expect(getExcerpt(workspaceDir, '../secret.md', 1, 5)).toBeNull();
+    expect(getExcerpt(workspaceDir, 'memory/missing.md', 1, 5)).toBeNull();
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});
+
+test('sharedDbPathFromEnv: null when unset, <dir>/kb.sqlite when set (K3 corpus:shared)', () => {
+  const prev = process.env.GATEWAY_SHARED_KB_DIR;
+  try {
+    delete process.env.GATEWAY_SHARED_KB_DIR;
+    expect(sharedDbPathFromEnv()).toBeNull();
+    process.env.GATEWAY_SHARED_KB_DIR = '   ';
+    expect(sharedDbPathFromEnv()).toBeNull(); // blank → disabled
+    process.env.GATEWAY_SHARED_KB_DIR = '/tmp/shared/kb/global';
+    expect(sharedDbPathFromEnv()).toBe('/tmp/shared/kb/global/kb.sqlite');
+  } finally {
+    if (prev === undefined) delete process.env.GATEWAY_SHARED_KB_DIR;
+    else process.env.GATEWAY_SHARED_KB_DIR = prev;
+  }
+});
+
+test('mergeHits: round-robin interleave (bm25 not comparable across corpora), capped', () => {
+  const mk = (path: string, score: number) => ({
+    path, startLine: 1, endLine: 1, score, snippet: path, originClass: 'agent', importance: null,
+  });
+  // Each list is already best-first within its own corpus. A cross-corpus numeric
+  // sort would mix incomparable bm25 scales; interleave a,c,b instead (personal
+  // first each round), capped at the limit.
+  const merged = mergeHits([mk('a', -0.9), mk('b', -0.1)], [mk('c', -0.5), mk('d', -0.05)], 3);
+  expect(merged.map((h) => h.path)).toEqual(['a', 'c', 'b']);
+});
+
+test('mergeHits: interleave preserves per-corpus order even when scales differ', () => {
+  const mk = (path: string, score: number) => ({
+    path, startLine: 1, endLine: 1, score, snippet: path, originClass: 'agent', importance: null,
+  });
+  // Shared scores numerically "better" (more negative) must NOT starve the personal
+  // corpus — round-robin gives p1, s1, p2, s2.
+  const merged = mergeHits([mk('p1', -0.2), mk('p2', -0.05)], [mk('s1', -9), mk('s2', -8)], 4);
+  expect(merged.map((h) => h.path)).toEqual(['p1', 's1', 'p2', 's2']);
+});
+
+test('getExcerpt: a symlink inside memory/ escaping the workspace is refused', () => {
+  const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb1-'));
+  const workspaceDir = path.join(agentDir, 'workspace');
+  fs.mkdirSync(path.join(workspaceDir, 'memory'), { recursive: true });
+  // A secret target OUTSIDE the workspace, and a memory/ symlink pointing at it.
+  const secret = path.join(agentDir, 'outside-secret.md');
+  fs.writeFileSync(secret, 'TOPSECRET outside the workspace');
+  fs.symlinkSync(secret, path.join(workspaceDir, 'memory', 'evil.md'));
+  try {
+    // Passes the string scope check (memory/*.md) but realpath escapes the ws → null.
+    expect(getExcerpt(workspaceDir, 'memory/evil.md', 1, 5)).toBeNull();
+  } finally {
+    fs.rmSync(agentDir, { recursive: true, force: true });
+  }
+});

package/mcp/tools/memory/archive-reader.ts

@@ -0,0 +1,253 @@
+/**
+ * Read-only reader for the per-agent knowledge archive (planning-64 K1).
+ *
+ * The archive `kb.sqlite` is BUILT by src/ under Node via `node:sqlite`
+ * (src/agent/knowledge). These MCP tools run under **Bun**, which has no
+ * `node:sqlite`, so the read path here uses **`bun:sqlite`** instead. Same
+ * on-disk SQLite/FTS5 file — verified that node:sqlite writes and bun:sqlite
+ * reads it back via `bm25()`. This is a deliberate, read-only mirror of the
+ * query half of `src/agent/knowledge/archive-db.ts`; keep the two in sync.
+ */
+
+import { Database } from 'bun:sqlite';
+import * as fs from 'fs';
+import * as path from 'path';
+import { recordRetrievalHits } from './retrieval-recorder';
+
+export interface SearchHit {
+  path: string;
+  startLine: number;
+  endLine: number;
+  score: number; // bm25 (lower = more relevant); surfaced for transparency
+  snippet: string;
+  originClass: string | null;
+  importance: number | null;
+  /** Stable archive-entry identity (planning-66); null outside any entry block. */
+  entryHash: string | null;
+}
+
+/** Archive DB path for an agent: sibling of history.db at agents/<id>/kb.sqlite. */
+export function archiveDbPath(workspaceDir: string): string {
+  return path.join(path.dirname(workspaceDir), 'kb.sqlite');
+}
+
+/**
+ * Shared, cross-agent vault DB path from the gateway-provided env
+ * (`GATEWAY_SHARED_KB_DIR` = the resolved <root>/<project> dir), or null when
+ * shared KB is disabled / not configured (planning-64 K3).
+ */
+export function sharedDbPathFromEnv(): string | null {
+  const dir = process.env.GATEWAY_SHARED_KB_DIR;
+  if (!dir || !dir.trim()) return null;
+  return path.join(dir, 'kb.sqlite');
+}
+
+/**
+ * Merge hit lists (per-agent + shared), keeping the best `limit`. bm25 scores are
+ * corpus-relative — the value depends on each index's term/document statistics —
+ * so scores from two independent FTS indexes are NOT on a comparable scale and a
+ * global sort can spuriously rank one corpus over the other. Each list is already
+ * sorted best-first within its own corpus, so interleave them round-robin for a
+ * fair blend instead of a cross-corpus numeric sort.
+ */
+export function mergeHits<T extends SearchHit>(a: T[], b: T[], limit: number): T[] {
+  const out: T[] = [];
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max && out.length < limit; i++) {
+    if (i < a.length) out.push(a[i]);
+    if (out.length < limit && i < b.length) out.push(b[i]);
+  }
+  return out;
+}
+
+/** Build an FTS5 MATCH string: quote each token so punctuation can't inject syntax. */
+function toFtsMatch(query: string): string {
+  return query
+    .split(/[^\p{L}\p{N}_]+/u)
+    .filter(Boolean)
+    .map((t) => `"${t.replace(/"/g, '""')}"`)
+    .join(' ');
+}
+
+/**
+ * Keyword search over the archive (FTS5 BM25). Returns [] when the index does
+ * not exist yet or the query has no usable tokens. Read-only; never creates a DB.
+ *
+ * When `recordRetrievals` is set (planning-66), each returned entry's stable
+ * `entry_hash` is appended to `kb_retrieval_log` through a SEPARATE, dedicated
+ * writable handle AFTER the results are built — append-only and fire-and-forget,
+ * so the read path never read-modify-writes chunk rows and never blocks/locks the
+ * search response. The Node side folds this log into per-entry recency at GC time.
+ */
+/** True when kb_chunks carries the planning-66 `entry_hash` column. */
+function hasEntryHashColumn(db: Database): boolean {
+  const cols = db.query(`PRAGMA table_info(kb_chunks)`).all() as Array<{ name: string }>;
+  return cols.some((c) => c.name === 'entry_hash');
+}
+
+/**
+ * Idempotent, best-effort heal for a pre-#346 archive DB. The `entry_hash`
+ * column is only added by the writer (`ArchiveDb` constructor migration); a
+ * `kb.sqlite` that has not been reindexed since #346 still lacks it, so the
+ * read-only search query below crashes with `no such column: entry_hash`. Add
+ * the column in place via a short writable handle (mirroring the recall-logging
+ * handle further down). A read-only filesystem simply skips — the column-aware
+ * query then falls back to a NULL `entryHash` so search still returns hits.
+ */
+function ensureEntryHashColumn(dbPath: string): void {
+  try {
+    const w = new Database(dbPath);
+    try {
+      w.exec('PRAGMA busy_timeout=2000');
+      if (!hasEntryHashColumn(w)) {
+        w.exec(`ALTER TABLE kb_chunks ADD COLUMN entry_hash TEXT`);
+        w.exec(`CREATE INDEX IF NOT EXISTS idx_kb_chunks_entry_hash ON kb_chunks(entry_hash)`);
+      }
+    } finally {
+      w.close();
+    }
+  } catch {
+    /* read-only / locked DB — the column-aware query below degrades gracefully */
+  }
+}
+
+export function searchArchive(
+  dbPath: string,
+  query: string,
+  maxResults: number,
+  opts?: { recordRetrievals?: boolean; now?: number },
+): SearchHit[] {
+  if (!fs.existsSync(dbPath)) return [];
+  const match = toFtsMatch(query);
+  if (!match) return [];
+
+  // Heal pre-#346 DBs in place so the query never crashes on a missing column.
+  ensureEntryHashColumn(dbPath);
+
+  const db = new Database(dbPath, { readonly: true });
+  // If the heal above could not run (read-only FS), select a NULL entry_hash
+  // rather than referencing a column that does not exist.
+  const entryHashSelect = hasEntryHashColumn(db) ? 'c.entry_hash' : 'NULL';
+  let hits: SearchHit[];
+  try {
+    const rows = db
+      .query(
+        `SELECT c.id AS id, c.path AS path, c.start_line AS startLine, c.end_line AS endLine,
+                c.text AS text, ${entryHashSelect} AS entryHash, bm25(kb_chunks_fts) AS score,
+                p.origin_class AS originClass, r.importance AS importance
+         FROM kb_chunks_fts f
+         JOIN kb_chunks c ON c.rowid_id = f.rowid
+         LEFT JOIN kb_chunk_provenance p ON p.chunk_id = c.id
+         LEFT JOIN kb_chunk_recall r ON r.chunk_id = c.id
+         WHERE kb_chunks_fts MATCH ?
+         ORDER BY bm25(kb_chunks_fts)
+         LIMIT ?`,
+      )
+      .all(match, maxResults) as Array<{
+      path: string;
+      startLine: number;
+      endLine: number;
+      text: string;
+      entryHash: string | null;
+      score: number;
+      originClass: string | null;
+      importance: number | null;
+    }>;
+    hits = rows.map((r) => ({
+      path: r.path,
+      startLine: r.startLine,
+      endLine: r.endLine,
+      score: r.score,
+      snippet: r.text.length > 500 ? `${r.text.slice(0, 500)}…` : r.text,
+      originClass: r.originClass,
+      importance: r.importance,
+      entryHash: r.entryHash,
+    }));
+  } finally {
+    db.close();
+  }
+
+  // Recall counter (planning-66): fire-and-forget, append-only, best-effort. A
+  // dedicated writable handle (WAL + busy_timeout so it never fails a concurrent
+  // reindex) logs the retrieved entries AFTER the read handle is closed. Any error
+  // is swallowed inside recordRetrievalHits — telemetry never fails a search.
+  if (opts?.recordRetrievals && hits.length > 0) {
+    try {
+      const w = new Database(dbPath);
+      try {
+        w.exec('PRAGMA busy_timeout=2000');
+        recordRetrievalHits(
+          { run: (sql, params = []) => void w.query(sql).run(...(params as never[])) },
+          hits.map((h) => h.entryHash),
+          opts.now ?? Date.now(),
+        );
+      } finally {
+        w.close();
+      }
+    } catch {
+      /* best-effort telemetry — never affect the search response */
+    }
+  }
+  return hits;
+}
+
+/** A memory-scoped path: MEMORY.md, USER.md, or memory/**.md — no traversal. */
+export function isMemoryScopedPath(relPath: string): boolean {
+  const p = relPath.replace(/\\/g, '/');
+  if (p.includes('..') || path.isAbsolute(p)) return false;
+  if (p === 'MEMORY.md' || p === 'USER.md') return true;
+  return p.startsWith('memory/') && p.endsWith('.md');
+}
+
+export interface Excerpt {
+  path: string;
+  from: number;
+  to: number;
+  text: string;
+  totalLines: number;
+  truncated: boolean;
+}
+
+/**
+ * Bounded exact excerpt of a memory file by line range (1-indexed). Reads the
+ * file directly (it is the source of truth). Returns null for an out-of-scope
+ * path or a missing file.
+ */
+export function getExcerpt(
+  workspaceDir: string,
+  relPath: string,
+  from = 1,
+  lines = 200,
+): Excerpt | null {
+  // Validate and read the SAME normalized path so the check can't diverge from
+  // what is actually opened.
+  const rel = relPath.replace(/\\/g, '/');
+  if (!isMemoryScopedPath(rel)) return null;
+  const abs = path.join(workspaceDir, rel);
+  if (!fs.existsSync(abs)) return null;
+  // Containment against symlink escape: a memory/x.md symlink pointing outside
+  // the workspace passes the string check but must not be readable through the
+  // tool. Resolve real paths and require the target stays under the workspace.
+  try {
+    const realBase = fs.realpathSync(workspaceDir);
+    const realTarget = fs.realpathSync(abs);
+    if (realTarget !== realBase && !realTarget.startsWith(realBase + path.sep)) return null;
+  } catch {
+    return null; // realpath failed (broken symlink, race) → refuse
+  }
+
+  const all = fs.readFileSync(abs, 'utf8').split('\n');
+  const total = all.length;
+  const start = Math.max(1, Math.floor(from));
+  const count = Math.max(1, Math.floor(lines));
+  const end = Math.min(total, start + count - 1);
+  const slice = start > total ? [] : all.slice(start - 1, end);
+  return {
+    path: relPath,
+    from: start,
+    to: start > total ? start : end,
+    text: slice.join('\n'),
+    totalLines: total,
+    truncated: end < total,
+  };
+}

package/mcp/tools/memory/module.ts

@@ -0,0 +1,152 @@
+/**
+ * Memory tool module (planning-64 K1) — implements ToolModule.
+ *
+ * Read-only, on-demand retrieval over the per-agent knowledge archive
+ * (`kb.sqlite`, built by src/ under Node). Two lanes of memory: the small core
+ * (MEMORY.md/USER.md) is injected every turn; everything else lives in the
+ * searchable archive and is reached here via `memory_search` / `memory_get` —
+ * so the bulk never has to sit in the prompt. Runs under Bun; reads via
+ * `bun:sqlite` (see archive-reader.ts).
+ */
+
+import type { ToolModule, McpToolDefinition, McpToolResult, ToolVisibility } from '../../types';
+import { searchArchive, getExcerpt, archiveDbPath, sharedDbPathFromEnv, mergeHits } from './archive-reader';
+
+/** Corpora the tool can serve. */
+const SUPPORTED_CORPORA = new Set(['memory', 'shared', 'all']);
+
+export class MemoryModule implements ToolModule {
+  id = 'memory';
+  toolVisibility: ToolVisibility = 'all-configured';
+
+  isEnabled(): boolean {
+    // Available whenever the agent's workspace dir is known (same gate as skills).
+    return Boolean(process.env.GATEWAY_WORKSPACE_DIR);
+  }
+
+  getTools(): McpToolDefinition[] {
+    return [
+      {
+        name: 'memory_search',
+        description:
+          'Search your long-term memory archive (past notes under memory/, plus MEMORY.md/USER.md) by keyword and get the most relevant snippets with their file + line range. Use this to recall details that are NOT in the memory currently loaded into your context — the archive holds far more than fits in the prompt. Read-only.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Keywords to search for.' },
+            maxResults: {
+              type: 'number',
+              description: 'Max snippets to return (default 6, max 20).',
+            },
+            corpus: {
+              type: 'string',
+              enum: ['memory', 'shared', 'all'],
+              description:
+                'Which corpus to search: "memory" (this agent, default), "shared" (the cross-agent shared KB), or "all" (both).',
+            },
+          },
+          required: ['query'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'memory_get',
+        description:
+          'Read an exact line range from one of your memory files (a path returned by memory_search, e.g. "memory/foo.md", or "MEMORY.md"/"USER.md"). Use after memory_search to pull the full context around a snippet. Read-only.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Memory-scoped path (memory/*.md, MEMORY.md, USER.md).' },
+            from: { type: 'number', description: '1-indexed start line (default 1).' },
+            lines: { type: 'number', description: 'Number of lines to return (default 200).' },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+    ];
+  }
+
+  async handleTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+    const workspaceDir = process.env.GATEWAY_WORKSPACE_DIR;
+    if (!workspaceDir) {
+      return this.err('Memory archive unavailable: no workspace directory configured.');
+    }
+
+    try {
+      switch (name) {
+        case 'memory_search': {
+          const query = typeof args.query === 'string' ? args.query.trim() : '';
+          if (!query) return this.err('memory_search requires a non-empty "query".');
+
+          // Fail closed on an unsupported corpus rather than silently widening scope.
+          const corpus = typeof args.corpus === 'string' ? args.corpus : 'memory';
+          if (!SUPPORTED_CORPORA.has(corpus)) {
+            return this.json({
+              results: [],
+              unavailable: true,
+              warning: `corpus "${corpus}" is not available yet (shared/all arrive in a later phase). Use "memory".`,
+            });
+          }
+
+          const rawMax = Number.isFinite(args.maxResults as number) ? (args.maxResults as number) : 6;
+          const maxResults = Math.max(1, Math.min(20, Math.floor(rawMax)));
+
+          const personalDb = archiveDbPath(workspaceDir);
+          const sharedDb = sharedDbPathFromEnv();
+          // Recall counter (planning-66): record retrievals ONLY against the
+          // per-agent archive (the GC tier). Gated by the gateway via env, mirroring
+          // GATEWAY_SHARED_KB_DIR — off unless dreaming.staleness.recordRetrievals.
+          const rec = { recordRetrievals: process.env.GATEWAY_RECORD_RETRIEVALS === '1' };
+          let results;
+          if (corpus === 'memory') {
+            results = searchArchive(personalDb, query, maxResults, rec).map((h) => ({ ...h, corpus: 'memory' }));
+          } else if (corpus === 'shared') {
+            if (!sharedDb) return this.json({ results: [], unavailable: true, warning: 'shared KB is not enabled.' });
+            results = searchArchive(sharedDb, query, maxResults).map((h) => ({ ...h, corpus: 'shared' }));
+          } else {
+            // "all": merge personal + shared, keep the best by bm25.
+            type Tagged = ReturnType<typeof searchArchive>[number] & { corpus: string };
+            const mine: Tagged[] = searchArchive(personalDb, query, maxResults, rec).map((h) => ({ ...h, corpus: 'memory' }));
+            const shared: Tagged[] = sharedDb
+              ? searchArchive(sharedDb, query, maxResults).map((h) => ({ ...h, corpus: 'shared' }))
+              : [];
+            results = mergeHits(mine, shared, maxResults);
+          }
+
+          if (results.length === 0) {
+            return this.json({
+              results: [],
+              note: 'No matches (or the archive has not been indexed yet).',
+            });
+          }
+          return this.json({ results, corpus });
+        }
+
+        case 'memory_get': {
+          const p = typeof args.path === 'string' ? args.path : '';
+          const from = Number.isFinite(args.from as number) ? (args.from as number) : 1;
+          const lines = Number.isFinite(args.lines as number) ? (args.lines as number) : 200;
+          const excerpt = getExcerpt(workspaceDir, p, from, lines);
+          if (!excerpt) {
+            return this.err(`memory_get: "${p}" is not a readable memory-scoped file (memory/*.md, MEMORY.md, USER.md).`);
+          }
+          return this.json(excerpt);
+        }
+
+        default:
+          return this.err(`Unknown memory tool: ${name}`);
+      }
+    } catch (e) {
+      return this.err(`memory tool error: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  private json(obj: unknown): McpToolResult {
+    return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) }] };
+  }
+
+  private err(text: string): McpToolResult {
+    return { content: [{ type: 'text', text }], isError: true };
+  }
+}