@rubytech/create-maxy-code 0.1.158 → 0.1.161

package/payload/platform/plugins/memory/bin/conversation-archive-ingest.sh

@@ -1,43 +1,29 @@
 #!/usr/bin/env bash
 # =============================================================================
-# conversation-archive-ingest.sh — single deterministic Bash entry for
-# conversation-archive ingestion
-# env-only identity, progress-file path on stdout).
+# conversation-archive-ingest.sh — Bash wrapper around the
+# conversation-archive prepare helper (Task 435).
 #
-# Source-agnostic: WhatsApp `_chat.txt`, Telegram, Signal, LinkedIn DMs, Zoom
-# transcript, meeting minutes, iMessage, Slack — every source flows through
-# the same pipeline with `--source` selecting the normaliser.
-#
-# Pipeline: normalise (per source) → bind canonical sender set →
-# derive conversationIdentity → look up prior :ConversationArchive (delta
-# cursor) → sessionize delta at gap-hours boundary → for each session: classify
-# via Haiku (mode='chat') + memory-ingest immediately (per-session checkpoint).
+# Post-Task-435 contract: the wrapper validates env (ACCOUNT_ID, USER_ID,
+# NEO4J_URI, NEO4J_PASSWORD) and argv, then exec's the .mjs which runs the
+# deterministic pipeline (normalise → verify participants → derive
+# conversationIdentity → look up prior archive cursor → slice delta →
+# sessionize → emit JSON). Classify + memory-ingest move into the dispatched
+# specialist's per-turn work (driven by SKILL.md).
 #
 # Usage:
 #   bash conversation-archive-ingest.sh <archive-path>
-#         --source <whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|other>
+#         --source <whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|x-dm|other>
 #         --participant-person-ids <csv>
 #         --scope <admin|public>
-#         [--rebuild]                  (opt-in destructive rebuild)
+#         [--rebuild]
 #         [--timezone <iana-zone>]
-#         [--date-format <DD/MM/YY|MM/DD/YY|DD/MM/YYYY|MM/DD/YYYY>]   (whatsapp only)
-#         [--session-id <id>]
-#
-# Sessions split deterministically at 8h gap (fixed code constant).
-# `--session-gap-hours` is REMOVED; passing it FAILs at phase=argv.
+#         [--date-format <DD/MM/YY|MM/DD/YY|DD/MM/YYYY|MM/DD/YYYY>]
 #
-# Identity: `ACCOUNT_ID` + `USER_ID` come from the caller's env
-# (plumbed by `spawn-env.ts` into every Bash subprocess). The owner :AdminUser
-# elementId is derived from (accountId, userId) inside the bin via Cypher.
-# `--account-id` and `--owner-element-id` flags are GONE — env-only identity
-# is doctrine. `--participant-person-ids` carries the operator-confirmed
-# non-owner set.
+# Identity: ACCOUNT_ID + USER_ID come from the caller's env (plumbed by
+# spawn-env.ts). Owner :AdminUser elementId is derived inside the .mjs.
 #
-# Exit 0  + JSON summary on stdout on success.
+# Exit 0 + one JSON line on stdout on success.
 # Exit !0 + one [conversation-archive] FAIL line on stderr on failure.
-# Stdout (always, before exec node): `[conversation-archive] progress-file=<absolute-path>`
-# Mid-run progress: line-by-line writes to that progress-file (fsync per line);
-# the agent's heartbeat polls it via `tail -n <N> <path>` every 30 s.
 # =============================================================================
 
 set -euo pipefail
@@ -56,10 +42,6 @@ if [ ! -f "$INGEST_MJS" ]; then
   arg_fail "conversation-archive-ingest.mjs not found at $INGEST_MJS — run from a built install"
 fi
 
-# Identity is env-only. The mjs LOUD-FAILs on missing/malformed
-# values, but we mirror the cheap accountId presence check here so the
-# progress-file path can be computed and emitted before exec node — without
-# accountId, the path is undefined.
 if [ -z "${ACCOUNT_ID:-}" ]; then
   arg_fail "ACCOUNT_ID env missing — bin must be invoked under an authenticated agent context (set by spawn-env.ts)"
 fi
@@ -74,7 +56,6 @@ HAS_PARTICIPANTS=0
 PARTICIPANTS_VAL=""
 HAS_SCOPE=0
 SCOPE_VAL=""
-SESSION_ID_VAL=""
 
 ARGS=("$@")
 i=0
@@ -84,7 +65,6 @@ while [ $i -lt ${#ARGS[@]} ]; do
     --source)                  HAS_SOURCE=1;       SOURCE_VAL="${ARGS[$((i + 1))]:-}";       i=$((i + 2)); continue ;;
     --participant-person-ids)  HAS_PARTICIPANTS=1; PARTICIPANTS_VAL="${ARGS[$((i + 1))]:-}"; i=$((i + 2)); continue ;;
     --scope)                   HAS_SCOPE=1;        SCOPE_VAL="${ARGS[$((i + 1))]:-}";        i=$((i + 2)); continue ;;
-    --session-id)              SESSION_ID_VAL="${ARGS[$((i + 1))]:-}";                       i=$((i + 2)); continue ;;
     --rebuild)                 i=$((i + 1)); continue ;;
     --session-gap-hours)       arg_fail "--session-gap-hours is no longer supported; gap is fixed at 8h. Use --rebuild on the prior export bytes if you need to re-classify." ;;
     --timezone|--date-format)  i=$((i + 2)); continue ;;
@@ -98,7 +78,7 @@ while [ $i -lt ${#ARGS[@]} ]; do
 done
 
 [ -n "$ARCHIVE" ]                                                || arg_fail "missing positional <archive>"
-[ "$HAS_SOURCE"       -eq 1 ] && [ -n "$SOURCE_VAL"       ]      || arg_fail "missing --source (whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|other)"
+[ "$HAS_SOURCE"       -eq 1 ] && [ -n "$SOURCE_VAL"       ]      || arg_fail "missing --source (whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|x-dm|other)"
 [ "$HAS_PARTICIPANTS" -eq 1 ] && [ -n "$PARTICIPANTS_VAL" ]      || arg_fail "missing --participant-person-ids (csv of operator-confirmed :Person/:AdminUser elementIds, owner excluded)"
 [ "$HAS_SCOPE"        -eq 1 ] && [ -n "$SCOPE_VAL"        ]      || arg_fail "missing --scope (or empty value)"
 case "$SCOPE_VAL" in
@@ -123,16 +103,4 @@ fi
 export NEO4J_USER="${NEO4J_USER:-neo4j}"
 export MAXY_PLATFORM_ROOT="$PLATFORM_ROOT"
 
-# Progress-file path must match the path the mjs opens (deterministic from
-# (ACCOUNT_ID, sessionId)). When the operator omits --session-id, the mjs
-# mints one — the wrapper passes through the same value via env so both
-# sides converge on one path.
-if [ -z "$SESSION_ID_VAL" ]; then
-  SESSION_ID_VAL="conversation-archive:${SOURCE_VAL}:$(date +%s%N)"
-  ARGS+=(--session-id "$SESSION_ID_VAL")
-fi
-INSTALL_DIR="$(cd "$PLATFORM_ROOT/.." && pwd)"
-PROGRESS_FILE="$INSTALL_DIR/data/accounts/$ACCOUNT_ID/logs/conversation-archive-$SESSION_ID_VAL.log"
-echo "[conversation-archive] progress-file=$PROGRESS_FILE"
-
 exec node "$INGEST_MJS" "${ARGS[@]}"

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

@@ -12,6 +12,8 @@ import { buildLiveSchemaSource, defaultSchemaCypherPath, } from "./lib/live-sche
 import { memoryReindex } from "./tools/memory-reindex.js";
 import { memoryIngestExtract } from "./tools/memory-ingest-extract.js";
 import { memoryIngest } from "./tools/memory-ingest.js";
+import { CONVERSATION_SOURCES } from "./lib/conversation-normalisers/types.js";
+import { kdClassify } from "./tools/kd-classify.js";
 import { memoryArchiveWrite } from "./tools/memory-archive-write.js";
 import { obsidianVaultImport, } from "./tools/obsidian-vault-import.js";
 // whatsapp-export-{parse,preview,insight-write} deleted. Conversation
@@ -25,6 +27,7 @@ import { memoryIngestWeb } from "./tools/memory-ingest-web.js";
 import { memoryUpdate } from "./tools/memory-update.js";
 import { memoryDelete } from "./tools/memory-delete.js";
 import { memoryFindCandidates } from "./tools/memory-find-candidates.js";
+import { memoryNodeExists, ALLOWED_LABELS as MEMORY_NODE_EXISTS_LABELS } from "./tools/memory-node-exists.js";
 import { memoryRestore } from "./tools/memory-restore.js";
 import { memoryEmptyTrash } from "./tools/memory-empty-trash.js";
 import { memoryListAttachments } from "./tools/memory-list-attachments.js";
@@ -39,7 +42,8 @@ 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 { conversationArchiveDeriveInsights, PROPOSAL_KINDS, } from "./tools/conversation-archive-derive-insights.js";
+import { conversationArchiveListChunks } from "./tools/conversation-archive-list-chunks.js";
 import { conversationArchiveEnrichRejection } from "./tools/conversation-archive-enrich-rejection.js";
 import { fetchImageAsContent } from "./tools/image-fetch.js";
 import { memoryTypedEdgePass } from "./tools/memory-typed-edge-pass.js";
@@ -295,16 +299,12 @@ eagerTool(server, "memory-search", "Search the knowledge graph using semantic ve
     }
 });
 // ---------------------------------------------------------------------------
-// conversation-archive Phase 2: chunk-anchored insight derivation.
-// Read-only tool. Walks the :Section chunks of one named conversation
-// archive (`:ConversationArchive` keyed on `conversationIdentity` — Task
-// 397) 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.
+// conversation-archive Phase 2 — chunk page reader (Task 433).
+// Returns one page of :Section chunk bodies for the named :ConversationArchive
+// so the conversation-archive-enrich skill can drive the dispatched
+// specialist to read each chunk and emit claims in-turn. Read-only.
 // ---------------------------------------------------------------------------
-server.tool("conversation-archive-derive-insights", "Walk the :Section chunks of one named :ConversationArchive (conversation-archive walker) 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.", {
+server.tool("conversation-archive-list-chunks", "Page through the :Section chunks of one named :ConversationArchive and return each chunk's elementId, ordered index, summary, and full body. The conversation-archive-enrich skill calls this per page, then prompts the dispatched specialist to read each chunk's body in-turn and emit claims; the skill hands those claims back to `conversation-archive-derive-insights` for per-kind cypher emission. Read-only.", {
     archiveElementId: z
         .string()
         .describe("elementId of the :ConversationArchive parent (Task 397 — keyed on conversationIdentity) the operator named (required)."),
@@ -313,23 +313,100 @@ server.tool("conversation-archive-derive-insights", "Walk the :Section chunks of
         .int()
         .nonnegative()
         .optional()
-        .describe("Zero-based chunk offset. Default 0. Increase per page."),
+        .describe("Zero-based chunk offset. Default 0. Advance by chunkLimit 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."),
+        .describe("Chunks per page (1..20). Default 5."),
 }, async ({ archiveElementId, chunkOffset, chunkLimit }) => {
     if (!accountId)
-        return refuseNoAccount("conversation-archive-derive-insights");
+        return refuseNoAccount("conversation-archive-list-chunks");
     try {
-        const result = await conversationArchiveDeriveInsights({
+        const result = await conversationArchiveListChunks({
             accountId,
             archiveElementId,
             chunkOffset,
             chunkLimit,
+        });
+        const header = `archiveElementId=${result.archiveElementId} title=${JSON.stringify(result.archiveTitle ?? "")} totalChunks=${result.totalChunks} walked=${result.walkedFrom}..${result.walkedTo} chunks=${result.chunks.length} chunksRemaining=${result.chunksRemaining}`;
+        const chunkBlocks = result.chunks
+            .map((c) => [
+            `Chunk ${c.index + 1}/${result.totalChunks}:`,
+            `  elementId=${c.elementId}`,
+            `  summary=${JSON.stringify(c.summary)}`,
+            `  body=${JSON.stringify(c.body)}`,
+        ].join("\n"))
+            .join("\n\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: result.chunks.length === 0
+                        ? `${header}\n(no chunks at this offset)`
+                        : `${header}\n\n${chunkBlocks}`,
+                },
+            ],
+        };
+    }
+    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-list-chunks\n");
+// ---------------------------------------------------------------------------
+// conversation-archive Phase 2: per-chunk claim → cypher proposal emitter.
+// Task 433: accepts the agent-produced `claims` array for one chunk (read
+// from `conversation-archive-list-chunks`) and returns operator-facing
+// proposals carrying the per-kind mergeCypher. Rejection sidecar filter is
+// applied here. The tool itself NEVER writes; idempotency lives on the
+// MERGE-key (chunkElementId, kind, contentHash) baked into each mergeCypher.
+// ---------------------------------------------------------------------------
+const claimSchema = z.object({
+    kind: z.enum([...PROPOSAL_KINDS]).describe("One of: mention, task, preference, observed-relationship."),
+    evidenceSnippet: z
+        .string()
+        .describe("Near-verbatim quote from the chunk body (≤80 chars enforced server-side)."),
+    subject: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Display name of the primary entity. Required for mention + observed-relationship."),
+    object: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Display name of the related entity. Required for observed-relationship only."),
+    payload: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Kind-specific structured fields (taskTitle/taskDueHint for task; preferenceCategory/preferenceKey/preferenceValue for preference; relationshipType for observed-relationship)."),
+});
+server.tool("conversation-archive-derive-insights", "Convert one chunk's agent-produced claims into operator-facing claim proposals (mention, task, preference, observed-relationship). The conversation-archive-enrich skill reads chunk bodies via `conversation-archive-list-chunks`, drives the dispatched specialist to emit claims in-turn, and passes them here for per-kind cypher emission. Applies the durable rejection sidecar so already-triaged claims do not re-surface. Read-only: the per-row operator gate runs in the skill, this tool never writes.", {
+    archiveElementId: z
+        .string()
+        .describe("elementId of the :ConversationArchive parent (Task 397 — keyed on conversationIdentity) the operator named (required)."),
+    chunkElementId: z
+        .string()
+        .describe("elementId of the single :Section chunk the agent just read (required)."),
+    claims: z
+        .array(claimSchema)
+        .describe("Claims the dispatched specialist emitted in-turn from the chunk body. Zero is valid — pass [] to record an empty-chunk pass."),
+}, async ({ archiveElementId, chunkElementId, claims }) => {
+    if (!accountId)
+        return refuseNoAccount("conversation-archive-derive-insights");
+    try {
+        const result = await conversationArchiveDeriveInsights({
+            accountId,
+            archiveElementId,
+            chunkElementId,
+            claims: claims,
             sessionId: resolveSessionId(),
         });
         const proposalLines = result.proposals
@@ -349,13 +426,13 @@ server.tool("conversation-archive-derive-insights", "Walk the :Section chunks of
             ].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}`;
+        const header = `archiveElementId=${result.archiveElementId} chunkElementId=${result.chunkElementId} proposals=${result.proposals.length} rejectionsFiltered=${result.rejectionsFiltered} invalidClaims=${result.invalidClaims}`;
         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(no proposals from this chunk's claims)`
                         : `${header}\n\n${proposalLines}`,
                 },
             ],
@@ -676,7 +753,7 @@ if (!readOnly) {
                 keywords,
                 sourceWorkflow,
                 occurredAt,
-                conversationNodeId: process.env.CONVERSATION_NODE_ID,
+                conversationNodeId: process.env.SESSION_NODE_ID,
             });
             const status = result.created
                 ? `Report created`
@@ -888,20 +965,29 @@ if (!readOnly) {
             };
         }
     });
-    server.tool("memory-ingest", "Write a classified document into the graph as typed nodes anchored to the document subject. " +
-        "Requires a prior memory-ingest-extract call for the text cache; the typed-section JSON in the `sections` argument is produced by the dispatched specialist in-turn from the loaded ontology. " +
+    server.tool("memory-ingest", "Write a classified document or conversation-archive session into the graph as typed nodes anchored to a subject. " +
+        "Two mutually-exclusive parent paths — exactly one MUST be set: " +
+        "(1) **Document path** — set `attachmentId` (requires a prior memory-ingest-extract call for the text cache). MERGEs under `:KnowledgeDocument` keyed on attachmentId. The typed-section JSON in `sections` is produced by the dispatched specialist in-turn from the loaded ontology. " +
+        "(2) **Conversation-archive path** — set `conversationIdentity` along with the conversation-document fields (`source`, `archiveSha256`, `archiveSourceFile`, `participantElementIds`, `lastIngestedMessageHash`, `lastIngestedMessageAt`, optionally `archiveTitle` and `cleanupPriorChunks`). MERGEs under `:ConversationArchive` keyed on conversationIdentity. The specialist invokes this once per session prepared by `conversation-archive-ingest.sh`, advancing the cursor atomically with each session's chunks. " +
         "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) " +
+        "subject via the natural ontology edge plus a (parent)-[:REFERENCES]->(typed) link, or — for " +
+        "UNMAPPED sections — a generic :Section node hanging off the parent via HAS_SECTION (legacy fallback). " +
+        "Document re-ingest replaces the document's typed and untyped children (same attachmentId). Conversation-archive re-ingest is delta-append: prior chunks are never touched unless `cleanupPriorChunks=true` is set (only legitimate on the FIRST session of a `--rebuild` run). " +
+        "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."),
+        attachmentId: z.string().optional().describe("UUID of the file attachment — must match a prior memory-ingest-extract call. Document path only — mutually exclusive with conversationIdentity."),
+        conversationIdentity: z.string().optional().describe("sha256(accountId + ':' + sortedParticipantElementIds.join(',')) — produced by `conversation-archive-ingest.sh`. Conversation-archive path only — mutually exclusive with attachmentId."),
+        source: z.enum(CONVERSATION_SOURCES).optional().describe("Conversation source enum. Required on the conversation-archive path."),
+        archiveSha256: z.string().optional().describe("sha256 of the export bytes. Required on the conversation-archive path; stamped on every :Section chunk so cleanup-by-archiveSha256 is exact."),
+        archiveSourceFile: z.string().optional().describe("Basename of the source file (e.g. `_chat.txt`). Required on the conversation-archive path."),
+        participantElementIds: z.array(z.string()).optional().describe("Owner + operator-confirmed participants (elementIds). Required on the conversation-archive path. Owner is included first; :PARTICIPANT_IN edges land for every entry. Order is irrelevant for conversationIdentity, which is derived from a sorted set."),
+        lastIngestedMessageHash: z.string().optional().describe("sha256 of the last message in THIS session. Required on the conversation-archive path; written to :ConversationArchive.lastIngestedMessageHash atomically with this session's chunks for delta-append on the next ingest."),
+        lastIngestedMessageAt: z.string().optional().describe("ISO timestamp of the last message in THIS session. Required on the conversation-archive path; written to :ConversationArchive.lastIngestedMessageAt."),
+        archiveTitle: z.string().optional().describe("Stable archive title (`<source> · <owner> ↔ <others> · <YYYY-MM-DD>→<YYYY-MM-DD>`) computed by `conversation-archive-ingest.sh`. Written ON CREATE and COALESCE-on-MATCH so the UI label is stable across re-ingests. Conversation-archive path only."),
+        cleanupPriorChunks: z.boolean().optional().describe("When true, the writer deletes prior chunks for the matching archiveSha256 before MERGE. Set this ONLY on the FIRST session of a `--rebuild` run; subsequent sessions in the same run MUST set it false or the writer drops chunks the earlier sessions just wrote. Defaults to false."),
+        documentSummary: z.string().describe("Classifier-produced summary (1-3 sentences) for the document path. On the conversation-archive path, pass the stable `archiveTitle` so the parent's summary matches the title."),
+        anchorNodeId: z.string().describe("Element ID of the anchor node. Document path: the operator-confirmed document subject (UserProfile/LocalBusiness/Person/Organization). Conversation-archive path: the owner :AdminUser elementId (or :Person for a third-party archive)."),
+        anchorLabel: z.string().describe("Primary label of the anchor node (e.g. 'UserProfile', 'LocalBusiness', 'AdminUser'). 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(),
@@ -945,13 +1031,22 @@ if (!readOnly) {
         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 }) => {
+    }, async ({ attachmentId, conversationIdentity, source, archiveSha256, archiveSourceFile, participantElementIds, lastIngestedMessageHash, lastIngestedMessageAt, archiveTitle, cleanupPriorChunks, documentSummary, anchorNodeId, anchorLabel, sections, documentEdges, orphanCandidates, scope, sourceUrl, sourceType, documentKeywords, userKeywords, sessionId: sessionIdOverride }) => {
         if (!accountId)
             return refuseNoAccount("memory-ingest");
         try {
             const result = await memoryIngest({
                 accountId,
                 attachmentId,
+                conversationIdentity,
+                source,
+                archiveSha256,
+                archiveSourceFile,
+                participantElementIds,
+                lastIngestedMessageHash,
+                lastIngestedMessageAt,
+                archiveTitle,
+                cleanupPriorChunks,
                 documentSummary,
                 anchorNodeId,
                 anchorLabel,
@@ -978,6 +1073,7 @@ if (!readOnly) {
                             orphanCandidates: result.orphanCandidates,
                             documentSummary: result.documentSummary,
                             keywords: result.keywords,
+                            cleanedPriorChunks: result.cleanedPriorChunks,
                         }),
                     }],
             };
@@ -992,6 +1088,25 @@ if (!readOnly) {
             };
         }
     });
+    eagerTool(server, "kd-classify", "Operator-solicited reclassify for any :KnowledgeDocument that carries a `body` property (today: email-thread KDs; future: any thread-shaped source). Reads the KD by attachmentId, decides via a body-growth gate (proceed iff body grew ≥25% since the last classify, or first-ever classify), stages the body to a temp file under $ACCOUNT_DIR/tmp/, and returns a dispatch envelope the admin agent hands to the `librarian` specialist. Librarian runs the document-ingest skill against the temp file; memory-ingest MERGEs by attachmentId, replacing any prior :Section children, and stamps lastClassifiedAt + lastClassifiedBodyLength on the KD so the next gate call has a baseline. Bodyless attachment KDs (PDFs etc.) are not supported here — they have no growth signal.", {
+        attachmentId: z.string().describe("attachmentId of the :KnowledgeDocument to classify. For email threads, this is sha256(`email:<accountId>:<rootMessageId>`); use the email-classify tool when you only have the root Message-ID."),
+    }, async ({ attachmentId }) => {
+        if (!accountId)
+            return refuseNoAccount("kd-classify");
+        try {
+            const text = await kdClassify({ accountId, attachmentId });
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `kd-classify 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 " +
@@ -1211,7 +1326,7 @@ if (!readOnly) {
                 "",
                 ...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 `- elementId=${i.elementId} sessionId=${i.sessionId ?? "null"} assistantMsgs=${i.assistantMsgCount} realUserMsgs=${i.realUserMsgCount}${preview}`;
                 }),
             ];
             return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -1223,6 +1338,30 @@ if (!readOnly) {
             };
         }
     });
+    server.tool("memory-node-exists", "Deterministic label-existence check for installer-seeded singleton roots. " +
+        "Returns { exists, elementId, labels } for a single label/accountId lookup, " +
+        "bypassing the memory-search ranking stack so an installer-seeded node with " +
+        "empty content properties (e.g. a freshly seeded :LocalBusiness with no name yet) " +
+        "is still reported as exists=true. Allow-list of labels is fixed: LocalBusiness, " +
+        "AdminUser, UserProfile, Person. Refuses any other label — use memory-search for " +
+        "ranked discovery on general labels. Use this before any branch that claims a " +
+        "singleton root is missing.", {
+        label: z.enum(MEMORY_NODE_EXISTS_LABELS).describe("Installer-seeded singleton label. One of: LocalBusiness, AdminUser, UserProfile, Person."),
+    }, async ({ label }) => {
+        if (!accountId)
+            return refuseNoAccount("memory-node-exists");
+        try {
+            const result = await memoryNodeExists({ accountId, label });
+            const payload = JSON.stringify(result);
+            return { content: [{ type: "text", text: payload }] };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `memory-node-exists 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 " +
@@ -1473,7 +1612,7 @@ if (!readOnly) {
     }
     /** 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 label = opts.name ? `"${opts.name}"` : opts.sessionId.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);
@@ -1492,12 +1631,12 @@ if (!readOnly) {
         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). " +
+        "Without sessionId: 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 sessionId: 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
+        sessionId: z
             .string()
             .optional()
             .describe("If provided, returns messages for this conversation. If omitted, lists all conversations."),
@@ -1521,20 +1660,20 @@ if (!readOnly) {
             .number()
             .optional()
             .describe("Maximum results (default 50 for conversations, 200 for messages)"),
-    }, async ({ conversationId, agentType, agentSlug, since, includeMessages, limit }) => {
+    }, async ({ sessionId, agentType, agentSlug, since, includeMessages, limit }) => {
         if (!accountId)
             return refuseNoAccount("conversation-list");
         const startTime = Date.now();
         const dbSession = getSession();
         try {
-            if (conversationId) {
+            if (sessionId) {
                 // 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})
+                const result = await dbSession.run(`MATCH (m:Message)-[:PART_OF]->(c:Conversation {sessionId: $sessionId, 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) });
+             LIMIT $limit`, { sessionId, accountId, limit: int(messageLimit) });
                 if (result.records.length === 0) {
                     return {
                         content: [{ type: "text", text: "No messages found for this conversation." }],
@@ -1546,7 +1685,7 @@ if (!readOnly) {
                     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`);
+                process.stderr.write(`[conversation-list] [${accountId}] mode=messages sessionId=${sessionId.slice(0, 8)}… count=${result.records.length} (${Date.now() - startTime}ms)\n`);
                 return {
                     content: [{ type: "text", text: formatted.join("\n---\n") }],
                 };
@@ -1579,7 +1718,7 @@ if (!readOnly) {
              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,
+             RETURN c.sessionId AS sessionId,
                     c.agentType AS agentType,
                     c.agentSlug AS agentSlug,
                     c.name AS name,
@@ -1594,11 +1733,11 @@ if (!readOnly) {
                     };
                 }
                 const formatted = result.records.map((r) => {
-                    const id = String(r.get("conversationId") ?? "");
+                    const id = String(r.get("sessionId") ?? "");
                     const msgCount = Number(r.get("messageCount") ?? 0);
                     const header = formatConversationHeader({
                         name: r.get("name"),
-                        conversationId: id,
+                        sessionId: id,
                         agentType: String(r.get("agentType") ?? ""),
                         agentSlug: r.get("agentSlug"),
                         createdAt: String(r.get("createdAt") ?? ""),
@@ -1634,7 +1773,7 @@ if (!readOnly) {
            ${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,
+           RETURN c.sessionId AS sessionId,
                   c.agentType AS agentType,
                   c.agentSlug AS agentSlug,
                   c.name AS name,
@@ -1648,13 +1787,13 @@ if (!readOnly) {
                 };
             }
             const formatted = result.records.map((r) => {
-                const id = String(r.get("conversationId") ?? "");
+                const id = String(r.get("sessionId") ?? "");
                 const msgCount = typeof r.get("messageCount") === "number"
                     ? r.get("messageCount")
                     : Number(r.get("messageCount"));
                 return formatConversationHeader({
                     name: r.get("name"),
-                    conversationId: id,
+                    sessionId: id,
                     agentType: String(r.get("agentType") ?? ""),
                     agentSlug: r.get("agentSlug"),
                     createdAt: String(r.get("createdAt") ?? ""),
@@ -1691,7 +1830,7 @@ if (!readOnly) {
             .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()
+        sessionId: 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)"),
@@ -1702,7 +1841,7 @@ if (!readOnly) {
             .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 }) => {
+    }, async ({ category, key, value, source, mode, sessionId, profileFields, personFields, mergeSourceIds }) => {
         if (!accountId)
             return refuseNoAccount("profile-update");
         try {
@@ -1717,7 +1856,7 @@ if (!readOnly) {
                 value,
                 source,
                 mode,
-                conversationId,
+                sessionId,
                 profileFields: profileFields,
                 personFields,
                 mergeSourceIds,
@@ -1901,15 +2040,15 @@ if (!readOnly) {
         "(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."),
+        sessionId: z.string().min(1).describe("The Conversation node's sessionId 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 }) => {
+    }, async ({ sessionId, pattern }) => {
         if (!accountId)
             return refuseNoAccount("conversation-memory-expunge");
         try {
-            const result = await conversationMemoryExpunge({ accountId, conversationId, pattern });
+            const result = await conversationMemoryExpunge({ accountId, sessionId, pattern });
             const lines = [
-                `Expunged "${result.pattern}" from conversation ${result.conversationId.slice(0, 8)}…`,
+                `Expunged "${result.pattern}" from conversation ${result.sessionId.slice(0, 8)}…`,
                 `:Memory nodes scanned: ${result.nodesScanned}`,
                 `Properties nulled: ${result.propertiesNulled}`,
             ];
@@ -1967,7 +2106,7 @@ eagerTool(server, "conversation-search", "Search conversation history using sema
         try {
             const conversationSessionId = resolveSessionId();
             const sessionClause = conversationSessionId
-                ? "AND node.conversationId = $sessionId"
+                ? "AND node.sessionId = $sessionId"
                 : "";
             const result = await dbSession.run(`CALL db.index.vector.queryNodes('message_embedding', $limit, $embedding)
            YIELD node, score
@@ -1979,7 +2118,7 @@ eagerTool(server, "conversation-search", "Search conversation history using sema
            RETURN node.messageId AS messageId,
                   node.role AS role,
                   node.content AS content,
-                  node.conversationId AS conversationId,
+                  node.sessionId AS sessionId,
                   c.name AS sessionName,
                   node.createdAt AS createdAt,
                   score
@@ -2000,7 +2139,7 @@ eagerTool(server, "conversation-search", "Search conversation history using sema
                 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 convId = r.get("sessionId");
                 const sessionName = r.get("sessionName");
                 const convPrefix = convId ? convId.slice(0, 8) : "unknown";
                 const convLabel = sessionName
@@ -2010,7 +2149,7 @@ eagerTool(server, "conversation-search", "Search conversation history using sema
             });
             // Diagnostic: log when admin search results span multiple conversations
             const distinctConvIds = new Set(result.records
-                .map((r) => r.get("conversationId"))
+                .map((r) => r.get("sessionId"))
                 .filter(Boolean));
             if (distinctConvIds.size > 1) {
                 const prefixes = [...distinctConvIds].map((id) => id.slice(0, 8));
@@ -2082,7 +2221,7 @@ server.tool("image-fetch", [
 // bypassing this tool.
 server.tool("memory-typed-edge-pass", "Run the typed-edge auto-extraction pass over prose-bearing nodes this account wrote since sinceIso. Reads Message/Page/Meeting/Email/Idea/Note/Post/Report nodes, batches them, asks Haiku for typed-edge proposals against the closed allowlist (ATTENDED, WORKS_AT, INVESTED_IN, FOUNDED, ADVISES, MENTIONS, AUTHORED, ATTACHED_TO, REFERENCES), validates each proposal inline, and MERGEs accepted edges with createdBy provenance. Returns the counters (nodes, proposed, accepted, rejected, failed, ms) for the caller to hand back to admin's session-retrospective-mark-complete.", {
     sinceIso: z.string().describe("ISO timestamp lower bound. Prose nodes with updatedAt >= sinceIso are processed."),
-    conversationId: z.string().optional().describe("Conversation id stamped onto the createdBy provenance of MERGEd edges. Defaults to CONVERSATION_ID env if absent."),
+    sessionId: z.string().optional().describe("Conversation id stamped onto the createdBy provenance of MERGEd edges. Defaults to SESSION_ID env if absent."),
 }, async (args) => {
     if (!accountId)
         return refuseNoAccount("memory-typed-edge-pass");