@0xmaxma/claude-gateway 1.7.9 → 1.8.0

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

@@ -13,7 +13,7 @@ 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';
+import { searchArchive, findSimilarSharedNotes, getExcerpt, isMemoryScopedPath, archiveDbPath, sharedDbPathFromEnv, mergeHits } from './archive-reader';
 
 // Build a temp agent dir with a kb.sqlite carrying the given chunks.
 function mkAgentWithArchive(
@@ -210,3 +210,27 @@ test('getExcerpt: a symlink inside memory/ escaping the workspace is refused', (
     fs.rmSync(agentDir, { recursive: true, force: true });
   }
 });
+
+test('findSimilarSharedNotes: OR-matches on partial overlap where an AND search (searchArchive) would miss', () => {
+  const { workspaceDir } = mkAgentWithArchive([
+    { id: 'notes/oncall-runbook.md#1-1', path: 'notes/oncall-runbook.md', start: 1, end: 1, text: 'escalate paging incidents to the platform team via pagerduty' },
+    { id: 'notes/unrelated.md#1-1', path: 'notes/unrelated.md', start: 1, end: 1, text: 'deploy checklist for the frontend release pipeline' },
+  ]);
+  const dbPath = archiveDbPath(workspaceDir);
+  // Seed text shares only "escalate" + "paging" with the runbook note, not the
+  // rest of its wording — an implicit-AND searchArchive() call would need every
+  // token to hit and returns nothing, but OR-based findSimilarSharedNotes finds it.
+  const seed = 'oncall escalation paging on-call playbook';
+  expect(searchArchive(dbPath, seed, 5).length).toBe(0);
+  const similar = findSimilarSharedNotes(dbPath, seed, 5);
+  expect(similar.length).toBe(1);
+  expect(similar[0].path).toBe('notes/oncall-runbook.md');
+});
+
+test('findSimilarSharedNotes: no matching terms, or a missing DB, both return []', () => {
+  const { workspaceDir } = mkAgentWithArchive([
+    { id: 'notes/oncall-runbook.md#1-1', path: 'notes/oncall-runbook.md', start: 1, end: 1, text: 'escalate paging incidents to the platform team' },
+  ]);
+  expect(findSimilarSharedNotes(archiveDbPath(workspaceDir), 'completely unrelated topic zzz', 5)).toEqual([]);
+  expect(findSimilarSharedNotes('/nonexistent/kb.sqlite', 'oncall escalation', 5)).toEqual([]);
+});

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

@@ -69,6 +69,22 @@ function toFtsMatch(query: string): string {
     .join(' ');
 }
 
+/**
+ * Same tokenizing/quoting as `toFtsMatch`, but joined with OR and capped to
+ * `maxTerms`. Used for "is anything like this already here?" lookups
+ * (`findSimilarSharedNotes`), where an implicit-AND match across a whole
+ * note's worth of terms would almost never hit — a near-duplicate rarely
+ * repeats every single word of the seed text.
+ */
+function toFtsMatchOr(query: string, maxTerms = 12): string {
+  return query
+    .split(/[^\p{L}\p{N}_]+/u)
+    .filter(Boolean)
+    .slice(0, maxTerms)
+    .map((t) => `"${t.replace(/"/g, '""')}"`)
+    .join(' OR ');
+}
+
 /**
  * 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.
@@ -111,16 +127,12 @@ function ensureEntryHashColumn(dbPath: string): void {
   }
 }
 
-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 [];
-
+/**
+ * Core FTS5 query, shared by `searchArchive` (implicit-AND keyword search)
+ * and `findSimilarSharedNotes` (OR-based near-duplicate lookup) — only the
+ * MATCH expression differs between the two callers.
+ */
+function runFtsMatchQuery(dbPath: string, match: string, maxResults: number): SearchHit[] {
   // Heal pre-#346 DBs in place so the query never crashes on a missing column.
   ensureEntryHashColumn(dbPath);
 
@@ -128,7 +140,6 @@ export function searchArchive(
   // 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(
@@ -153,7 +164,7 @@ export function searchArchive(
       originClass: string | null;
       importance: number | null;
     }>;
-    hits = rows.map((r) => ({
+    return rows.map((r) => ({
       path: r.path,
       startLine: r.startLine,
       endLine: r.endLine,
@@ -166,6 +177,18 @@ export function searchArchive(
   } finally {
     db.close();
   }
+}
+
+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 [];
+  const hits = runFtsMatchQuery(dbPath, match, maxResults);
 
   // Recall counter (planning-66): fire-and-forget, append-only, best-effort. A
   // dedicated writable handle (WAL + busy_timeout so it never fails a concurrent
@@ -191,6 +214,41 @@ export function searchArchive(
   return hits;
 }
 
+export function recordSharedPathRetrieval(dbPath: string, sourcePath: string, now = Date.now()): void {
+  if (!fs.existsSync(dbPath)) return;
+  try {
+    const db = new Database(dbPath);
+    try {
+      db.exec('PRAGMA busy_timeout=2000');
+      const rows = db
+        .query('SELECT DISTINCT entry_hash FROM kb_chunks WHERE path = ? AND entry_hash IS NOT NULL')
+        .all(sourcePath) as Array<{ entry_hash: string | null }>;
+      recordRetrievalHits(
+        { run: (sql, params = []) => void db.query(sql).run(...(params as never[])) },
+        rows.map((r) => r.entry_hash),
+        now,
+      );
+    } finally {
+      db.close();
+    }
+  } catch {
+    /* best-effort telemetry — never affect a direct read response */
+  }
+}
+
+/**
+ * Find shared notes whose content overlaps `seedText` (typically a new
+ * note's name plus the opening of its content) — the basis of
+ * `memory_shared_create`'s "does something like this already exist?" nudge.
+ * Read-only, same missing-DB/empty-query behavior as `searchArchive`.
+ */
+export function findSimilarSharedNotes(dbPath: string, seedText: string, maxResults = 3): SearchHit[] {
+  if (!fs.existsSync(dbPath)) return [];
+  const match = toFtsMatchOr(seedText);
+  if (!match) return [];
+  return runFtsMatchQuery(dbPath, match, maxResults);
+}
+
 /** A memory-scoped path: MEMORY.md, USER.md, or memory/**.md — no traversal. */
 export function isMemoryScopedPath(relPath: string): boolean {
   const p = relPath.replace(/\\/g, '/');

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

@@ -0,0 +1,168 @@
+/**
+ * Bun tests for the shared-KB write mirror (memory_shared_create/_get/_update/
+ * _delete's building blocks). Runs under Bun (`bun test`) alongside archive-reader.test.ts.
+ */
+
+import { test, expect } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import {
+  sharedNoteFilename,
+  sharedNoteExists,
+  readSharedNote,
+  writeSharedNoteAtomic,
+  deleteSharedNote,
+  contentLossPercent,
+  triggerSharedReindex,
+} from './archive-writer';
+import { searchArchive } from './archive-reader';
+
+function tmpVaultDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'kb-shared-write-'));
+}
+
+test('sharedNoteFilename: slugifies, strips .md, contains to one segment (mirrors Node-side shared-writer)', () => {
+  expect(sharedNoteFilename('My Cool Note.md')).toBe('my-cool-note.md');
+  expect(sharedNoteFilename('../../etc/passwd')).toBe('etc-passwd.md'); // no separators survive
+  expect(sharedNoteFilename('')).toBe('note.md');
+  expect(sharedNoteFilename('a/b\\c')).toBe('a-b-c.md');
+});
+
+test('writeSharedNoteAtomic: writes atomically into <vaultDir>/notes and cannot escape it', () => {
+  const vaultDir = tmpVaultDir();
+  try {
+    const p = writeSharedNoteAtomic(vaultDir, '../escape attempt', 'shared body');
+    const notesDir = path.join(vaultDir, 'notes');
+    expect(p.startsWith(notesDir + path.sep)).toBe(true); // contained
+    expect(fs.readFileSync(p, 'utf8')).toBe('shared body');
+    // No stray temp files left behind.
+    expect(fs.readdirSync(notesDir).some((f) => f.startsWith('.tmp-'))).toBe(false);
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+});
+
+test('sharedNoteExists: false before write, true after — the basis for memory_shared_create/_update\'s existence gates', () => {
+  const vaultDir = tmpVaultDir();
+  try {
+    expect(sharedNoteExists(vaultDir, 'oncall')).toBe(false);
+    writeSharedNoteAtomic(vaultDir, 'oncall', 'escalate paging incidents to platform team');
+    expect(sharedNoteExists(vaultDir, 'oncall')).toBe(true);
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+});
+
+test('readSharedNote: null before write, full content after', () => {
+  const vaultDir = tmpVaultDir();
+  try {
+    expect(readSharedNote(vaultDir, 'oncall')).toBeNull();
+    writeSharedNoteAtomic(vaultDir, 'oncall', 'escalate paging incidents to platform team');
+    expect(readSharedNote(vaultDir, 'oncall')).toBe('escalate paging incidents to platform team');
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+});
+
+test('writeSharedNoteAtomic: same name overwrites in place (update semantics, no duplicate file)', () => {
+  const vaultDir = tmpVaultDir();
+  try {
+    const p1 = writeSharedNoteAtomic(vaultDir, 'oncall', 'v1: escalate to platform team');
+    const p2 = writeSharedNoteAtomic(vaultDir, 'oncall', 'v2: escalate to SRE team');
+    expect(p1).toBe(p2);
+    expect(fs.readFileSync(p2, 'utf8')).toBe('v2: escalate to SRE team');
+    expect(fs.readdirSync(path.join(vaultDir, 'notes')).length).toBe(1);
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+});
+
+test('deleteSharedNote: removes an existing note and reports true; false (no-op) if absent', () => {
+  const vaultDir = tmpVaultDir();
+  try {
+    expect(deleteSharedNote(vaultDir, 'oncall')).toBe(false); // nothing written yet
+    writeSharedNoteAtomic(vaultDir, 'oncall', 'escalate paging incidents to platform team');
+    expect(sharedNoteExists(vaultDir, 'oncall')).toBe(true);
+    expect(deleteSharedNote(vaultDir, 'oncall')).toBe(true);
+    expect(sharedNoteExists(vaultDir, 'oncall')).toBe(false);
+    expect(deleteSharedNote(vaultDir, 'oncall')).toBe(false); // already gone
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+});
+
+test('deleteSharedNote: cannot escape the notes dir (name is filename-slugified first)', () => {
+  const vaultDir = tmpVaultDir();
+  try {
+    // Nothing outside notes/ can ever be targeted, so this is always a no-op.
+    expect(deleteSharedNote(vaultDir, '../../etc/passwd')).toBe(false);
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+});
+
+test('contentLossPercent: 0 when every old line survives, 100 when none do', () => {
+  const oldContent = 'line one\nline two\nline three';
+  expect(contentLossPercent(oldContent, 'line one\nline two\nline three\nline four')).toBe(0); // pure append, nothing dropped
+  expect(contentLossPercent(oldContent, 'totally different content')).toBe(100);
+});
+
+test('contentLossPercent: dropping a subset of old lines is proportional loss, not zero', () => {
+  const oldContent = 'line one\nline two\nline three';
+  expect(contentLossPercent(oldContent, 'line one\nline two')).toBe(33); // 1 of 3 old lines missing
+});
+
+test('contentLossPercent: partial loss rounds to nearest percent', () => {
+  // 2 of 4 old lines survive verbatim -> 50% lost.
+  const oldContent = 'a\nb\nc\nd';
+  expect(contentLossPercent(oldContent, 'a\nb\nsomething else')).toBe(50);
+});
+
+test('contentLossPercent: empty old content never divides by zero', () => {
+  expect(contentLossPercent('', 'brand new content')).toBe(0);
+  expect(contentLossPercent('\n\n', 'brand new content')).toBe(0); // blank-only old content
+});
+
+test('triggerSharedReindex: never throws, even when the compiled CLI is missing', () => {
+  const vaultDir = tmpVaultDir();
+  try {
+    expect(() => triggerSharedReindex(vaultDir)).not.toThrow();
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+});
+
+// End-to-end proof of the acceptance criterion: a written note is discoverable
+// via the same search path memory_search uses, WITHOUT waiting for the nightly
+// dream or a manual reindex step. Uses the real compiled reindex-cli.js (built
+// by `npm run build` into dist/ alongside this package, per package.json
+// `files`) — skips gracefully if that build artifact is missing (e.g. a bare
+// `bun test` run against source with no prior `npm run build`).
+test('memory_shared_create flow: write + triggerSharedReindex makes the note searchable within a few seconds', async () => {
+  const cliPath = path.join(__dirname, '..', '..', '..', 'dist', 'agent', 'knowledge', 'reindex-cli.js');
+  if (!fs.existsSync(cliPath)) {
+    console.warn('[archive-writer.test] dist/agent/knowledge/reindex-cli.js missing — run `npm run build` first; skipping e2e reindex test');
+    return;
+  }
+  const vaultDir = tmpVaultDir();
+  try {
+    const content = 'The staging cluster now runs on kubernetes in ap-southeast-1.';
+    writeSharedNoteAtomic(vaultDir, 'infra-note', content);
+    triggerSharedReindex(vaultDir);
+
+    const dbPath = path.join(vaultDir, 'kb.sqlite');
+    const deadline = Date.now() + 8000;
+    let hits: ReturnType<typeof searchArchive> = [];
+    while (Date.now() < deadline) {
+      hits = searchArchive(dbPath, 'staging cluster kubernetes', 5);
+      if (hits.length > 0) break;
+      await new Promise((r) => setTimeout(r, 150));
+    }
+    expect(hits.length).toBeGreaterThan(0);
+    expect(hits[0].snippet).toContain('kubernetes');
+  } finally {
+    fs.rmSync(vaultDir, { recursive: true, force: true });
+  }
+}, 12000);

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

@@ -0,0 +1,137 @@
+/**
+ * Write-side glue for the shared KB (Bun/mcp side; planning-64 K3 follow-up).
+ *
+ * Unlike the read side (archive-reader.ts, which must reimplement its query
+ * path because `bun:sqlite`/`node:sqlite` are different bindings over the
+ * same file), the atomic-write logic itself (slugify + write-temp-then-rename)
+ * has NO `node:sqlite` dependency — it's plain `fs`/`path`. So this file does
+ * NOT duplicate it: it imports the real `writeSharedNote` / `sharedNoteFilename`
+ * straight from the compiled `dist/agent/knowledge/shared-writer.js`, the same
+ * pattern already used elsewhere in `mcp/` for logic it needs but cannot reach
+ * in `src/` directly (see `mcp/tools/slack/module.ts`'s `SlackClient` import,
+ * `mcp/tools/telegram/receiver-server.ts`'s `turn-trace`/`incident-store`
+ * imports). Verified against mcp-no-src-imports.test.ts.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { writeSharedNote, sharedNoteFilename } from '../../../dist/agent/knowledge/shared-writer.js';
+import type { ResolvedKnowledgeSharedCfg } from '../../../dist/agent/knowledge/types.js';
+
+export { sharedNoteFilename };
+
+/**
+ * Reconstruct the minimal resolved shared-KB config `writeSharedNote` needs
+ * (only `root`/`project` are actually read, via `sharedNotesDir`), by
+ * splitting `vaultDir` = `<root>/<project>` — the inverse of the Node-side
+ * `sharedVaultDir()`. `mode`/`graph`/`enabled` are dead weight for this call
+ * (writeSharedNote never reads them) but filled in for type shape.
+ */
+function cfgFromVaultDir(vaultDir: string): ResolvedKnowledgeSharedCfg {
+  return {
+    enabled: true,
+    root: path.dirname(vaultDir),
+    project: path.basename(vaultDir),
+    mode: 'auto',
+    graph: false,
+  };
+}
+
+/**
+ * Note identity is the caller's own freeform `name`, slugified to one safe
+ * path segment (`sharedNoteFilename`) — deliberately NOT prefixed with an
+ * agent id or content-hashed. `memory_shared_create`/`_update`/`_delete` are
+ * a shared, cross-agent namespace by design: any agent can name a note
+ * anything, and a repeat call with the same name addresses the same file.
+ * This is why `memory_shared_create` cross-checks near-duplicates via
+ * `findSimilarSharedNotes` before writing — nothing else prevents two agents
+ * from independently picking the same topic under different names.
+ *
+ * This matches the nightly promoter's reason-derived naming (`shared-promote.ts`),
+ * so recurring automatic promotions and manual writes resolve through the same
+ * freeform shared namespace.
+ */
+
+/** Whether a note already exists at this name (post-`sharedNoteFilename` slugification). */
+export function sharedNoteExists(vaultDir: string, name: string): boolean {
+  return fs.existsSync(path.join(vaultDir, 'notes', sharedNoteFilename(name)));
+}
+
+/** Full content of a shared note, or null if it does not exist. */
+export function readSharedNote(vaultDir: string, name: string): string | null {
+  const target = path.join(vaultDir, 'notes', sharedNoteFilename(name));
+  if (!fs.existsSync(target)) return null;
+  return fs.readFileSync(target, 'utf8');
+}
+
+/** Write a note into the shared vault atomically. Returns the absolute path written. */
+export function writeSharedNoteAtomic(vaultDir: string, name: string, content: string): string {
+  return writeSharedNote(cfgFromVaultDir(vaultDir), name, content);
+}
+
+/** Delete a note by name. Returns false (no-op) if it did not exist. */
+export function deleteSharedNote(vaultDir: string, name: string): boolean {
+  const target = path.join(vaultDir, 'notes', sharedNoteFilename(name));
+  if (!fs.existsSync(target)) return false;
+  fs.rmSync(target);
+  return true;
+}
+
+/**
+ * Percentage (0-100) of `oldContent`'s non-blank lines that do NOT appear
+ * verbatim anywhere in `newContent` — `memory_shared_update`'s guard against
+ * an agent blindly clobbering a note instead of editing it. Deliberately a
+ * blunt line-membership check (not a real diff/LCS): cheap, deterministic,
+ * and good enough to flag "this update discards most of what was here",
+ * which is all the guard needs to do. 0 old lines counts as 0% lost (nothing
+ * to lose) rather than dividing by zero.
+ */
+export function contentLossPercent(oldContent: string, newContent: string): number {
+  const oldLines = oldContent.split('\n').map((l) => l.trim()).filter(Boolean);
+  if (oldLines.length === 0) return 0;
+  const newLineSet = new Set(newContent.split('\n').map((l) => l.trim()));
+  const lost = oldLines.filter((l) => !newLineSet.has(l)).length;
+  return Math.round((lost / oldLines.length) * 100);
+}
+
+/**
+ * Fire-and-forget reindex trigger so a promoted note is searchable immediately,
+ * instead of waiting for the next natural reindex (session spawn / nightly
+ * dream). Spawns the SAME compiled CLI the Node-side `spawnArchiveReindex`
+ * uses (`dist/agent/knowledge/reindex-cli.js`) as a SUBPROCESS (never
+ * imported — reindex-cli.ts requires `node:sqlite`, which Bun does not have,
+ * so it can only be run, not loaded, from this process).
+ *
+ * This code runs under Bun, whose own `process.execPath` points at the `bun`
+ * binary — spawning the CLI with that fails silently (`node:sqlite` is not a
+ * Bun built-in) since the child is detached with `stdio:'ignore'`. The gateway
+ * forwards its own (real Node) `process.execPath` via `GATEWAY_NODE_EXEC_PATH`
+ * (see src/session/process.ts) specifically so this spawn uses the right
+ * runtime; fall back to a bare `node` on PATH if that env is somehow unset.
+ *
+ * The CLI's shared-archive half only needs `{enabled, root, project}` (see
+ * `cfgFromVaultDir`); the personal-archive half is explicitly disabled
+ * (`{enabled:false}`) since this trigger only concerns the shared vault.
+ * Best-effort: swallows every failure so a promote call never fails because
+ * reindexing couldn't be kicked off.
+ */
+export function triggerSharedReindex(vaultDir: string): void {
+  try {
+    const cliPath = path.join(__dirname, '..', '..', '..', 'dist', 'agent', 'knowledge', 'reindex-cli.js');
+    if (!fs.existsSync(cliPath)) return;
+    const nodeBin = process.env.GATEWAY_NODE_EXEC_PATH || 'node';
+    const sharedCfg = cfgFromVaultDir(vaultDir);
+    const child = spawn(
+      nodeBin,
+      [cliPath, vaultDir, JSON.stringify({ enabled: false }), JSON.stringify(sharedCfg)],
+      { detached: true, stdio: 'ignore' },
+    );
+    child.on('error', () => {
+      /* swallowed */
+    });
+    child.unref();
+  } catch {
+    /* best-effort: reindex is never on the critical path of a promote call */
+  }
+}

package/mcp/tools/memory/module.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Bun tests for MemoryModule.handleTool's memory_shared_create / _get / _update /
+ * _delete — the exists/missing gates, the near-duplicate nudge on create, and the
+ * content-loss confirmation guard on update.
+ */
+
+import { test, expect, beforeEach, afterEach } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { MemoryModule } from './module';
+
+let workspaceDir: string;
+let vaultDir: string;
+const originalEnv = {
+  GATEWAY_WORKSPACE_DIR: process.env.GATEWAY_WORKSPACE_DIR,
+  GATEWAY_SHARED_KB_DIR: process.env.GATEWAY_SHARED_KB_DIR,
+};
+
+beforeEach(() => {
+  workspaceDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-module-ws-'));
+  vaultDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-module-shared-'));
+  process.env.GATEWAY_WORKSPACE_DIR = workspaceDir;
+  process.env.GATEWAY_SHARED_KB_DIR = vaultDir;
+});
+
+afterEach(() => {
+  fs.rmSync(workspaceDir, { recursive: true, force: true });
+  fs.rmSync(vaultDir, { recursive: true, force: true });
+  for (const [k, v] of Object.entries(originalEnv)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+});
+
+function textOf(result: Awaited<ReturnType<MemoryModule['handleTool']>>): string {
+  return (result.content[0] as { text: string }).text;
+}
+
+test('memory_shared_create: writes a new note under a freeform name (no agent-id prefix)', async () => {
+  const mod = new MemoryModule();
+  const result = await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'escalate to SRE' });
+  expect(result.isError).toBeUndefined();
+  const body = JSON.parse(textOf(result));
+  expect(body.created).toBe(true);
+  expect(fs.existsSync(path.join(vaultDir, 'notes', 'oncall-runbook.md'))).toBe(true);
+});
+
+test('memory_shared_create: fails with an exact-name collision, does not overwrite', async () => {
+  const mod = new MemoryModule();
+  await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'v1: escalate to platform team' });
+  const result = await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'v2 attempt' });
+  expect(result.isError).toBe(true);
+  expect(textOf(result)).toContain('already exists');
+  expect(fs.readFileSync(path.join(vaultDir, 'notes', 'oncall-runbook.md'), 'utf8')).toBe('v1: escalate to platform team');
+});
+
+test('memory_shared_create: any agent can create — no GATEWAY_AGENT_ID required', async () => {
+  delete process.env.GATEWAY_AGENT_ID;
+  const mod = new MemoryModule();
+  const result = await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'escalate to SRE' });
+  expect(result.isError).toBeUndefined();
+});
+
+test('memory_shared_get: reads full content; errors on a missing note', async () => {
+  const mod = new MemoryModule();
+  const missing = await mod.handleTool('memory_shared_get', { name: 'oncall-runbook' });
+  expect(missing.isError).toBe(true);
+
+  await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'escalate to SRE' });
+  const result = await mod.handleTool('memory_shared_get', { name: 'oncall-runbook' });
+  expect(result.isError).toBeUndefined();
+  const body = JSON.parse(textOf(result));
+  expect(body.content).toBe('escalate to SRE');
+});
+
+test('memory_shared_update: fails when the note does not exist yet, pointing at memory_shared_create', async () => {
+  const mod = new MemoryModule();
+  const result = await mod.handleTool('memory_shared_update', { name: 'oncall-runbook', content: 'escalate to SRE' });
+  expect(result.isError).toBe(true);
+  expect(textOf(result)).toContain('memory_shared_create');
+});
+
+test('memory_shared_update: applies a small edit (below the loss threshold) without confirm', async () => {
+  const mod = new MemoryModule();
+  await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'line one\nline two\nline three\nline four' });
+  // Drop 1 of 4 lines (25% loss) — under the 50% threshold, should apply directly.
+  const result = await mod.handleTool('memory_shared_update', { name: 'oncall-runbook', content: 'line one\nline two\nline three' });
+  expect(result.isError).toBeUndefined();
+  const body = JSON.parse(textOf(result));
+  expect(body.updated).toBe(true);
+  expect(fs.readFileSync(path.join(vaultDir, 'notes', 'oncall-runbook.md'), 'utf8')).toBe('line one\nline two\nline three');
+});
+
+test('memory_shared_update: a large content loss needs confirm:true, and does not write until given', async () => {
+  const mod = new MemoryModule();
+  await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'line one\nline two\nline three\nline four' });
+
+  const warned = await mod.handleTool('memory_shared_update', { name: 'oncall-runbook', content: 'brand new unrelated content' });
+  expect(warned.isError).toBeUndefined();
+  const warnedBody = JSON.parse(textOf(warned));
+  expect(warnedBody.updated).toBe(false);
+  expect(warnedBody.needsConfirmation).toBe(true);
+  expect(warnedBody.lossPercent).toBe(100);
+  // Still the original content — the warning must not have written anything.
+  expect(fs.readFileSync(path.join(vaultDir, 'notes', 'oncall-runbook.md'), 'utf8')).toBe('line one\nline two\nline three\nline four');
+
+  const confirmed = await mod.handleTool('memory_shared_update', { name: 'oncall-runbook', content: 'brand new unrelated content', confirm: true });
+  const confirmedBody = JSON.parse(textOf(confirmed));
+  expect(confirmedBody.updated).toBe(true);
+  expect(fs.readFileSync(path.join(vaultDir, 'notes', 'oncall-runbook.md'), 'utf8')).toBe('brand new unrelated content');
+});
+
+test('memory_shared_delete: any agent can delete any note — no ownership scoping', async () => {
+  const mod = new MemoryModule();
+  await mod.handleTool('memory_shared_create', { name: 'oncall-runbook', content: 'escalate to SRE' });
+  delete process.env.GATEWAY_AGENT_ID; // a different/misconfigured agent — still allowed
+  const result = await mod.handleTool('memory_shared_delete', { name: 'oncall-runbook' });
+  expect(result.isError).toBeUndefined();
+  expect(fs.existsSync(path.join(vaultDir, 'notes', 'oncall-runbook.md'))).toBe(false);
+});
+
+test('memory_shared_delete: errors (no-op) on a name that does not exist', async () => {
+  const mod = new MemoryModule();
+  const result = await mod.handleTool('memory_shared_delete', { name: 'never-created' });
+  expect(result.isError).toBe(true);
+});
+
+// End-to-end proof that memory_shared_create's near-duplicate nudge actually
+// fires through the real reindex path (not just the pure findSimilarSharedNotes
+// unit tests in archive-reader.test.ts). Skips gracefully if dist/ hasn't been
+// built, same guard as archive-writer.test.ts's e2e reindex test.
+test('memory_shared_create: near-duplicate content is nudged for confirmation once reindexed', async () => {
+  const cliPath = path.join(__dirname, '..', '..', '..', 'dist', 'agent', 'knowledge', 'reindex-cli.js');
+  if (!fs.existsSync(cliPath)) {
+    console.warn('[memory module.test] dist/agent/knowledge/reindex-cli.js missing — run `npm run build` first; skipping e2e near-dup test');
+    return;
+  }
+  const mod = new MemoryModule();
+  await mod.handleTool('memory_shared_create', {
+    name: 'oncall-escalation-runbook',
+    content: 'escalate paging incidents to the platform team via pagerduty, then page SRE if unacknowledged in 10 minutes',
+  });
+
+  // Wait for the fire-and-forget reindex triggered by the create above.
+  const dbPath = path.join(vaultDir, 'kb.sqlite');
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline && !fs.existsSync(dbPath)) {
+    await new Promise((r) => setTimeout(r, 150));
+  }
+
+  let result = await mod.handleTool('memory_shared_create', {
+    name: 'paging-oncall-playbook',
+    content: 'oncall playbook: paging escalation to platform team via pagerduty',
+  });
+  // Reindex is best-effort/async; retry briefly if it hadn't landed yet.
+  const retryDeadline = Date.now() + 8000;
+  while (Date.now() < retryDeadline) {
+    const body = JSON.parse(textOf(result));
+    if (body.needsConfirmation) break;
+    await new Promise((r) => setTimeout(r, 200));
+    result = await mod.handleTool('memory_shared_create', {
+      name: 'paging-oncall-playbook',
+      content: 'oncall playbook: paging escalation to platform team via pagerduty',
+    });
+  }
+  const body = JSON.parse(textOf(result));
+  expect(body.created).toBe(false);
+  expect(body.needsConfirmation).toBe(true);
+  expect(body.similar.some((s: { path: string }) => s.path.includes('oncall-escalation-runbook'))).toBe(true);
+  expect(fs.existsSync(path.join(vaultDir, 'notes', 'paging-oncall-playbook.md'))).toBe(false);
+
+  // confirm:true creates it anyway.
+  const confirmed = await mod.handleTool('memory_shared_create', {
+    name: 'paging-oncall-playbook',
+    content: 'oncall playbook: paging escalation to platform team via pagerduty',
+    confirm: true,
+  });
+  expect(JSON.parse(textOf(confirmed)).created).toBe(true);
+
+  // #386: confirming past a near-dup nudge should link the related note(s)
+  // found, not leave a disconnected duplicate — so /knowledge/graph gets a
+  // real edge instead of staying empty.
+  const written = fs.readFileSync(path.join(vaultDir, 'notes', 'paging-oncall-playbook.md'), 'utf8');
+  expect(written).toContain('[[oncall-escalation-runbook]]');
+}, 20000);