@0xmaxma/claude-gateway 1.7.8 → 1.7.10

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);

package/mcp/tools/memory/module.ts

@@ -10,11 +10,22 @@
  */
 
 import type { ToolModule, McpToolDefinition, McpToolResult, ToolVisibility } from '../../types';
-import { searchArchive, getExcerpt, archiveDbPath, sharedDbPathFromEnv, mergeHits } from './archive-reader';
+import { searchArchive, findSimilarSharedNotes, getExcerpt, archiveDbPath, sharedDbPathFromEnv, mergeHits, recordSharedPathRetrieval } from './archive-reader';
+import { sharedNoteExists, readSharedNote, writeSharedNoteAtomic, deleteSharedNote, contentLossPercent, triggerSharedReindex, sharedNoteFilename } from './archive-writer';
+
+/** memory_shared_update: below this line-loss %, an update just applies — no confirm needed. */
+const UPDATE_LOSS_CONFIRM_THRESHOLD = 50;
 
 /** Corpora the tool can serve. */
 const SUPPORTED_CORPORA = new Set(['memory', 'shared', 'all']);
 
+// Mirrors skill_create's MAX_SKILL_SIZE (mcp/tools/skills/handlers.ts) — the
+// direct structural precedent for a write-capable, scope-aware MCP tool. A
+// shared note lives in a vault SHARED across every agent in the project, so
+// leaving it uncapped would let one agent (a runaway loop, or a prompt
+// injection) exhaust shared disk / bloat the shared FTS5 index for everyone.
+const MAX_SHARED_NOTE_SIZE = 100 * 1024; // 100KB
+
 export class MemoryModule implements ToolModule {
   id = 'memory';
   toolVisibility: ToolVisibility = 'all-configured';
@@ -64,6 +75,60 @@ export class MemoryModule implements ToolModule {
           additionalProperties: false,
         },
       },
+      {
+        name: 'memory_shared_create',
+        description:
+          'Create a NEW note in the shared, cross-agent knowledge base RIGHT NOW, instead of waiting for the nightly automatic promotion. This is an explicit, agent-initiated write (works even when shared-KB mode is "propose"). Notes live in a shared namespace across every agent — pick any "name" you like, there is no agent-id prefix. Fails if a note with this exact name already exists (use memory_shared_update on it instead, after reading it with memory_shared_get). Before writing, this also searches the shared KB for notes with SIMILAR content and, if any are found, returns them instead of creating (to avoid near-duplicate notes cluttering the vault) — pass confirm:true to create anyway once you have checked they are not the same topic; when you do, a `[[link]]` to each similar note found is appended to your content automatically, so the knowledge-graph dashboard stays connected instead of gaining a disconnected duplicate. The note becomes searchable via memory_search (corpus "shared" or "all") shortly after this call returns.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'Freeform name identifying this note, e.g. "deploy-runbook". Stable identity — reuse it with memory_shared_update to edit the same note later.' },
+            content: { type: 'string', description: 'Full note body to write into the shared KB. Max 100KB.' },
+            confirm: { type: 'boolean', description: 'Create anyway even though similar existing notes were found. Default: false.' },
+          },
+          required: ['name', 'content'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'memory_shared_get',
+        description: 'Read the full current content of one shared-KB note by its exact "name" (see memory_shared_create). Use this before memory_shared_update so your edit is based on what is actually there — memory_search only returns short snippets, not the full note.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'The note\'s exact name.' },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'memory_shared_update',
+        description:
+          `Update an EXISTING shared-KB note by its exact "name" — replaces its full content with "content". Fails if no note with this name exists yet (use memory_shared_create instead). Read the note first with memory_shared_get and edit it — "content" is what the note becomes, not what gets appended, so anything you drop is gone. As a guard against an update that blindly discards most of the note (rather than an intentional rewrite), if the new content is missing ${UPDATE_LOSS_CONFIRM_THRESHOLD}%+ of the existing note's lines, this returns a warning instead of writing — pass confirm:true once you have checked that is what you intend.`,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'The note\'s exact name (see memory_shared_create).' },
+            content: { type: 'string', description: 'Full replacement body for the note. Max 100KB.' },
+            confirm: { type: 'boolean', description: `Apply the update even though it would remove ${UPDATE_LOSS_CONFIRM_THRESHOLD}%+ of the existing content. Default: false.` },
+          },
+          required: ['name', 'content'],
+          additionalProperties: false,
+        },
+      },
+      {
+        name: 'memory_shared_delete',
+        description: 'Delete one shared-KB note by its exact "name" (see memory_shared_create). Any agent can delete any note in the shared vault — there is no per-agent ownership. This cannot delete notes the nightly dreaming pipeline promoted (different naming scheme).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'The note\'s exact name.' },
+          },
+          required: ['name'],
+          additionalProperties: false,
+        },
+      },
     ];
   }
 
@@ -94,22 +159,23 @@ export class MemoryModule implements ToolModule {
 
           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.
+          // Recall counters are append-only, best-effort telemetry. Apply the
+          // same opt-in recording to BOTH KB tiers: shared lifecycle/staleness
+          // (issue #392) needs real `memory_search` reads to retain and restore
+          // notes, not manually seeded DB events in tests.
           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' }));
+            results = searchArchive(sharedDb, query, maxResults, rec).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' }))
+              ? searchArchive(sharedDb, query, maxResults, rec).map((h) => ({ ...h, corpus: 'shared' }))
               : [];
             results = mergeHits(mine, shared, maxResults);
           }
@@ -134,6 +200,126 @@ export class MemoryModule implements ToolModule {
           return this.json(excerpt);
         }
 
+        case 'memory_shared_create': {
+          // Same gate memory_search uses for corpus:"shared" — fail closed with a
+          // clear error rather than silently falling back to some default vault.
+          const vaultDir = process.env.GATEWAY_SHARED_KB_DIR;
+          if (!vaultDir || !vaultDir.trim()) {
+            return this.err('memory_shared_create unavailable: shared KB is not enabled.');
+          }
+          const name = typeof args.name === 'string' ? args.name.trim() : '';
+          if (!name) return this.err('memory_shared_create requires non-empty "name".');
+          let content = typeof args.content === 'string' ? args.content : '';
+          if (!content.trim()) return this.err('memory_shared_create requires non-empty "content".');
+          if (content.length > MAX_SHARED_NOTE_SIZE) {
+            return this.err(`memory_shared_create: content exceeds ${MAX_SHARED_NOTE_SIZE / 1024}KB limit (${(content.length / 1024).toFixed(1)}KB).`);
+          }
+          if (sharedNoteExists(vaultDir, name)) {
+            return this.err(`memory_shared_create: a note named "${name}" already exists. Use memory_shared_update to modify it (read it first with memory_shared_get), or pick a different name.`);
+          }
+
+          const confirm = args.confirm === true;
+          const sharedDb = sharedDbPathFromEnv();
+          const similar = sharedDb ? findSimilarSharedNotes(sharedDb, `${name} ${content}`, 3) : [];
+          if (similar.length > 0) {
+            if (!confirm) {
+              return this.json({
+                created: false,
+                needsConfirmation: true,
+                reason: 'similar-notes-found',
+                similar: similar.map((h) => ({ path: h.path, snippet: h.snippet })),
+                message: `Found ${similar.length} existing note(s) with similar content — consider memory_shared_update on one of these instead of creating a new one. Pass confirm:true to create "${name}" anyway.`,
+              });
+            }
+            // Confirmed anyway: link to the related notes instead of leaving a
+            // disconnected duplicate (#386) — wiki.ts already resolves
+            // [[wikilinks]] into real /knowledge/graph edges, no parser change
+            // needed, this is the only writer that needs to start emitting them.
+            const links = similar
+              .map((h) => h.path.replace(/\.md$/i, ''))
+              .filter((n) => n !== name)
+              .map((n) => `[[${n}]]`);
+            if (links.length > 0) {
+              content = `${content.trim()}\n\nRelated: ${links.join(' ')}`;
+              if (content.length > MAX_SHARED_NOTE_SIZE) {
+                return this.err(`memory_shared_create: content plus related-note links exceeds ${MAX_SHARED_NOTE_SIZE / 1024}KB limit.`);
+              }
+            }
+          }
+
+          const notePath = writeSharedNoteAtomic(vaultDir, name, content);
+          triggerSharedReindex(vaultDir);
+          return this.json({ created: true, path: notePath });
+        }
+
+        case 'memory_shared_get': {
+          const vaultDir = process.env.GATEWAY_SHARED_KB_DIR;
+          if (!vaultDir || !vaultDir.trim()) {
+            return this.err('memory_shared_get unavailable: shared KB is not enabled.');
+          }
+          const name = typeof args.name === 'string' ? args.name.trim() : '';
+          if (!name) return this.err('memory_shared_get requires non-empty "name".');
+          const content = readSharedNote(vaultDir, name);
+          if (content === null) {
+            return this.err(`memory_shared_get: no note named "${name}" found.`);
+          }
+          if (process.env.GATEWAY_RECORD_RETRIEVALS === '1' && sharedDb) {
+            // Shared notes are lifecycle-whole-file entries, so record the source
+            // note's indexed entry hash after a successful exact read (#392).
+            recordSharedPathRetrieval(sharedDb, sharedNoteFilename(name));
+          }
+          return this.json({ name, content });
+        }
+
+        case 'memory_shared_update': {
+          const vaultDir = process.env.GATEWAY_SHARED_KB_DIR;
+          if (!vaultDir || !vaultDir.trim()) {
+            return this.err('memory_shared_update unavailable: shared KB is not enabled.');
+          }
+          const name = typeof args.name === 'string' ? args.name.trim() : '';
+          if (!name) return this.err('memory_shared_update requires non-empty "name".');
+          const content = typeof args.content === 'string' ? args.content : '';
+          if (!content.trim()) return this.err('memory_shared_update requires non-empty "content".');
+          if (content.length > MAX_SHARED_NOTE_SIZE) {
+            return this.err(`memory_shared_update: content exceeds ${MAX_SHARED_NOTE_SIZE / 1024}KB limit (${(content.length / 1024).toFixed(1)}KB).`);
+          }
+          const existing = readSharedNote(vaultDir, name);
+          if (existing === null) {
+            return this.err(`memory_shared_update: no note named "${name}" found. Use memory_shared_create instead.`);
+          }
+
+          const lossPercent = contentLossPercent(existing, content);
+          const confirm = args.confirm === true;
+          if (lossPercent >= UPDATE_LOSS_CONFIRM_THRESHOLD && !confirm) {
+            return this.json({
+              updated: false,
+              needsConfirmation: true,
+              reason: 'large-content-loss',
+              lossPercent,
+              message: `This update would remove ~${lossPercent}% of the existing note's lines. Pass confirm:true if that's intentional.`,
+            });
+          }
+
+          const notePath = writeSharedNoteAtomic(vaultDir, name, content);
+          triggerSharedReindex(vaultDir);
+          return this.json({ updated: true, path: notePath, lossPercent });
+        }
+
+        case 'memory_shared_delete': {
+          const vaultDir = process.env.GATEWAY_SHARED_KB_DIR;
+          if (!vaultDir || !vaultDir.trim()) {
+            return this.err('memory_shared_delete unavailable: shared KB is not enabled.');
+          }
+          const name = typeof args.name === 'string' ? args.name.trim() : '';
+          if (!name) return this.err('memory_shared_delete requires non-empty "name".');
+          const deleted = deleteSharedNote(vaultDir, name);
+          if (!deleted) {
+            return this.err(`memory_shared_delete: no note named "${name}" found.`);
+          }
+          triggerSharedReindex(vaultDir);
+          return this.json({ deleted: true, name });
+        }
+
         default:
           return this.err(`Unknown memory tool: ${name}`);
       }

package/mcp/tools/shared/limits.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared limits for the channel reply tools (Discord / Telegram / Slack).
+ *
+ * Self-contained on purpose, like share-client.ts: mcp/** ships as source
+ * without src/**, so this module must not import from src/ (see
+ * tests/unit/mcp-no-src-imports.test.ts).
+ */
+
+/**
+ * Cap on a single outbound attachment. 50 MB is the smallest of the three
+ * platforms' own upload ceilings, so one value keeps the tools' behaviour
+ * identical instead of each re-declaring the same literal.
+ */
+export const MAX_ATTACHMENT_BYTES = 50 * 1024 * 1024;