@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/memory/mcp/dist/index.js

@@ -0,0 +1,1813 @@
+import { initStderrTee } from "../../../../lib/mcp-stderr-tee/dist/index.js";
+initStderrTee("memory");
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { eagerTool } from "../../../../lib/mcp-eager/dist/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { int } from "neo4j-driver";
+import { memorySearch } from "./tools/memory-search.js";
+import { memoryRank } from "./tools/memory-rank.js";
+import { memoryWrite } from "./tools/memory-write.js";
+import { loadSchema } from "./lib/schema-loader.js";
+import { buildLiveSchemaSource, defaultSchemaCypherPath, } from "./lib/live-schema-source.js";
+import { memoryReindex } from "./tools/memory-reindex.js";
+import { memoryIngestExtract } from "./tools/memory-ingest-extract.js";
+import { memoryIngest } from "./tools/memory-ingest.js";
+import { memoryArchiveWrite } from "./tools/memory-archive-write.js";
+// Task 894: whatsapp-export-{parse,preview,insight-write} deleted. Conversation
+// transcripts now flow through the source-agnostic `conversation-archive` skill
+// + `memory/bin/conversation-archive-ingest.sh`, writing :ConversationArchive
+// + :Section:Conversation chunks via memory-ingest with parentLabel='ConversationArchive'.
+// Task 891: whatsapp-export-insight-pass deleted (Phase 2 deferred).
+import { memoryIngestWeb } from "./tools/memory-ingest-web.js";
+import { memoryClassify } from "./tools/memory-classify.js";
+import { memoryUpdate } from "./tools/memory-update.js";
+import { memoryDelete } from "./tools/memory-delete.js";
+import { memoryFindCandidates } from "./tools/memory-find-candidates.js";
+import { memoryRestore } from "./tools/memory-restore.js";
+import { memoryEmptyTrash } from "./tools/memory-empty-trash.js";
+import { memoryListAttachments } from "./tools/memory-list-attachments.js";
+import { memoryReadAttachment } from "./tools/memory-read-attachment.js";
+import { memoryEditAttachment } from "./tools/memory-edit-attachment.js";
+import { memoryRenameAttachment } from "./tools/memory-rename-attachment.js";
+import { profileRead } from "./tools/profile-read.js";
+import { profileUpdate } from "./tools/profile-update.js";
+import { profileDelete } from "./tools/profile-delete.js";
+import { graphPruneDenylistAdd } from "./tools/graph-prune-denylist-add.js";
+import { graphPruneDenylistList } from "./tools/graph-prune-denylist-list.js";
+import { graphPruneDenylistRemove } from "./tools/graph-prune-denylist-remove.js";
+import { conversationMemoryExpunge } from "./tools/conversation-memory-expunge.js";
+import { conversationArchiveDeriveInsights, } from "./tools/conversation-archive-derive-insights.js";
+import { conversationArchiveEnrichRejection } from "./tools/conversation-archive-enrich-rejection.js";
+import { getSession, closeDriver } from "./lib/neo4j.js";
+import { embed } from "./lib/embeddings.js";
+import { notTrashed } from "../../../../lib/graph-trash/dist/index.js";
+const server = new McpServer({
+    name: "maxy-memory",
+    version: "0.1.0",
+});
+const readOnly = process.env.READ_ONLY === "true";
+const accountId = process.env.ACCOUNT_ID;
+if (!accountId) {
+    throw new Error("ACCOUNT_ID environment variable is required");
+}
+// Load the markdown schema sidecar once at startup. Every memory-write call
+// reads its required-property and synonym maps. If loading fails we throw —
+// a memory server running with a broken schema is worse than one that fails
+// to start loudly.
+const schema = loadSchema();
+// Live label source (Task 736). The memory MCP runs as a separate stdio
+// process from graph-mcp, so it owns its own SchemaCache instance backed by
+// the existing Neo4j driver. The cache refreshes every 60s and tap-fires
+// drift detection from its emit hook. Boot does NOT block on the first
+// refresh — `defaultDeclaredOnly` is sufficient until live joins, since
+// declared labels cover the bootstrap labels (LocalBusiness etc.).
+const schemaCypherPath = defaultSchemaCypherPath();
+const liveSchemaRuntime = buildLiveSchemaSource({
+    schemaCypherPath,
+    markdownLabels: schema.markdownLabels.keys(),
+    fetcher: {
+        async labels() {
+            const session = getSession();
+            try {
+                const result = await session.run("CALL db.labels() YIELD label RETURN label");
+                return result.records
+                    .map((r) => r.get("label"))
+                    .filter((v) => typeof v === "string");
+            }
+            finally {
+                await session.close();
+            }
+        },
+        async relationshipTypes() {
+            const session = getSession();
+            try {
+                const result = await session.run("CALL db.relationshipTypes() YIELD relationshipType RETURN relationshipType");
+                return result.records
+                    .map((r) => r.get("relationshipType"))
+                    .filter((v) => typeof v === "string");
+            }
+            finally {
+                await session.close();
+            }
+        },
+    },
+});
+// Boot drift fires once the first refresh resolves. We do not await — the
+// validator handles boot races by accepting declared labels (which include
+// the bootstrap set) until live joins. Drift logs land in server.log as
+// soon as the snapshot lands, with no impact on serving requests.
+liveSchemaRuntime.ready.then(() => {
+    process.stderr.write(`[schema-validator] using-cache cacheAgeMs=0 ready=${liveSchemaRuntime.source.liveReady()}\n`);
+});
+const validator = {
+    schema,
+    liveSource: liveSchemaRuntime.source,
+};
+const userId = process.env.USER_ID; // Optional — present for admin sessions with users.json auth
+// Scope filtering: comma-separated list of allowed scopes (e.g. "public,shared").
+// When set, memory-search only returns nodes whose scope is in this list.
+// When absent (admin), no scope filtering is applied.
+const allowedScopes = process.env.ALLOWED_SCOPES
+    ? process.env.ALLOWED_SCOPES.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+// Per-handler session resolution (Task 740). Module-load env capture was
+// wrong: when the admin agent didn't set SESSION_ID on MCP spawn, `sessionId`
+// was undefined for the entire process lifetime — every subsequent
+// `createdBySession` write was empty. Read per-handler so the env value
+// (now set in claude-agent.ts:3107 baseEnv) is observed at call time, and
+// allow per-call override via tool argument when an agent has better info.
+function resolveSessionId(override) {
+    if (override && override.trim())
+        return override.trim();
+    const fromEnv = process.env.SESSION_ID;
+    return fromEnv && fromEnv.trim() ? fromEnv.trim() : undefined;
+}
+// Per-agent knowledge scoping: when set, memory-search only returns nodes whose
+// `agents` array contains this slug. For public agents, set via env var (server-level
+// enforcement). For admin queries, passed as an optional tool param.
+const envAgentSlug = process.env.AGENT_SLUG || undefined;
+// Keyword subscriptions: comma-separated list of keywords for BM25-based reactive
+// knowledge inclusion. When set, memory-search runs a BM25 query per keyword and
+// unions results with directly-tagged nodes. Capped at 5 for Pi performance.
+const MAX_KEYWORD_SUBSCRIPTIONS = 5;
+const envKeywordSubscriptions = process.env.KNOWLEDGE_KEYWORDS
+    ? process.env.KNOWLEDGE_KEYWORDS.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean).slice(0, MAX_KEYWORD_SUBSCRIPTIONS)
+    : undefined;
+// Output character budget for memory-search results. Claude Code's tool result token
+// limit is roughly 100K chars; 80K leaves headroom for MCP framing and avoids the
+// dump-to-file cascade that forces multi-step Bash parsing.
+const OUTPUT_CHAR_BUDGET = 80_000;
+/** Format a single search result. When includeRelated is false, related nodes are omitted. */
+function formatResult(r, includeRelated) {
+    let text = `[${r.labels.join(", ")}] (id: ${r.nodeId}) (score: ${r.score.toFixed(3)})\n`;
+    for (const [k, v] of Object.entries(r.properties)) {
+        text += `  ${k}: ${String(v)}\n`;
+    }
+    if (includeRelated && r.related.length > 0) {
+        text += "  Related:\n";
+        for (const rel of r.related) {
+            const arrow = rel.direction === "outgoing" ? `--[${rel.relationship}]-->` : `<--[${rel.relationship}]--`;
+            text += `    ${arrow} [${rel.labels.join(", ")}]`;
+            const relProps = Object.entries(rel.properties)
+                .filter(([k]) => k !== "embedding" && k !== "accountId")
+                .map(([k, v]) => `${k}: ${String(v)}`)
+                .join(", ");
+            if (relProps)
+                text += ` {${relProps}}`;
+            text += "\n";
+        }
+    }
+    return text;
+}
+eagerTool(server, "memory-search", "Search the knowledge graph using semantic vector search with graph traversal. Returns relevant nodes and their relationships.", {
+    query: z.string().describe("Natural language search query"),
+    labels: z
+        .array(z.string())
+        .optional()
+        .describe("Filter by node labels (e.g. Question, Service, DefinedTerm, Review, Person)"),
+    limit: z
+        .number()
+        .optional()
+        .describe("Maximum number of results (default 10)"),
+    expandHops: z
+        .number()
+        .optional()
+        .describe("Graph traversal depth for related nodes (default 1). Use 0 for listing/inventory queries (node properties only, compact output). Use 1 for deep context queries (includes related nodes — can produce large output for nodes with many relationships)."),
+    keywords: z
+        .array(z.string())
+        .optional()
+        .describe("Filter KnowledgeDocument results to those containing these topic keywords"),
+    keywordMatch: z
+        .enum(["any", "all"])
+        .optional()
+        .describe("Keyword match mode: 'any' (default, OR — matches docs with any listed keyword) or 'all' (AND — must have every keyword)"),
+    agentSlug: z
+        .string()
+        .optional()
+        .describe("Filter to nodes tagged for this agent slug (nodes where slug is in the agents array). For admin use — public agents use server-level env var."),
+}, async ({ query, labels, limit, expandHops, keywords, keywordMatch, agentSlug: toolAgentSlug }) => {
+    // Env var takes precedence over tool param (security: public agent server-level enforcement)
+    const effectiveAgentSlug = envAgentSlug ?? toolAgentSlug;
+    try {
+        const results = await memorySearch({
+            query,
+            labels,
+            accountId,
+            limit,
+            expandHops,
+            allowedScopes,
+            keywords,
+            keywordMatch,
+            agentSlug: effectiveAgentSlug,
+            keywordSubscriptions: envKeywordSubscriptions,
+        });
+        if (results.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No results found for this query.",
+                    },
+                ],
+            };
+        }
+        const formatted = results.map((r) => formatResult(r, true));
+        const separator = "\n---\n";
+        let output = formatted.join(separator);
+        let droppedRelated = 0;
+        let droppedResults = 0;
+        if (output.length > OUTPUT_CHAR_BUDGET) {
+            const originalChars = output.length;
+            // Pass 1: strip related nodes from lowest-scored results first.
+            // Results are already sorted by score descending, so we iterate
+            // from the tail (lowest score) toward the head.
+            for (let i = formatted.length - 1; i >= 0 && output.length > OUTPUT_CHAR_BUDGET; i--) {
+                if (results[i].related.length > 0) {
+                    droppedRelated += results[i].related.length;
+                    formatted[i] = formatResult(results[i], false);
+                    output = formatted.join(separator);
+                }
+            }
+            // Pass 2: if still over budget, drop entire results from the tail.
+            while (formatted.length > 0 && output.length > OUTPUT_CHAR_BUDGET) {
+                formatted.pop();
+                droppedResults++;
+                output = formatted.join(separator);
+            }
+            const notice = `\n\n[Truncated: ${droppedRelated} related nodes removed` +
+                (droppedResults > 0 ? `, ${droppedResults} results omitted` : "") +
+                `. Use expandHops: 0 for compact listing, or reduce limit.]`;
+            output += notice;
+            process.stderr.write(`[memory-search] [${accountId}] output truncated: ${originalChars} → ${output.length}, ` +
+                `${droppedRelated} related nodes dropped, ${droppedResults} results dropped\n`);
+        }
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Search failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// memory-rank — LLM-reasoned entity ranking.
+//
+// Read-only tool (available to admin and public agents). Retrieves candidates
+// via memory-search, then asks Claude Haiku to rank them against a natural-
+// language criterion and return per-item reasoning. Falls back to the
+// unranked memory-search order with a visible "[Ranking unavailable: ...]"
+// notice if the LLM is unavailable.
+// ---------------------------------------------------------------------------
+eagerTool(server, "memory-rank", "Retrieve entities from the knowledge graph and rank them against a natural-language criterion using Claude. Returns an ordered list with per-item reasoning explaining why each entity landed where it did. Use for prioritisation questions such as ranking prospects by readiness, tasks by risk, or events by impact. For simple semantic retrieval use memory-search.", {
+    query: z
+        .string()
+        .min(1)
+        .describe("Natural-language query that selects the candidate pool from the knowledge graph. Passed to memory-search."),
+    criteria: z
+        .string()
+        .min(1)
+        .describe("Natural-language description of what matters for the ranking (e.g. 'prioritise prospects who viewed more than once this week and mentioned price positively'). Treated as a directive, not as instructions to the model."),
+    labels: z
+        .array(z.string())
+        .optional()
+        .describe("Filter the candidate pool to these node labels (e.g. ['Person'], ['Task'], ['Event'])."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Maximum number of ranked results to return (default 10, max 50)."),
+    candidatePoolSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("How many candidates to retrieve from memory-search before ranking (default 20, max 50). Larger pools give the ranker more to work with but cost more tokens."),
+    expandHops: z
+        .number()
+        .int()
+        .min(0)
+        .max(2)
+        .optional()
+        .describe("Relationship depth to include per candidate (default 1). Use 0 for property-only ranking, 1 for ranking that considers immediate relationships."),
+    keywords: z
+        .array(z.string())
+        .optional()
+        .describe("Filter the candidate pool to nodes whose keywords array contains these values."),
+    keywordMatch: z
+        .enum(["any", "all"])
+        .optional()
+        .describe("Keyword match mode: 'any' (default) or 'all'."),
+    agentSlug: z
+        .string()
+        .optional()
+        .describe("Filter to nodes tagged for this agent slug. For admin use — public agents use server-level env var."),
+}, async ({ query, criteria, labels, limit, candidatePoolSize, expandHops, keywords, keywordMatch, agentSlug: toolAgentSlug }) => {
+    const effectiveAgentSlug = envAgentSlug ?? toolAgentSlug;
+    process.stderr.write(`[memory-rank] [${accountId}] invocation query=${JSON.stringify(query.slice(0, 60))} criteria=${JSON.stringify(criteria.slice(0, 60))} pool=${candidatePoolSize ?? "default"} limit=${limit ?? "default"}\n`);
+    try {
+        const response = await memoryRank({
+            query,
+            criteria,
+            labels,
+            accountId,
+            limit,
+            candidatePoolSize,
+            expandHops,
+            allowedScopes,
+            keywords,
+            keywordMatch,
+            agentSlug: effectiveAgentSlug,
+            keywordSubscriptions: envKeywordSubscriptions,
+        });
+        // Three distinct empty/near-empty cases with different meanings:
+        //   1. candidatePoolSize === 0 — memory-search found nothing. True empty result.
+        //   2. candidatePoolSize > 0, results.length === 0, no fallback — Haiku
+        //      considered the candidates and said none matched the criterion. The
+        //      agent must be told that candidates existed but were rejected, not
+        //      that nothing was found.
+        //   3. candidatePoolSize > 0, results.length > 0 — normal ranked output
+        //      (or ranked-fallback unranked output when fallbackReason is set).
+        if (response.candidatePoolSize === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No candidates found for this query.",
+                    },
+                ],
+            };
+        }
+        if (response.results.length === 0 && !response.fallbackReason) {
+            // Haiku ran successfully and returned rankings: []. Candidates existed
+            // but none matched the criterion. Report this honestly so the agent
+            // can relay it to the user instead of claiming nothing was found.
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Considered ${response.candidatePoolSize} candidate${response.candidatePoolSize === 1 ? "" : "s"} but none matched the criterion.`,
+                    },
+                ],
+            };
+        }
+        const headerLines = [];
+        if (response.fallbackReason) {
+            headerLines.push(`[Ranking unavailable: ${response.fallbackReason}] — showing ${response.results.length} candidates in their original memory-search score order.`);
+        }
+        else {
+            headerLines.push(`Ranked ${response.results.length} of ${response.candidatePoolSize} candidates.`);
+            if (response.hallucinated > 0) {
+                headerLines.push(`(${response.hallucinated} ranker response${response.hallucinated === 1 ? "" : "s"} referenced candidates not in the pool and were discarded.)`);
+            }
+        }
+        const body = response.results
+            .map((r) => {
+            const rankLine = r.rank !== undefined ? `#${r.rank} ` : "";
+            const reasoningLine = r.reasoning ? `\n  reasoning: ${r.reasoning}` : "";
+            let text = `${rankLine}[${r.labels.join(", ")}] (id: ${r.nodeId}) (score: ${r.score.toFixed(3)})${reasoningLine}\n`;
+            for (const [k, v] of Object.entries(r.properties)) {
+                text += `  ${k}: ${String(v)}\n`;
+            }
+            if (r.related.length > 0) {
+                text += "  Related:\n";
+                for (const rel of r.related) {
+                    const arrow = rel.direction === "outgoing"
+                        ? `--[${rel.relationship}]-->`
+                        : `<--[${rel.relationship}]--`;
+                    text += `    ${arrow} [${rel.labels.join(", ")}]`;
+                    const relProps = Object.entries(rel.properties)
+                        .filter(([k]) => k !== "embedding" && k !== "accountId")
+                        .map(([k, v]) => `${k}: ${String(v)}`)
+                        .join(", ");
+                    if (relProps)
+                        text += ` {${relProps}}`;
+                    text += "\n";
+                }
+            }
+            return text;
+        })
+            .join("\n---\n");
+        const output = `${headerLines.join("\n")}\n\n${body}`;
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[memory-rank] [${accountId}] unhandled error: ${msg}\n`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Rank failed: ${msg}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Task 892 — conversation-archive Phase 2: chunk-anchored insight derivation.
+// Read-only tool. Walks :Section:Conversation chunks of one named
+// :ConversationArchive in pages and asks Haiku (via OAuth) for the
+// high-confidence claims. Returns operator-facing proposals with the cypher
+// needed to wire them; the conversation-archive-enrich skill drives the
+// per-row operator gate. The tool itself NEVER writes; idempotency lives on
+// the MERGE-key shape (chunkElementId, kind, contentHash) encoded in each
+// proposal's mergeCypher.
+// ---------------------------------------------------------------------------
+server.tool("conversation-archive-derive-insights", "Walk the :Section:Conversation chunks of one named :ConversationArchive and emit high-confidence claim proposals (mention, task, preference, observed-relationship). Read-only: the caller drives a per-row operator gate; this tool never writes. Paginates via chunkOffset + chunkLimit (default 5). Operator-triggered, never automatic.", {
+    archiveElementId: z
+        .string()
+        .describe("elementId of the :ConversationArchive the operator named (required)."),
+    chunkOffset: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("Zero-based chunk offset. Default 0. Increase per page."),
+    chunkLimit: z
+        .number()
+        .int()
+        .positive()
+        .max(20)
+        .optional()
+        .describe("Chunks per page (1..20). Default 5 — small pages keep MCP calls under SDK timeout windows."),
+}, async ({ archiveElementId, chunkOffset, chunkLimit }) => {
+    try {
+        const result = await conversationArchiveDeriveInsights({
+            accountId,
+            archiveElementId,
+            chunkOffset,
+            chunkLimit,
+            sessionId: resolveSessionId(),
+        });
+        const proposalLines = result.proposals
+            .map((p, i) => {
+            const disambig = p.disambiguation && p.disambiguation.needsResolution.length > 0
+                ? ` resolve:${p.disambiguation.needsResolution.map((r) => `${r.role}="${r.displayName}"`).join(",")}`
+                : "";
+            return [
+                `Proposal ${i + 1}/${result.proposals.length}:`,
+                `  chunkElementId=${p.chunkElementId}`,
+                `  kind=${p.kind}`,
+                `  contentHash=${p.contentHash}`,
+                `  evidence="${p.evidenceSnippet}"`,
+                `  proposedAction=${p.proposedAction}${disambig}`,
+                `  mergeCypher=${p.mergeCypher.replace(/\n/g, " ")}`,
+                `  mergeParams=${JSON.stringify(p.mergeParams)}`,
+            ].join("\n");
+        })
+            .join("\n\n");
+        const header = `archiveElementId=${result.archiveElementId} title=${JSON.stringify(result.archiveTitle ?? "")} totalChunks=${result.totalChunks} walked=${result.walkedFrom}..${result.walkedTo} proposals=${result.proposals.length} proposalsRemaining=${result.proposalsRemaining} emptyChunks=${result.emptyChunkElementIds.length}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.proposals.length === 0
+                        ? `${header}\n(no high-confidence claims in this page; advance chunkOffset to walk further)`
+                        : `${header}\n\n${proposalLines}`,
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: msg }],
+            isError: true,
+        };
+    }
+});
+process.stderr.write("[memory-mcp] registered tool=conversation-archive-derive-insights\n");
+// ---------------------------------------------------------------------------
+// Task 980 — durable rejection memory for conversation-archive-enrich.
+// Writes to a sidecar JSONL alongside the account's state directory; the
+// filter step in conversation-archive-derive-insights reads the same file.
+// Modes:
+//   record — append rejection line (idempotent on duplicate keys).
+//   undo   — drop matching line via atomic-rename (called after a `wire`
+//            so a later wire of a once-rejected key cleans up its rejection).
+// ---------------------------------------------------------------------------
+server.tool("conversation-archive-enrich-rejection", "Record or undo a per-row rejection from conversation-archive-enrich. Writes a sidecar JSONL keyed on (chunkElementId, kind, contentHash). Call with mode='record' on operator `reject`; call with mode='undo' after a successful `wire` so a later wire of a once-rejected key clears its rejection. Idempotent: duplicate records are no-ops.", {
+    archiveElementId: z
+        .string()
+        .describe("elementId of the :ConversationArchive (carried on each line for diagnostics)."),
+    chunkElementId: z
+        .string()
+        .describe("elementId of the :Section:Conversation chunk the rejection applies to."),
+    kind: z
+        .string()
+        .describe("Proposal kind — one of mention|task|preference|observed-relationship."),
+    contentHash: z
+        .string()
+        .describe("The proposal's contentHash (sha256 over kind + payload)."),
+    mode: z
+        .enum(["record", "undo"])
+        .describe("record = append rejection; undo = remove rejection (called after `wire`)."),
+}, async ({ archiveElementId, chunkElementId, kind, contentHash, mode }) => {
+    try {
+        const result = conversationArchiveEnrichRejection({
+            accountId,
+            archiveElementId,
+            chunkElementId,
+            kind,
+            contentHash,
+            mode,
+            sessionId: resolveSessionId(),
+        });
+        const summary = `mode=${result.mode} beforeCount=${result.beforeCount} afterCount=${result.afterCount} path=${result.path}`;
+        return {
+            content: [{ type: "text", text: summary }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[conversation-archive-enrich] rejection-tool-fail mode=${mode} chunk=${chunkElementId} reason="${msg}"\n`);
+        return {
+            content: [{ type: "text", text: msg }],
+            isError: true,
+        };
+    }
+});
+process.stderr.write("[memory-mcp] registered tool=conversation-archive-enrich-rejection\n");
+if (!readOnly) {
+    eagerTool(server, "memory-write", "Create a new node in the knowledge graph with automatic embedding computation. Every node must be created with at least one relationship — call memory-search first to find target elementIds. Writes targeting :Person, :UserProfile, :AdminUser, :Organization, :LocalBusiness, :CloudflareTunnel, or :CloudflareHostname additionally require an inbound :PRODUCED edge from :Task, :Conversation, or :Message. For autonomous workflows that own a :Task lifecycle, pass the Task's elementId as `producedByTaskId`. For direct asks during a conversation, omit `producedByTaskId` — the platform auto-injects the edge from the active conversation.", {
+        labels: z
+            .array(z.string())
+            .describe("Node labels (e.g. ['Person'], ['Question'], ['DefinedTerm'])"),
+        properties: z
+            .record(z.string(), z.unknown())
+            .describe("Node properties as key-value pairs"),
+        scope: z
+            .string()
+            .describe("Visibility scope — required. Valid values: 'public', 'shared', 'admin', or 'user:{identifier}'."),
+        relationships: z
+            .array(z.object({
+            type: z.string().describe("Relationship type (e.g. HAS_PRICING, OFFERS)"),
+            direction: z.enum(["outgoing", "incoming"]),
+            targetNodeId: z.string().describe("Element ID of the target node"),
+        }))
+            .min(1)
+            .describe("Relationships to create with existing nodes. At least one is required — a node without an adjacency is noise, not knowledge."),
+        producedByTaskId: z
+            .string()
+            .optional()
+            .describe("Active Task elementId for autonomous-workflow writes. When set, an inbound :PRODUCED edge from this Task is composed into relationships before the write. Task must share the same accountId; mismatch is rejected. Omit for direct conversation asks — the platform composes the edge from the active conversation instead."),
+    }, async ({ labels, properties, scope, relationships, producedByTaskId }) => {
+        try {
+            const result = await memoryWrite({
+                labels,
+                properties: properties,
+                accountId,
+                scope,
+                relationships,
+                createdBy: {
+                    agent: envAgentSlug,
+                    session: resolveSessionId(),
+                    tool: "memory-write",
+                },
+                validator,
+                producedByTaskId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Node created: [${result.labels.join(", ")}] (ID: ${result.nodeId})`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Write failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-update", "Update properties on an existing node in the knowledge graph. Finds the node by element ID, verifies account ownership, sets the provided properties, and recomputes the embedding.", {
+        nodeId: z.string().describe("Element ID of the node to update (from memory-search results)"),
+        properties: z
+            .record(z.string(), z.unknown())
+            .describe("Properties to set or overwrite. Restricted keys (embedding, accountId, createdAt) are ignored."),
+    }, async ({ nodeId, properties }) => {
+        try {
+            const result = await memoryUpdate({
+                nodeId,
+                properties: properties,
+                accountId,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Node updated: [${result.labels.join(", ")}] (ID: ${result.nodeId})`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Update failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    eagerTool(server, "session-compact-status", "Check whether a session compaction summary exists in the graph. Returns the most recent summary title, date, and briefing text. Use this at session start to determine whether a prior session was compacted and its context should be restored.", {}, async () => {
+        const session = getSession();
+        try {
+            const result = await session.run(`MATCH (n:CreativeWork {accountId: $accountId})
+           WHERE n.title STARTS WITH 'Session Summary'
+           RETURN n.title AS title, n.createdAt AS createdAt, n.abstract AS abstract
+           ORDER BY n.createdAt DESC LIMIT 1`, { accountId });
+            if (result.records.length === 0) {
+                return { content: [{ type: "text", text: "No session summaries found." }] };
+            }
+            const r = result.records[0];
+            const text = `Title: ${r.get("title")}\nDate: ${r.get("createdAt")}\n\n${r.get("abstract")}`;
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `session-compact-status failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+        finally {
+            await session.close();
+        }
+    });
+    eagerTool(server, "session-compact", "Write a session summary to the knowledge graph. Call this when compacting context — provide the full briefing and the tool handles labelling, structure, and embedding.", {
+        content: z.string().describe("The session briefing — what was discussed, decisions made, work in progress, open questions, and anything learned about the user or their business"),
+    }, async ({ content }) => {
+        try {
+            // Write doctrine (Task 673): session summaries link back to the
+            // Conversation they summarise, so an operator searching a session's
+            // graph sees the summary hanging off its source. Hard-require
+            // SESSION_ID — the previous revision fell back to "most recent
+            // admin Conversation" which would cross-attach a summary to an
+            // unrelated session hours later (reviewer flagged this as silent
+            // provenance corruption).
+            const sessionIdForCompact = resolveSessionId();
+            if (!sessionIdForCompact) {
+                throw new Error("session-compact requires SESSION_ID — the tool must be invoked inside an admin session so the summary can link back to its Conversation.");
+            }
+            const lookupSession = getSession();
+            let conversationElementId = null;
+            try {
+                const r = await lookupSession.run(`MATCH (c:Conversation {sessionKey: $sessionId, accountId: $accountId}) RETURN elementId(c) AS id LIMIT 1`, { sessionId: sessionIdForCompact, accountId });
+                if (r.records.length > 0) {
+                    conversationElementId = r.records[0].get("id");
+                }
+            }
+            finally {
+                await lookupSession.close();
+            }
+            if (!conversationElementId) {
+                throw new Error(`session-compact: no Conversation found with sessionKey=${sessionIdForCompact} in this account. Cannot link summary — refuse rather than create an orphan.`);
+            }
+            const title = `Session Summary ${new Date().toISOString().slice(0, 10)}`;
+            const result = await memoryWrite({
+                labels: ["CreativeWork"],
+                properties: { title, abstract: content },
+                accountId,
+                scope: "admin",
+                relationships: [
+                    {
+                        type: "SUMMARIZES",
+                        direction: "outgoing",
+                        targetNodeId: conversationElementId,
+                    },
+                ],
+                createdBy: {
+                    agent: envAgentSlug,
+                    session: sessionIdForCompact,
+                    tool: "session-compact",
+                },
+                validator,
+            });
+            return {
+                content: [{ type: "text", text: `Session summary saved (ID: ${result.nodeId})` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `session-compact failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    eagerTool(server, "memory-reindex", "Rebuild vector embeddings for all nodes missing embeddings. Run after seeding or bulk updates.", {}, async () => {
+        try {
+            const result = await memoryReindex(accountId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Reindex complete: ${result.nodesProcessed} processed, ${result.nodesSkipped} skipped, ${result.scopeBackfilled} scope backfilled.${result.errors.length > 0 ? `\nErrors: ${result.errors.join("; ")}` : ""}`,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            console.error("[memory-reindex] failed:", err instanceof Error ? err.message : String(err));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Reindex failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-ingest-extract", "Extract text from an uploaded file and cache it server-side for memory-classify and memory-ingest. " +
+        "Supports PDF (via pdftotext), plain text, and markdown. " +
+        "Rejects CSV (structured data — use memory-write instead) and images (metadata-only). " +
+        "Returns file metadata + a short preview; the full text lives in the in-process cache keyed by attachmentId. " +
+        "Chunking has moved upstream into memory-classify (LLM-driven section classification) — this tool no longer chunks.", {
+        storagePath: z.string().describe("Absolute path to the stored file on disk"),
+        filename: z.string().describe("Original filename as uploaded"),
+        mimeType: z.string().describe("MIME type of the file"),
+        attachmentId: z.string().describe("UUID of the file attachment — used as cache key for memory-ingest"),
+    }, async ({ storagePath, filename, mimeType, attachmentId }) => {
+        try {
+            const result = await memoryIngestExtract({ storagePath, filename, mimeType, attachmentId });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(result),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-ingest-extract failed for "${filename}": ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-classify", "Classify an unstructured document into typed sections via Claude Haiku. " +
+        "Reads the cached text written by memory-ingest-extract (same attachmentId), runs the classifier against " +
+        "the live ontology label set, and returns a JSON structure ready for memory-ingest. Every returned `kind` is " +
+        "verified server-side against the ontology — invalid labels become `UNMAPPED` so the writer falls back to " +
+        "generic Section nodes with a logged ontology gap. When Haiku is unavailable, returns `{kind: \"fallback\"}` " +
+        "with a reason — the skill should treat the whole document as one UNMAPPED Section.", {
+        attachmentId: z.string().describe("UUID of the file attachment — must match a prior memory-ingest-extract call"),
+        anchorDescription: z.string().describe("Short human sentence describing the document subject the classifier should anchor sections to. " +
+            "Examples: 'subject = UserProfile (the account owner)'; 'subject = LocalBusiness (the operator's business)'; " +
+            "'subject = Person {name: \"Jane Smith\"} (a third party)'."),
+    }, async ({ attachmentId, anchorDescription }) => {
+        try {
+            const result = await memoryClassify({
+                accountId,
+                attachmentId,
+                anchorDescription,
+                liveSchemaSource: liveSchemaRuntime.source,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(result),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-classify failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-ingest", "Write a classified document into the graph as typed nodes anchored to the document subject. " +
+        "Requires prior calls to memory-ingest-extract (text cache) and memory-classify (typed structure). " +
+        "Each section becomes either a typed graph node (Position, Service, Credential, etc.) anchored to the named " +
+        "subject via the natural ontology edge plus a (KnowledgeDocument)-[:REFERENCES]->(typed) link, or — for " +
+        "UNMAPPED sections — a generic :Section node hanging off the document via HAS_SECTION (legacy fallback). " +
+        "Re-ingesting with the same attachmentId replaces the document's typed and untyped children — safe to call " +
+        "on already-ingested documents. Shared related entities (Organizations, Persons referenced by typed nodes) " +
+        "are MERGEd by identifying property and never deleted on re-ingest.", {
+        attachmentId: z.string().describe("UUID of the file attachment — must match a prior memory-ingest-extract call"),
+        documentSummary: z.string().describe("Classifier-produced summary of the entire document (1-3 sentences)"),
+        anchorNodeId: z.string().describe("Element ID of the anchor node (UserProfile/LocalBusiness/Person/Organization). The document subject " +
+            "the operator confirmed during the document-ingest skill's first step."),
+        anchorLabel: z.string().describe("Primary label of the anchor node (e.g. 'UserProfile', 'LocalBusiness'). Used in the per-section MATCH " +
+            "for anchor-edge creation."),
+        sections: z.array(z.object({
+            kind: z.string().describe("Section kind from the closed enumeration (Position/Education/Chapter/Parties/.../Other), or a standalone-node kind like 'Project'."),
+            title: z.string(),
+            body: z.string().describe("Server-reconstructed body text: memory-classify slices documentText.slice(sourceStart, sourceEnd) and stamps it here, so this stays the writer's contract."),
+            summary: z.string().describe("1-3 sentence summary of the section — already truncated to 500 chars by memory-classify; stored as :Section.summary."),
+            sourceStart: z.number().int().nonnegative().describe("Whole-document char offset where the section begins (inclusive). Translated to whole-doc coords by the chunked-classify path."),
+            sourceEnd: z.number().int().nonnegative().describe("Whole-document char offset where the section ends (exclusive)."),
+            properties: z.record(z.string(), z.unknown()),
+            anchorEdge: z.object({
+                type: z.string(),
+                direction: z.enum(["from-anchor", "to-anchor"]),
+                properties: z.record(z.string(), z.unknown()).optional(),
+            }).nullable(),
+            related: z.array(z.object({
+                kind: z.string(),
+                properties: z.record(z.string(), z.unknown()),
+                edge: z.object({
+                    type: z.string(),
+                    direction: z.enum(["outgoing", "incoming"]),
+                    properties: z.record(z.string(), z.unknown()).optional(),
+                }),
+                merge: z.boolean().optional(),
+            })).optional(),
+            classifierReason: z.string().optional().describe("Required when kind === 'Other' — one-line description of what the section is about, stamped on :Section:Other.classifierReason for ontology-growth review."),
+        })).describe("Sections as returned by memory-classify, in reading order. The writer chains them via :NEXT in this order."),
+        documentEdges: z.array(z.object({
+            type: z.string(),
+            direction: z.enum(["outgoing", "incoming"]),
+            targetKind: z.string(),
+            targetProperties: z.record(z.string(), z.unknown()),
+            merge: z.boolean().optional(),
+        })).optional().describe("Document-level edges (e.g. PARTY edges off KnowledgeDocument for a contract). Currently emitted by the classifier when a Parties section is detected."),
+        orphanCandidates: z.array(z.object({
+            kind: z.string(),
+            label: z.string(),
+            reason: z.string(),
+        })).optional().describe("Orphan candidates from the classifier — nodes the classifier could not edge naturally. NOT written to the graph; the skill surfaces these to the operator loudly so they decide whether the orphan is intentional (rare, valid) or a classifier miss (bug)."),
+        scope: z.string().describe("Visibility scope for all created nodes — required. Valid values: 'public', 'shared', 'admin', or 'user:{identifier}'."),
+        sourceUrl: z.string().optional().describe("Original URL for web-sourced documents. Omit for file uploads."),
+        sourceType: z.string().optional().describe("Provenance: 'upload' or 'web'."),
+        documentKeywords: z.array(z.string()).optional().describe("Classifier-extracted topic keywords."),
+        userKeywords: z.array(z.string()).optional().describe("Keywords explicitly provided by the user. Merged additively with documentKeywords."),
+        sessionId: z.string().optional().describe("Session UUID for provenance stamping. Optional override; the server falls back to the SESSION_ID env var set by the admin agent at MCP spawn. The agent only needs to pass this when calling outside the normal admin-session context."),
+    }, async ({ attachmentId, documentSummary, anchorNodeId, anchorLabel, sections, documentEdges, orphanCandidates, scope, sourceUrl, sourceType, documentKeywords, userKeywords, sessionId: sessionIdOverride }) => {
+        try {
+            const result = await memoryIngest({
+                accountId,
+                attachmentId,
+                documentSummary,
+                anchorNodeId,
+                anchorLabel,
+                sections,
+                documentEdges,
+                orphanCandidates,
+                scope,
+                sourceUrl,
+                sourceType,
+                documentKeywords,
+                userKeywords,
+                sessionId: resolveSessionId(sessionIdOverride),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            documentNodeId: result.documentNodeId,
+                            sectionCount: result.sectionCount,
+                            kindBreakdown: result.kindBreakdown,
+                            edgeBreakdown: result.edgeBreakdown,
+                            relatedCount: result.relatedCount,
+                            standaloneCount: result.standaloneCount,
+                            orphanCandidates: result.orphanCandidates,
+                            documentSummary: result.documentSummary,
+                            keywords: result.keywords,
+                        }),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-ingest failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    eagerTool(server, "memory-archive-write", "Bulk-archive write surface for flat datasets. " +
+        "Writes typed entities + natural edges in 500-row UNWIND batches. The Cypher body is fixed " +
+        "server-side per `archiveType`; the agent supplies parsed rows + the discriminant, never " +
+        "raw Cypher. Use ONLY for flat first-class entity exports (LinkedIn Connections.csv and " +
+        "future CRM-type seeds). Conversation transcripts (WhatsApp, Telegram, Signal, …) flow " +
+        "through the `conversation-archive` skill (memory/bin/conversation-archive-ingest.sh) " +
+        "instead, which writes :ConversationArchive + :Section:Conversation chunks via memory-ingest. " +
+        "Currently supported archiveType values: `linkedin-connections`.", {
+        archiveType: z
+            .enum(["linkedin-connections"])
+            .describe("Discriminant naming the per-source schema and Cypher body the server runs. Add a new value here only when the corresponding handler is added in memory-archive-write.ts."),
+        ownerNodeId: z
+            .string()
+            .min(1)
+            .describe("elementId of the archive owner — :AdminUser for an operator's own archive, or :Person for an external-archive owner. Confirmed during the skill's owner-confirmation flow before this tool is invoked."),
+        rows: z
+            .array(z.record(z.string(), z.unknown()))
+            .min(1)
+            .describe("Parsed rows. The skill's selective-ingest gate runs BEFORE this tool — large blanket archives get filtered (Company / Position / Connected On range for linkedin-connections) before the write call."),
+        sessionId: z
+            .string()
+            .optional()
+            .describe("Skill-run UUID for provenance stamping. Falls back to SESSION_ID env var when absent."),
+    }, async ({ archiveType, ownerNodeId, rows, sessionId: sessionIdOverride }) => {
+        try {
+            const result = await memoryArchiveWrite({
+                archiveType,
+                ownerNodeId,
+                accountId,
+                rows: rows,
+                sessionId: resolveSessionId(sessionIdOverride),
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(result),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-archive-write failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // Task 891 retired the `whatsapp-export-insight-pass` Phase-2 tool; Task 894
+    // generalised the entire conversation-archive ingest path (no longer
+    // WhatsApp-specific) — see `memory/skills/conversation-archive/` and
+    // `memory/bin/conversation-archive-ingest.{mjs,sh}`. Phase-2 insight
+    // derivation will operate on :Section:Conversation chunks regardless of
+    // source.
+    server.tool("memory-ingest-web", "Adapter for web-content ingestion. Accepts a URL and its pre-fetched readable content " +
+        "(the agent calls WebFetch first, then passes the text here), writes content to a temp file, and delegates " +
+        "to memory-ingest-extract — caching the text under a freshly-generated attachmentId. The skill then drives " +
+        "memory-classify and memory-ingest using that attachmentId, exactly as for a file upload. " +
+        "If the URL was previously ingested, returns the existing document info so the agent can inform the user.", {
+        url: z.string().describe("The web page URL being ingested"),
+        content: z.string().describe("The readable text content of the web page (pre-fetched by the agent via WebFetch)"),
+        scope: z.string().optional().describe("Intended visibility scope (for logging). The actual scope is set when the agent subsequently calls memory-ingest."),
+    }, async ({ url, content, scope }) => {
+        try {
+            const result = await memoryIngestWeb({
+                accountId,
+                url,
+                content,
+                scope,
+            });
+            const response = {
+                attachmentId: result.attachmentId,
+                title: result.title,
+                sourceUrl: url,
+                sourceType: "web",
+                ...result.extract,
+            };
+            if (result.existingDocument) {
+                response.existingDocument = result.existingDocument;
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify(response),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `memory-ingest-web failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-find-candidates", "Deterministic bulk-delete selector for Conversation nodes. Returns a structured list of candidates " +
+        "matching a fixed-name filter ('empty' = zero :PART_OF messages; 'single-assistant' = exactly one " +
+        "assistant-role message) and an opaque filterToken. Pair with memory-delete(filterToken=…) — the server " +
+        "re-runs the same predicate per elementId before trashing, so a stale or forged token never deletes. " +
+        "Never author custom delete-selection Cypher for bulk flows; always use this tool.", {
+        filter: z.enum(["empty", "single-assistant"]).describe("Selection predicate. 'empty' = no :PART_OF Messages. 'single-assistant' = exactly one :PART_OF " +
+            "Message with role='assistant'. A content-matching filter ('no-real-user-input') is not yet available."),
+        agentType: z.enum(["admin", "public"]).optional().describe("Scope to conversations matching c.agentType. Omit to scope across both."),
+        limit: z.number().int().positive().optional().describe("Max candidates to return (default 200, hard cap 1000)."),
+        dryRun: z.boolean().optional().describe("Preview matches without minting an actionable filterToken. Candidates are listed in the response, but no delete can be performed against them — caller must re-run without dryRun to receive a token."),
+    }, async ({ filter, agentType, limit, dryRun }) => {
+        try {
+            const result = await memoryFindCandidates({ accountId, filter, agentType, limit, dryRun });
+            if (result.items.length === 0) {
+                return { content: [{ type: "text", text: `No candidates matched filter=${filter} agentType=${agentType ?? "any"}. No delete will happen.` }] };
+            }
+            const tokenLine = result.dryRun
+                ? "filterToken=(none — dryRun; re-run without dryRun to get an actionable token)"
+                : `filterToken=${result.filterToken}`;
+            const trailer = result.dryRun
+                ? "This is a dryRun preview. No delete can be performed until you re-run without dryRun."
+                : "Pass each elementId to memory-delete with the filterToken above. The server re-verifies on every call.";
+            const lines = [
+                `Matched ${result.matched} candidate(s) for filter=${filter} agentType=${agentType ?? "any"}.`,
+                tokenLine,
+                "",
+                trailer,
+                "",
+                ...result.items.map((i) => {
+                    const preview = i.firstUserMsgPreview ? ` userPreview=${JSON.stringify(i.firstUserMsgPreview)}` : "";
+                    return `- elementId=${i.elementId} conversationId=${i.conversationId ?? "null"} assistantMsgs=${i.assistantMsgCount} realUserMsgs=${i.realUserMsgCount}${preview}`;
+                }),
+            ];
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-find-candidates failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-delete", "Soft-delete a single graph node by elementId. Adds the :Trashed label, preserves relationships, " +
+        "and excludes the node from memory-search and any read filtered via notTrashed. For KnowledgeDocument, " +
+        "cascades to linked Section and Chunk children. For Conversation, cascades to attached :PART_OF Messages " +
+        ". Hard removal happens later via memory-empty-trash after the grace period (default 30 days). " +
+        "For bulk-delete flows, pass filterToken from memory-find-candidates — the server re-verifies the predicate " +
+        "before trashing. For GDPR Right-to-Erasure, use contact-erase instead (bypasses this primitive and " +
+        "hard-deletes per Article 17).", {
+        elementId: z.string().describe("Neo4j elementId of the node to trash (from memory-search or memory-find-candidates)."),
+        reason: z.string().optional().describe("Optional human-readable explanation; persisted as trashReason for audit."),
+        filterToken: z.string().optional().describe("Opaque token from memory-find-candidates. Required for bulk-selector flows; the server re-runs the " +
+            "canonical predicate on this elementId before trashing. Omit for single-node deletes where the caller " +
+            "chose the target directly (e.g. from a memory-search result)."),
+    }, async ({ elementId, reason, filterToken }) => {
+        try {
+            const result = await memoryDelete({ accountId, elementId, reason, filterToken });
+            const head = result.alreadyTrashed
+                ? `Already trashed: [${result.labels.join(", ")}] elementId=${elementId}`
+                : `Trashed: [${result.labels.join(", ")}] elementId=${elementId}`;
+            const cascade = result.cascade.sections + result.cascade.chunks > 0
+                ? `\nCascaded: ${result.cascade.sections} sections, ${result.cascade.chunks} chunks.`
+                : "";
+            const trail = result.alreadyTrashed
+                ? ""
+                : `\nTrashed at ${result.trashedAt}. Restore via memory-restore; hard removal after grace period via memory-empty-trash.`;
+            return { content: [{ type: "text", text: `${head}${cascade}${trail}` }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-delete failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-restore", "Undo memory-delete on a single graph node by elementId. Removes the :Trashed label and restores " +
+        "snapshotted unique-key properties. For KnowledgeDocument, walks HAS_SECTION/HAS_CHUNK edges to bring " +
+        "trashed children back too. Fails loudly when an active node already holds a unique slot the trashed " +
+        "node needs back (e.g. a fresh OnboardingState was created while the old one was in trash) — " +
+        "the error names the conflicting elementId so the caller can decide how to resolve.", {
+        elementId: z.string().describe("Neo4j elementId of the trashed node to restore."),
+    }, async ({ elementId }) => {
+        try {
+            const result = await memoryRestore({ accountId, elementId });
+            const cascade = result.cascade.sections + result.cascade.chunks > 0
+                ? `\nCascaded: ${result.cascade.sections} sections, ${result.cascade.chunks} chunks.`
+                : "";
+            return {
+                content: [{
+                        type: "text",
+                        text: `Restored: [${result.labels.join(", ")}] elementId=${elementId}${cascade}`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-restore failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-empty-trash", "Hard-delete trashed nodes whose trashedAt is older than the grace period (default 30 days). " +
+        "For KnowledgeDocument candidates, also removes the on-disk attachment directory. Use dryRun=true " +
+        "to preview candidates without mutating — the absence of [trash:emptied] log lines after a " +
+        "[trash:empty-run] dryRun=true line is the correct-behaviour signal. Optional labels filter " +
+        "restricts the sweep to a subset of node types (e.g. ['Person']).", {
+        graceDays: z.number().int().min(0).optional().describe("Minimum age in days a trashed node must reach before it's eligible. Default 30."),
+        dryRun: z.boolean().optional().describe("When true, lists candidates without deleting. Default false."),
+        labels: z.array(z.string()).optional().describe("Optional whitelist of node labels — only nodes carrying any of these labels are eligible."),
+    }, async ({ graceDays, dryRun, labels }) => {
+        try {
+            const result = await memoryEmptyTrash({ accountId, graceDays, dryRun, labels });
+            const lines = [];
+            lines.push(`Empty-trash run: graceDays=${result.graceDays} dryRun=${result.dryRun} candidates=${result.candidates.length} emptied=${result.emptied} attachmentDirsRemoved=${result.attachmentDirsRemoved}`);
+            if (result.candidates.length > 0 && result.candidates.length <= 25) {
+                for (const c of result.candidates) {
+                    lines.push(`  - [${c.labels.join(", ")}] elementId=${c.elementId} trashedAt=${c.trashedAt} by=${c.trashedBy ?? "unknown"}`);
+                }
+            }
+            else if (result.candidates.length > 25) {
+                lines.push(`  (${result.candidates.length} candidates — too many to list; grep [trash:empty-run]/[trash:emptied] in server.log for detail)`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-empty-trash failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-list-attachments", "List stored file attachments for this account with their ingestion status. " +
+        "Returns original filenames, sizes, upload dates, and whether each file has been ingested " +
+        "into the knowledge graph. Does not include web-ingested documents (those have no file on disk).", {}, async () => {
+        try {
+            const result = await memoryListAttachments(accountId);
+            if (result.entries.length === 0) {
+                return { content: [{ type: "text", text: "No stored attachments found." }] };
+            }
+            const lines = result.entries.map((e) => {
+                const status = e.softDeleted
+                    ? "deleted (pending purge)"
+                    : e.ingested
+                        ? "ingested"
+                        : "not ingested";
+                const size = e.sizeBytes < 1024
+                    ? `${e.sizeBytes} B`
+                    : e.sizeBytes < 1024 * 1024
+                        ? `${(e.sizeBytes / 1024).toFixed(1)} KB`
+                        : `${(e.sizeBytes / (1024 * 1024)).toFixed(1)} MB`;
+                const idLine = e.elementId
+                    ? `  ID: ${e.attachmentId}  elementId: ${e.elementId}  Stored: ${e.storedAt}`
+                    : `  ID: ${e.attachmentId}  Stored: ${e.storedAt}`;
+                return `${e.filename}  (${e.mimeType}, ${size})  [${status}]\n${idLine}`;
+            });
+            const summary = `${result.totalFiles} files (${result.ingestedCount} ingested${result.skippedCount > 0 ? `, ${result.skippedCount} skipped` : ""})`;
+            return {
+                content: [{ type: "text", text: `${summary}\n\n${lines.join("\n\n")}` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-list-attachments failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-read-attachment", "Read the content of a stored attachment from disk. Returns the full text for text/markdown files, " +
+        "extracted text for PDFs (via pdftotext), and metadata + HTTP URL for images. " +
+        "Use this to show the user what's in a file or to prepare content for editing.", {
+        attachmentId: z.string().describe("UUID of the attachment to read"),
+    }, async ({ attachmentId }) => {
+        try {
+            const result = await memoryReadAttachment(accountId, attachmentId);
+            let text = `**${result.filename}** (${result.mimeType}, ${result.sizeBytes} bytes)\nStored: ${result.storedAt}\n`;
+            if (result.contentNote)
+                text += `\n_${result.contentNote}_\n`;
+            if (result.httpUrl)
+                text += `\nURL: ${result.httpUrl}\n`;
+            if (result.content)
+                text += `\n---\n\n${result.content}`;
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-read-attachment failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-edit-attachment", "Edit a stored text/markdown attachment in place. Replaces the file content on disk, updates the " +
+        "metadata timestamp, and re-extracts the file for chunking (populating the extract cache). " +
+        "After this call, use memory-ingest with updated summaries to sync the knowledge graph. " +
+        "Only text/plain and text/markdown files are editable — PDFs and images are rejected.", {
+        attachmentId: z.string().describe("UUID of the attachment to edit"),
+        content: z.string().describe("The full replacement text content"),
+    }, async ({ attachmentId, content }) => {
+        try {
+            const result = await memoryEditAttachment({ accountId, attachmentId, content });
+            let text = `Edited: ${result.filename} (${result.oldSizeBytes} → ${result.newSizeBytes} bytes)`;
+            if (result.cachePopulated) {
+                text += `\nExtract cache populated: ${result.extractTextLength} chars.`;
+                text += `\nCall memory-classify and memory-ingest to re-sync the knowledge graph.`;
+            }
+            else {
+                text += `\nWARNING: File updated on disk but extract cache could not be populated.`;
+                text += `\nCall memory-ingest-extract manually, then memory-classify, then memory-ingest.`;
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-edit-attachment failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("memory-rename-attachment", "Rename a stored attachment. Updates the filename in the .meta.json sidecar and the " +
+        "KnowledgeDocument name in Neo4j (if the file has been ingested). The file on disk " +
+        "is not renamed — it uses UUID-based naming. Only the human-readable metadata changes.", {
+        attachmentId: z.string().describe("UUID of the attachment to rename"),
+        newFilename: z.string().describe("The new filename (e.g. 'quarterly-report-q1.pdf')"),
+    }, async ({ attachmentId, newFilename }) => {
+        try {
+            const result = await memoryRenameAttachment({ accountId, attachmentId, newFilename });
+            if (result.oldFilename === result.newFilename) {
+                return { content: [{ type: "text", text: `Filename unchanged: "${result.newFilename}"` }] };
+            }
+            let text = `Renamed: "${result.oldFilename}" → "${result.newFilename}"`;
+            text += result.graphUpdated
+                ? `\nKnowledge graph updated.`
+                : `\nNo KnowledgeDocument in graph (file not yet ingested — metadata only).`;
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-rename-attachment failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    // --- conversation-list formatting helpers ---
+    /** Strip Neo4j DateTime timezone ID bracket (e.g. "[UTC]", "[Europe/London]") that Date.parse rejects. */
+    function cleanNeo4jIso(isoStr) {
+        return isoStr.replace(/\[.*\]$/, "");
+    }
+    /** Format an ISO timestamp to short human-readable form: "YYYY-MM-DD HH:MM UTC". Empty string if invalid. */
+    function shortIso(isoStr) {
+        if (!isoStr)
+            return "";
+        const ms = Date.parse(cleanNeo4jIso(isoStr));
+        if (!Number.isFinite(ms))
+            return "";
+        return new Date(ms).toISOString().replace("T", " ").slice(0, 16) + " UTC";
+    }
+    /** Compute relative time string from an ISO timestamp. Returns null for >= 7 days or invalid input. */
+    function relativeTime(isoStr) {
+        if (!isoStr)
+            return null;
+        const ms = Date.parse(cleanNeo4jIso(isoStr));
+        if (!Number.isFinite(ms))
+            return null;
+        const diffMs = Date.now() - ms;
+        if (diffMs < 60_000)
+            return "just now"; // includes future timestamps (clock drift)
+        const mins = Math.floor(diffMs / 60_000);
+        if (mins < 60)
+            return `${mins}m ago`;
+        const hours = Math.floor(mins / 60);
+        if (hours < 24)
+            return `${hours}h ago`;
+        const days = Math.floor(hours / 24);
+        if (days < 7)
+            return `${days}d ago`;
+        return null;
+    }
+    /** Format conversation header line with activity timestamps. Shared across metadata and inline modes. */
+    function formatConversationHeader(opts) {
+        const label = opts.name ? `"${opts.name}"` : opts.conversationId.slice(0, 8) + "…";
+        const agentInfo = opts.agentSlug ? `${opts.agentType}/${opts.agentSlug}` : opts.agentType;
+        const createdStr = shortIso(opts.createdAt) || "(no timestamp)";
+        const updatedStr = shortIso(opts.updatedAt);
+        if (!updatedStr) {
+            return `${label} [${agentInfo}] · created ${createdStr} · (activity unknown) — ${opts.messageCount} messages`;
+        }
+        const createdMs = Date.parse(cleanNeo4jIso(opts.createdAt));
+        const updatedMs = Date.parse(cleanNeo4jIso(opts.updatedAt));
+        if (Number.isFinite(createdMs) && Number.isFinite(updatedMs) && Math.abs(updatedMs - createdMs) < 1000) {
+            const ago = relativeTime(opts.updatedAt);
+            const agoStr = ago ? ` (${ago})` : "";
+            return `${label} [${agentInfo}] · created ${createdStr}${agoStr} — ${opts.messageCount} messages`;
+        }
+        const ago = relativeTime(opts.updatedAt);
+        const agoStr = ago ? ` (${ago})` : "";
+        return `${label} [${agentInfo}] · created ${createdStr} · active ${updatedStr}${agoStr} — ${opts.messageCount} messages`;
+    }
+    server.tool("conversation-list", "List conversations or retrieve messages from a specific conversation. " +
+        "Without conversationId: lists all conversations with message counts, ordered by most recent activity (updatedAt DESC). " +
+        "Headers show both creation time and last activity time; when they differ, the conversation was resumed. " +
+        "With conversationId: returns all messages in that conversation chronologically with per-message timestamps. " +
+        "With includeMessages: returns conversations with their timestamped messages inline (useful for batch review). " +
+        "The since filter matches against activity time (updatedAt), not creation time.", {
+        conversationId: z
+            .string()
+            .optional()
+            .describe("If provided, returns messages for this conversation. If omitted, lists all conversations."),
+        agentType: z
+            .string()
+            .optional()
+            .describe("Filter conversations by agent type ('admin' or 'public'). Only applies when listing conversations."),
+        agentSlug: z
+            .string()
+            .optional()
+            .describe("Filter conversations by public agent slug (e.g. 'maxy-assistant'). Only applies when listing conversations."),
+        since: z
+            .string()
+            .optional()
+            .describe("ISO 8601 timestamp. Only return conversations with activity (updatedAt) at or after this time. Only applies when listing conversations."),
+        includeMessages: z
+            .boolean()
+            .optional()
+            .describe("When true, include message content inline with each conversation (max 50 messages per conversation). Only applies when listing conversations."),
+        limit: z
+            .number()
+            .optional()
+            .describe("Maximum results (default 50 for conversations, 200 for messages)"),
+    }, async ({ conversationId, agentType, agentSlug, since, includeMessages, limit }) => {
+        const startTime = Date.now();
+        const dbSession = getSession();
+        try {
+            if (conversationId) {
+                // Messages mode — chronological listing for a specific conversation
+                const messageLimit = limit ?? 200;
+                const result = await dbSession.run(`MATCH (m:Message)-[:PART_OF]->(c:Conversation {conversationId: $conversationId, accountId: $accountId})
+             WHERE ${notTrashed("m")} AND ${notTrashed("c")}
+             RETURN m.role AS role, m.content AS content, m.createdAt AS createdAt
+             ORDER BY m.createdAt ASC
+             LIMIT $limit`, { conversationId, accountId, limit: int(messageLimit) });
+                if (result.records.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No messages found for this conversation." }],
+                    };
+                }
+                const formatted = result.records.map((r) => {
+                    const role = String(r.get("role") ?? "unknown");
+                    const content = String(r.get("content") ?? "");
+                    const ts = shortIso(String(r.get("createdAt") ?? ""));
+                    return ts ? `[${role} ${ts}]\n  ${content}` : `[${role}]\n  ${content}`;
+                });
+                process.stderr.write(`[conversation-list] [${accountId}] mode=messages conversationId=${conversationId.slice(0, 8)}… count=${result.records.length} (${Date.now() - startTime}ms)\n`);
+                return {
+                    content: [{ type: "text", text: formatted.join("\n---\n") }],
+                };
+            }
+            // List mode — all conversations with message counts (or inline messages)
+            const convLimit = limit ?? (includeMessages ? 20 : 50);
+            const whereClauses = [];
+            if (agentType)
+                whereClauses.push("c.agentType = $agentType");
+            if (agentSlug)
+                whereClauses.push("c.agentSlug = $agentSlug");
+            if (since)
+                whereClauses.push("c.updatedAt >= datetime($since)");
+            const whereStr = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+            const params = {
+                accountId,
+                limit: int(convLimit),
+                ...(agentType ? { agentType } : {}),
+                ...(agentSlug ? { agentSlug } : {}),
+                ...(since ? { since } : {}),
+            };
+            if (includeMessages) {
+                // Inline messages mode — conversations with message content
+                const msgLimit = 50;
+                const trashedConvFilter = notTrashed("c");
+                const trashedMsgFilter = notTrashed("m");
+                const result = await dbSession.run(`MATCH (c:Conversation {accountId: $accountId})
+             ${whereStr ? whereStr + " AND " : "WHERE "}${trashedConvFilter}
+             WITH c ORDER BY c.updatedAt DESC LIMIT $limit
+             OPTIONAL MATCH (m:Message)-[:PART_OF]->(c) WHERE ${trashedMsgFilter}
+             WITH c, m ORDER BY m.createdAt ASC
+             WITH c, collect({role: m.role, content: m.content, createdAt: m.createdAt})[0..${msgLimit}] AS messages
+             RETURN c.conversationId AS conversationId,
+                    c.agentType AS agentType,
+                    c.agentSlug AS agentSlug,
+                    c.name AS name,
+                    c.createdAt AS createdAt,
+                    c.updatedAt AS updatedAt,
+                    size(messages) AS messageCount,
+                    messages
+             ORDER BY c.updatedAt DESC`, params);
+                if (result.records.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No conversations found." }],
+                    };
+                }
+                const formatted = result.records.map((r) => {
+                    const id = String(r.get("conversationId") ?? "");
+                    const msgCount = Number(r.get("messageCount") ?? 0);
+                    const header = formatConversationHeader({
+                        name: r.get("name"),
+                        conversationId: id,
+                        agentType: String(r.get("agentType") ?? ""),
+                        agentSlug: r.get("agentSlug"),
+                        createdAt: String(r.get("createdAt") ?? ""),
+                        updatedAt: String(r.get("updatedAt") ?? ""),
+                        messageCount: msgCount,
+                    });
+                    const messages = r.get("messages");
+                    const validMessages = (messages || []).filter((m) => m.role != null);
+                    if (validMessages.length === 0) {
+                        return `### ${header}\n  (no messages)`;
+                    }
+                    let missingTs = 0;
+                    const msgLines = validMessages.map((m) => {
+                        const role = String(m.role);
+                        const content = String(m.content ?? "");
+                        const ts = shortIso(String(m.createdAt ?? ""));
+                        if (!ts)
+                            missingTs++;
+                        return ts ? `[${role} ${ts}] ${content}` : `[${role}] ${content}`;
+                    });
+                    const footer = missingTs > 0 ? `\n(${missingTs} message${missingTs > 1 ? "s" : ""} had no timestamp)` : "";
+                    return `### ${header}\n${msgLines.join("\n")}${footer}`;
+                });
+                process.stderr.write(`[conversation-list] [${accountId}] mode=inline agentType=${agentType ?? "all"} agentSlug=${agentSlug ?? "all"} since=${since ?? "none"} count=${result.records.length} (${Date.now() - startTime}ms)\n`);
+                return {
+                    content: [{ type: "text", text: formatted.join("\n\n") }],
+                };
+            }
+            // Metadata mode — conversations with message counts only
+            const trashedConvFilter = notTrashed("c");
+            const trashedMsgFilter = notTrashed("m");
+            const result = await dbSession.run(`MATCH (c:Conversation {accountId: $accountId})
+           ${whereStr ? whereStr + " AND " : "WHERE "}${trashedConvFilter}
+           WITH c ORDER BY c.updatedAt DESC LIMIT $limit
+           OPTIONAL MATCH (m:Message)-[:PART_OF]->(c) WHERE ${trashedMsgFilter}
+           RETURN c.conversationId AS conversationId,
+                  c.agentType AS agentType,
+                  c.agentSlug AS agentSlug,
+                  c.name AS name,
+                  c.createdAt AS createdAt,
+                  c.updatedAt AS updatedAt,
+                  count(m) AS messageCount
+           ORDER BY c.updatedAt DESC`, params);
+            if (result.records.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No conversations found." }],
+                };
+            }
+            const formatted = result.records.map((r) => {
+                const id = String(r.get("conversationId") ?? "");
+                const msgCount = typeof r.get("messageCount") === "number"
+                    ? r.get("messageCount")
+                    : Number(r.get("messageCount"));
+                return formatConversationHeader({
+                    name: r.get("name"),
+                    conversationId: id,
+                    agentType: String(r.get("agentType") ?? ""),
+                    agentSlug: r.get("agentSlug"),
+                    createdAt: String(r.get("createdAt") ?? ""),
+                    updatedAt: String(r.get("updatedAt") ?? ""),
+                    messageCount: msgCount,
+                });
+            });
+            process.stderr.write(`[conversation-list] [${accountId}] mode=list agentType=${agentType ?? "all"} agentSlug=${agentSlug ?? "all"} since=${since ?? "none"} count=${result.records.length} (${Date.now() - startTime}ms)\n`);
+            return {
+                content: [{ type: "text", text: formatted.join("\n") }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `conversation-list failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        finally {
+            await dbSession.close();
+        }
+    });
+    server.tool("profile-update", "Create, update, or reinforce a user preference; set top-level UserProfile fields (timezone, locale, givenName, role, expertise) via profileFields; AND set operator-identity fields (email, telephone) on the operator's personal-profile Person via personFields. Person is the canonical operator-identity store; UserProfile carries preferences and behavioural state only. Supports modes: reinforce (re-observed, boost confidence), update (value changed), contradict (value contradicts prior), merge (combine overlapping preferences).", {
+        category: z.enum(["communication", "scheduling", "decision", "workflow", "content", "interaction"])
+            .describe("Preference category"),
+        key: z.string().describe("Preference identifier (e.g. 'response_length', 'meeting_time')"),
+        value: z.string().describe("The preference value (e.g. 'terse', 'never before 10am')"),
+        source: z.enum(["explicit", "behavioural"]).optional()
+            .describe("How the preference was observed. Defaults to 'behavioural'."),
+        mode: z.enum(["reinforce", "update", "contradict", "merge"]).optional()
+            .describe("Update mode. Defaults to 'reinforce'."),
+        conversationId: z.string().optional()
+            .describe("Conversation ID for evidence linking"),
+        profileFields: z.record(z.string(), z.unknown()).optional()
+            .describe("Top-level UserProfile fields to update (e.g. timezone, locale, role)"),
+        personFields: z.object({
+            email: z.string().optional(),
+            telephone: z.string().optional(),
+        }).optional()
+            .describe("Operator-identity fields written to the OWNS-bound Person. Use canonical `telephone` (NOT `phone` — that is the schema synonym, not the canonical name). Tool throws if the AdminUser-OWNS-Person edge is missing rather than silently no-op."),
+        mergeSourceIds: z.array(z.string()).optional()
+            .describe("For mode 'merge': preferenceIds of sources to combine into this preference"),
+    }, async ({ category, key, value, source, mode, conversationId, profileFields, personFields, mergeSourceIds }) => {
+        try {
+            if (!userId) {
+                return { content: [{ type: "text", text: "profile-update requires an authenticated admin session with userId" }], isError: true };
+            }
+            const result = await profileUpdate({
+                accountId,
+                userId,
+                category,
+                key,
+                value,
+                source,
+                mode,
+                conversationId,
+                profileFields: profileFields,
+                personFields,
+                mergeSourceIds,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `Preference ${result.action}: ${category}/${key} (confidence: ${result.confidence.toFixed(2)}${result.mergedCount ? `, merged ${result.mergedCount} sources` : ""})`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `profile-update failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("profile-delete", "Soft-delete a specific user preference (marks :Trashed, restorable via memory-restore within the grace period; permanently removed later by memory-empty-trash). Use when the owner says 'forget that' or 'don't remember X'. Idempotent — succeeds even if the preference doesn't exist.", {
+        category: z.enum(["communication", "scheduling", "decision", "workflow", "content", "interaction"])
+            .describe("Preference category"),
+        key: z.string().describe("Preference key to delete"),
+    }, async ({ category, key }) => {
+        try {
+            if (!userId) {
+                return { content: [{ type: "text", text: "profile-delete requires an authenticated admin session with userId" }], isError: true };
+            }
+            const result = await profileDelete({ accountId, userId, category, key });
+            return {
+                content: [{
+                        type: "text",
+                        text: result.deleted
+                            ? `Deleted preference: ${category}/${key}`
+                            : `No preference found for ${category}/${key} — nothing to delete.`,
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `profile-delete failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // profile-read contains owner PII (name, role, timezone, preferences) —
+    // admin-only, not exposed to the public agent.
+    server.tool("profile-read", "Read the business owner's profile and preferences. Returns preferences grouped by category (communication, scheduling, decisions, workflow, content, interaction). " +
+        "With detail=true: includes per-preference confidence scores, evidence trail (which conversations the preference was observed in), source (explicit vs behavioural), and summary statistics. " +
+        "Use detail=true when the owner asks 'what do you know about me?' or when reviewing memory accuracy.", {
+        detail: z.boolean().optional().describe("When true, returns per-preference confidence, source, evidence trail, and memory statistics. " +
+            "Default false returns a compact summary for system prompt injection."),
+    }, async ({ detail }) => {
+        try {
+            if (!userId) {
+                return { content: [{ type: "text", text: "profile-read requires an authenticated admin session with userId" }], isError: true };
+            }
+            const result = await profileRead({ accountId, userId, detail: detail ?? false });
+            return {
+                content: [{ type: "text", text: result.summary }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `profile-read failed: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -------------------------------------------------------------------------
+    // Deny-list maintenance + conversation-memory expunge.
+    //
+    // The deny-list is operator-curated storage of "never surface these
+    // substrings" signal. Nothing auto-applies it — no cron, no bulk engine.
+    // The admin agent reads the list and applies discretion per case via
+    // memory-update, memory-delete, or conversation-memory-expunge. This
+    // replaces the removed graph-prune autonomous rule engine whose
+    // orphan-delete rule wiped 19 nodes on 2026-04-20.
+    // -------------------------------------------------------------------------
+    server.tool("graph-prune-denylist-add", "Add one or more strings to the operator-curated deny-list. The list is a stored signal — no cron, no " +
+        "autonomous sweep. The admin agent reads the list and decides per case whether to null a property " +
+        "via memory-update, remove a node via memory-delete, or scrub a conversation's :Memory via " +
+        "conversation-memory-expunge. Use to record poisonous substrings (retired domain names, wrong " +
+        "account ids, fabricated identifiers) that you want the agent to watch for. The list is shared " +
+        "per-device and survives upgrades.", {
+        values: z.array(z.string().min(1)).min(1).describe("Substring values to add. Match is exact substring (case-sensitive) against string-typed properties only."),
+    }, async ({ values }) => {
+        try {
+            const result = graphPruneDenylistAdd(values);
+            const lines = [
+                `Added ${result.added.length} entries to deny-list (total ${result.totalAfter}).`,
+            ];
+            if (result.added.length > 0)
+                lines.push(`Added: ${result.added.join(", ")}`);
+            if (result.skipped.length > 0)
+                lines.push(`Already present (skipped): ${result.skipped.join(", ")}`);
+            lines.push("No autonomous sweep — apply discretion via memory-update / memory-delete / conversation-memory-expunge on reads that surface matching content.");
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `graph-prune-denylist-add failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("graph-prune-denylist-remove", "Remove one or more strings from the operator-curated deny-list. Entries no longer serve as signal " +
+        "for the admin agent. Any property values previously nulled via manual memory-update calls are not " +
+        "restored — audit entries on each affected node remain for forensic review.", {
+        values: z.array(z.string().min(1)).min(1).describe("Substring values to remove (must match exactly as previously added)."),
+    }, async ({ values }) => {
+        try {
+            const result = graphPruneDenylistRemove(values);
+            const lines = [
+                `Removed ${result.removed.length} entries from deny-list (total ${result.totalAfter}).`,
+            ];
+            if (result.removed.length > 0)
+                lines.push(`Removed: ${result.removed.join(", ")}`);
+            if (result.notFound.length > 0)
+                lines.push(`Not present (skipped): ${result.notFound.join(", ")}`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `graph-prune-denylist-remove failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("conversation-memory-expunge", "Remove deny-listable content from a specific conversation's :Memory nodes by manually-supplied " +
+        "substring pattern. Targets :Memory nodes linked to the named Conversation; nulls every string property " +
+        "whose value contains the pattern, with an audit entry on each affected node. The conversation transcript " +
+        "(Message nodes) is immutable history and is never modified — only the derived :Memory payload that " +
+        "memory-search would otherwise re-surface. Use when a single conversation polluted memory with claims " +
+        "that should not propagate (e.g. wrong-account hostnames, fabricated identifiers).", {
+        conversationId: z.string().min(1).describe("The Conversation node's conversationId to scope the expunge to."),
+        pattern: z.string().min(1).describe("The substring to scrub from string properties on linked :Memory nodes."),
+    }, async ({ conversationId, pattern }) => {
+        try {
+            const result = await conversationMemoryExpunge({ accountId, conversationId, pattern });
+            const lines = [
+                `Expunged "${result.pattern}" from conversation ${result.conversationId.slice(0, 8)}…`,
+                `:Memory nodes scanned: ${result.nodesScanned}`,
+                `Properties nulled: ${result.propertiesNulled}`,
+            ];
+            if (result.affectedNodeIds.length > 0 && result.affectedNodeIds.length <= 25) {
+                lines.push(`Affected node ids: ${result.affectedNodeIds.join(", ")}`);
+            }
+            else if (result.affectedNodeIds.length > 25) {
+                lines.push(`Affected node ids: ${result.affectedNodeIds.length} nodes (too many to list — see graph-prune.log for [graph:prune:action] entries).`);
+            }
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `conversation-memory-expunge failed: ${err instanceof Error ? err.message : String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+}
+// graph-prune-denylist-list and conversation-search are read-only — available regardless of readOnly mode.
+server.tool("graph-prune-denylist-list", "List the current operator-curated deny-list values used by the daily graph-prune cron. " +
+    "Returns the substring values, the timestamp of the last edit, and the total count.", {}, () => {
+    try {
+        const result = graphPruneDenylistList();
+        if (result.count === 0) {
+            return { content: [{ type: "text", text: "Deny-list is empty. Use graph-prune-denylist-add to seed entries." }] };
+        }
+        const text = `Deny-list (${result.count} entries, updated ${result.updatedAt}):\n${result.values.map((v) => `  - ${v}`).join("\n")}`;
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `graph-prune-denylist-list failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+// conversation-search is read-only — available regardless of readOnly mode.
+// When SESSION_ID is set (public agent), results are scoped to that conversation only.
+eagerTool(server, "conversation-search", "Search conversation history using semantic vector search. Returns relevant past messages, ordered by relevance. Use this to recall specific past interactions.", {
+    query: z.string().describe("Natural language search query"),
+    limit: z
+        .number()
+        .optional()
+        .describe("Maximum number of results (default 10)"),
+}, async ({ query, limit: maxResults }) => {
+    try {
+        const queryEmbedding = await embed(query);
+        const resultLimit = maxResults ?? 10;
+        const dbSession = getSession();
+        try {
+            const conversationSessionId = resolveSessionId();
+            const sessionClause = conversationSessionId
+                ? "AND node.conversationId = $sessionId"
+                : "";
+            const result = await dbSession.run(`CALL db.index.vector.queryNodes('message_embedding', $limit, $embedding)
+           YIELD node, score
+           WHERE node.accountId = $accountId
+           ${sessionClause}
+           AND ${notTrashed("node")}
+           WITH node, score
+           OPTIONAL MATCH (node)-[:PART_OF]->(c:Conversation) WHERE ${notTrashed("c")}
+           RETURN node.messageId AS messageId,
+                  node.role AS role,
+                  node.content AS content,
+                  node.conversationId AS conversationId,
+                  c.name AS sessionName,
+                  node.createdAt AS createdAt,
+                  score
+           ORDER BY score DESC
+           LIMIT $limit`, {
+                embedding: queryEmbedding,
+                limit: int(resultLimit),
+                accountId,
+                ...(conversationSessionId ? { sessionId: conversationSessionId } : {}),
+            });
+            if (result.records.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No conversation history found for this query." }],
+                };
+            }
+            const formatted = result.records.map((r) => {
+                const role = r.get("role");
+                const content = r.get("content");
+                const score = typeof r.get("score") === "number" ? r.get("score") : Number(r.get("score"));
+                const createdAt = String(r.get("createdAt"));
+                const convId = r.get("conversationId");
+                const sessionName = r.get("sessionName");
+                const convPrefix = convId ? convId.slice(0, 8) : "unknown";
+                const convLabel = sessionName
+                    ? `[conv:${convPrefix} "${sessionName}"]`
+                    : `[conv:${convPrefix}]`;
+                return `${convLabel} [${role}] (score: ${score.toFixed(3)}, ${createdAt})\n  ${content}`;
+            });
+            // Diagnostic: log when admin search results span multiple conversations
+            const distinctConvIds = new Set(result.records
+                .map((r) => r.get("conversationId"))
+                .filter(Boolean));
+            if (distinctConvIds.size > 1) {
+                const prefixes = [...distinctConvIds].map((id) => id.slice(0, 8));
+                process.stderr.write(`[conversation-search] [${accountId}] results span ${distinctConvIds.size} conversations: ${prefixes.join(", ")} (query: ${query.slice(0, 80)})\n`);
+            }
+            return {
+                content: [{ type: "text", text: formatted.join("\n---\n") }],
+            };
+        }
+        finally {
+            await dbSession.close();
+        }
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Conversation search failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Cleanup on exit
+process.on("SIGINT", async () => {
+    liveSchemaRuntime.cache.stop();
+    await closeDriver();
+    process.exit(0);
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map