@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/memory/skills/conversation-archive/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: conversation-archive
+description: Source-agnostic ingest for conversation transcripts. One skill for WhatsApp `_chat.txt`, Telegram, Signal, LinkedIn DMs, Zoom transcript, meeting minutes, iMessage, Slack, and any future source — `source` is a property on `:ConversationArchive`, never a separate skill or plugin. Confirms the owner + every distinct sender against existing `:AdminUser` / `:Person` nodes (no auto-creation), then invokes the deterministic Bash entry `conversation-archive-ingest.sh` with `--source <enum>`. The script normalises the source (per-source pluggable function), sessionizes at gap-hours boundaries, classifies each session via Haiku (mode='chat') into `:Section:Conversation` chunks with summary + topic keywords, and writes them under a parent `:ConversationArchive` MERGEd on `conversationIdentity = sha256(accountId + ":" + sortedParticipantElementIds)`. Re-imports are delta-append: prior chunks are never touched; only messages after `lastIngestedMessageHash` flow through the pipeline. Triggers when the operator drops any conversation export (file or directory) into chat.
+---
+
+# Conversation Archive — source-agnostic transcript ingestion
+
+One skill, one bash entry, one writer. The pipeline is identical for every conversation source. The only source-specific code is the per-source normaliser (a pluggable function under [`platform/plugins/memory/mcp/src/lib/conversation-normalisers/`](../../mcp/src/lib/conversation-normalisers/)). New sources = a new normaliser file + an enum entry, never a new skill.
+
+## Confirmed sources (Phase 0)
+
+`whatsapp` ships today (relocated grammar from the retired `whatsapp-import` plugin). Other sources land as needed:
+- `telegram` — Telegram JSON export
+- `signal` — Signal text export
+- `linkedin-messages` — LinkedIn DM thread export (LinkedIn *connections* stay flat-dataset; only DMs route here)
+- `zoom-transcript` — Zoom .vtt / .txt transcript
+- `meeting-minutes` — operator-supplied meeting notes
+- `imessage` — iMessage backup export
+- `slack` — Slack channel export
+
+Until a normaliser ships, the bash entry loud-fails with the implemented set listed in the error.
+
+## Owner + all-participants confirmation (mandatory first step)
+
+A conversation transcript carries N distinct senders (1 owner + N-1 others). Every distinct senderName must resolve to an existing `:AdminUser` or `:Person` elementId before the script runs — the writer LOUD-FAILs on any unresolved sender.
+
+The flow:
+
+1. **Identify the source.** Look at the file the operator dropped — `_chat.txt` ⇒ `whatsapp`; `*.json` from a Telegram export ⇒ `telegram`; `.vtt` ⇒ `zoom-transcript`; `.txt` of formatted meeting notes ⇒ `meeting-minutes`; etc. If unsure, ask the operator one question to disambiguate.
+
+2. **Read the file head** to discover senders before the script runs. Read the first ~50 lines (or use a per-source preview heuristic). Extract distinct sender display names. The operator never sees the script's own counters — surface a one-line histogram (`Sender '<name>' (<count> messages)`) per distinct sender.
+
+3. **List candidate `:AdminUser` and existing `:Person`** rows for the senders via `mcp__graph__maxy-graph-read_neo4j_cypher`.
+
+4. **Iterate the histogram, one operator question per distinct senderName.** For each sender: `"Sender '<name>' (<count> messages) — pick existing :AdminUser/:Person or block?"`. The operator either picks an existing elementId or names "block" (refuses to map to a node). **Never auto-create a `:Person`** — the operator must confirm a canonical node, mirroring `feedback_archives_are_not_documents.md`'s closed-set discipline.
+
+5. **Identify the owner** from the resolved set — the operator who exported the chat. Echo back: `"Owner = :AdminUser <name> (<elementId>); other participants = <list>. Confirm yes/no."`
+
+6. **Persist the resolved IDs** as `--owner-element-id` + `--participant-person-ids <csv>` for the script call.
+
+DM and group follow the identical flow. A 1:1 chat resolves 2 senders; a group resolves N senders. Identity (`conversationIdentity = sha256(accountId + ":" + sortedParticipantElementIds.join(","))`) is identical regardless of group size — DM and group use the same MERGE key. Source format (whatsapp / telegram / slack) does not affect identity.
+
+## Step 2 — invoke the script (background + heartbeat)
+
+The Haiku classify loop on a multi-thousand-message archive can take minutes. The Claude Agent SDK closes the response stream after **180 seconds of model silence**, so issuing the bash in the foreground guarantees a stall. The script is invoked in the **background** and its progress file is polled on a heartbeat — the script writes one fsync'd progress line per Haiku iteration, and surfacing those lines as chat tokens keeps the SDK silence timer reset.
+
+### Identity
+
+`ACCOUNT_ID` and `USER_ID` come from the agent's process env (plumbed by `spawn-env.ts` into every Bash subprocess). The script LOUD-FAILs on missing or malformed values; the operator never passes them as flags. The owner `:AdminUser` elementId is derived from `(ACCOUNT_ID, USER_ID)` inside the script via Cypher — `--owner-element-id` is gone.
+
+### Background invocation
+
+```bash
+bash platform/plugins/memory/bin/conversation-archive-ingest.sh <source-path> \
+  --source <whatsapp|telegram|signal|linkedin-messages|zoom-transcript|meeting-minutes|imessage|slack|other> \
+  --participant-person-ids <id1>,<id2>,... \
+  --scope <admin|public> \
+  --session-id <unique-id>
+```
+
+Issue with `run_in_background: true`. The script's first stdout line is:
+
+```
+[conversation-archive] progress-file=<absolute-path-to-progress-file>
+```
+
+Capture that path. The progress file lives at `data/accounts/$ACCOUNT_ID/logs/conversation-archive-$SESSION_ID.log` and is opened with append + fsync per write, so every line is durable on disk before the script proceeds.
+
+Optional flags:
+- `--timezone <iana>` — IANA zone for timestamps (default `Europe/London`).
+- `--date-format <DD/MM/YY|MM/DD/YY|DD/MM/YYYY|MM/DD/YYYY>` — WhatsApp only; override auto-detect for ambiguous locales.
+
+Sessions split deterministically at 8h gap (fixed code constant). The legacy `--session-gap-hours` flag is removed: chunked chat-mode classify absorbs oversize sessions internally so the gap value is no longer an operational lever. Passing the legacy flag FAILs at `phase=argv`.
+
+`--rebuild` (operator-issued only; never agent-autonomous — see Doctrine below): treats the run as first-ingest, deletes prior `:Section:Conversation` chunks for THIS export's `archiveSha256`, and re-classifies the entire archive. The skipped-cursor-lookup means a `--rebuild` and a fresh-export-with-different-bytes are operationally equivalent — one is destructive on identifiable bytes, the other is additive.
+
+### Heartbeat protocol
+
+Every 30 s while the background bash is live:
+
+```bash
+tail -n 100 <progress-file>
+```
+
+The bin emits one **derived** progress line per session boundary; the agent surfaces those (and only those) as chat tokens.
+
+Grep contract — surface ONLY these line shapes to operator chat:
+
+| Line shape (bin emits) | Surface as |
+|---|---|
+| `[conversation-archive] progress sessionIndex=K/N pct=P chunks-so-far=X elapsed-ms=M` | `Classifying session K/N (P%) — chunks so far X — elapsed <Ms>` |
+| `[conversation-archive] WARN cleanup-dropped chunks=N archiveSha256=<sha>` | **WARN** `cleanup-dropped chunks=N — prior data deleted (only legitimate under --rebuild; STOP and verify if not)` |
+| `[conversation-archive] FAIL phase=…` | verbatim + yield (do not retry) |
+
+Suppress all other `[conversation-archive] …` lines (raw `classify-session`, `session-committed`, `cleanup-skipped`, etc.) — they remain on disk for diagnosis but are not operator-stream noise. The bin's `progress` line is computed deterministically: per-tick percentage arithmetic and running totals come from one place, not from agent prose-rule arithmetic which drifts.
+
+If the tail returns no NEW `progress` line for 60 s while the bg pid is still live: surface one `still on session K/N (P%) — last update <Δ>s ago` and stop emitting until the next advance. Forbidden: emitting "polling progress file" or any meta-status the operator did not request. Forbidden: blind-reissue of the bash.
+
+### Bash poll `description` field — pin progress forward
+
+Each heartbeat `tail` call's `description` carries the most recent progress signal forward, parsed from the prior poll's last surfaced line. Chat timeline rows collapse to the `description`; the body holding the actual progress is hidden until the operator expands every row, so the progress belongs in the title.
+
+Format: `Heartbeat poll — sessionIndex=K/N pct=P chunks-so-far=X`
+
+The first poll (no prior progress yet) is `Heartbeat poll — starting`. Every subsequent poll updates the suffix from the last surfaced progress line; if the most recent poll surfaced the `still on session …` stall line, the suffix becomes `Heartbeat poll — sessionIndex=K/N pct=P stalled <Δ>s`.
+
+The literal label `Heartbeat poll` never shortens — not to `Poll N`, not to `polling`, not to anything else. Forbidden: any heartbeat `description` that drops the progress suffix once a `progress` line has been surfaced; any label other than `Heartbeat poll`.
+
+### Subagent dispatch contract
+
+When the heartbeat loop is delegated to a subagent (ad-hoc `Agent` invocation watching a `run_in_background` bash for this skill), the dispatch prompt MUST include the **Heartbeat protocol** subsection above verbatim — the grep contract, the description-format clause, and the no-NEW-progress branch. Subagents do not inherit memory or per-turn feedback; the dispatch prompt is the only carrier of this convention across the subagent boundary.
+
+A subagent that emits `Poll 58`, `Poll 69`, or any non-canonical label is a contract violation, not stylistic drift. The main agent's prompt-construction step is the gate: the subagent prompt is wrong if the literal string `Heartbeat poll —` is missing from it.
+
+### Resume after silent stall
+
+If the SDK injects `"A background task (subagent) didn't finish"` or the `"180 seconds of silence"` banner, the **first action** is `tail -n 200 <progress-file>` for the prior `sessionId`. The progress file's last line names the session number, message count, and phase — that's the resume context. Every per-session commit is atomic (chunks + cursor advance happen in one Cypher transaction via `memory-ingest`'s `MERGE`/`CREATE`); a kill mid-loop leaves the cursor at session N-1's last message. Re-issuing the same bash with the same argv and same `--session-id` resumes from session N onward without re-classifying anything already written.
+
+Forbidden: blind-reissue without reading the progress file first.
+
+### What the script does
+- Picks the normaliser for `--source`. WhatsApp: locates `_chat.txt` (zip / dir / direct file), parses deterministically, computes `archiveSha256`. Other sources interpret the path according to their own format.
+- Validates every distinct parsed senderName against the closed set of `{owner, participants...}` candidate names. Any miss LOUD-FAILs `parser-miss reason="senderName=<verbatim> not in confirmed participant set ..."`.
+- Computes `conversationIdentity` from accountId + sorted participant elementIds.
+- **Without `--rebuild`** (default): looks up any prior `:ConversationArchive` carrying that identity → reads `lastIngestedMessageHash`. If found, slices parsed lines after the cursor (delta-append). Cursor not found → `FAIL delta-cursor-missing`. Cursor at last line → empty-delta noop (exit 0, no writes; existing chunk count surfaced in JSON summary). **With `--rebuild`**: skips the prior-cursor lookup entirely; every line is treated as first-ingest delta; the first session's `memory-ingest` deletes prior chunks for THIS `archiveSha256` and the new cursor overwrites the stale one in the same MERGE.
+- Sessionizes the delta lines at the fixed 8h gap (code constant, no flag).
+- Computes the stable archive `title` once: `<source> · <owner> ↔ <others> · <YYYY-MM-DD>→<YYYY-MM-DD>`.
+- For each session: renders as turn-attributed text (`[ts] Sender: body\n…`) and calls `memory-classify` with `mode='chat'`. Oversize sessions dispatch to the chunked-chat path internally — sessionize size is no longer an operator concern. Returns one or more `:Section:Conversation` chunk specs.
+- **Per-session checkpoint:** immediately after each successful classify, calls `memory-ingest` for THAT session's chunks AND advances `lastIngestedMessageHash` / `lastIngestedMessageAt` on the parent `:ConversationArchive` to the last message of that session — atomic (chunk writes + cursor advance happen inside one Cypher transaction). A kill mid-loop leaves the cursor at session N-1's last message; re-issuing with the same argv and `--session-id` resumes from session N onward without re-classifying prior sessions.
+- Server MERGEs the parent on `conversationIdentity` (writing `title` ON CREATE and COALESCE-on-MATCH so a stable title is never overwritten), MERGEs `:PARTICIPANT_IN` edges, CREATEs new chunks, extends the `:NEXT` chain from its tail. The cleanup-by-`archiveSha256` step runs ONLY when `--rebuild` is set AND only on the FIRST per-session call of a run. Every node and edge stamps `source=<enum>` and `createdByAgent='conversation-archive'`.
+
+NO insight pass runs. Phase 2 (operator-driven `:Observation` / `:Task` / `:Preference` derivation against chunks) is its own follow-up task — and applies uniformly to every source once chunks exist.
+
+## Three operator messages per ingest
+
+After the script succeeds, formulate the three operator-facing messages from the JSON summary on stdout (one operator message per surfaceable phase):
+
+1. **Parse summary.** `Parsed <archiveSourceFile> (source=<enum>): <parsed> messages across <sessions> sessions, date range <dateRange.first> → <dateRange.last>. Participants: <senderHistogram[i].name (count), …>.`
+2. **Classify summary.** `Classified into <chunks> chunks, covering: <topicKeywords[0], topicKeywords[1], …>.`
+3. **Write summary.** `Created :ConversationArchive <archiveElementId> with <chunks> :Section:Conversation chunks (NEXT chain length <chunks - 1>). Participants linked via :PARTICIPANT_IN: <participantsLinked>.`
+
+For an empty-delta re-import (`delta.kind === "empty-delta"`): emit only message 1 + a noop line `noop reason="no new messages since <priorLastIngestedMessageAt>"`.
+
+## Stdout JSON shape (success)
+
+```json
+{
+  "archiveElementId": "4:abcd…:42",
+  "conversationIdentity": "<sha256-hex>",
+  "archiveSha256": "<sha256-hex>",
+  "archiveSourceFile": "_chat.txt",
+  "source": "whatsapp",
+  "parsed": 1707,
+  "mediaSkipped": 0,
+  "systemSkipped": 0,
+  "delta": { "kind": "first-ingest|delta|empty-delta", "deltaStart": 0, "deltaMessages": 1707 },
+  "sessions": 38,
+  "chunks": 142,
+  "nextEdgesCreated": 141,
+  "participantsLinked": 2,
+  "dateRange": { "first": "2024-01-15T09:30:00+00:00", "last": "2026-04-30T18:42:00+01:00" },
+  "senderHistogram": [{ "name": "Joel", "count": 812 }, { "name": "Adam", "count": 895 }],
+  "topicKeywords": ["pricing", "scheduling", "introductions", "..."],
+  "ms": 6800
+}
+```
+
+## Failure path — single FAIL line
+
+- **Exit non-zero** + one stderr line: `[conversation-archive] FAIL phase=<argv|parse|classify|delta-cursor-missing|memory-ingest|uncaught> reason="..."`. Surface this verbatim to the operator and yield. **Do not retry.**
+- `parser-miss` LOUD-FAIL: an unconfirmed senderName slipped through. Either re-run with the missing :Person elementId added to `--participant-person-ids`, or report a parser bug.
+- `delta-cursor-missing` LOUD-FAIL: the prior `lastIngestedMessageHash` is not present in the re-export. Either the operator deleted prior messages from the archive, or this is a different chat. Investigation required — never re-run blindly.
+
+## Idempotency
+
+- **Re-running the same export bytes is a no-op by default.** The bin reports the existing chunk count and exits 0; cursor and chunks are unchanged. An earlier contract that ran cleanup-by-`archiveSha256` on every same-bytes re-run was the destructive primitive that combined with `--session-gap-hours` to silently destroy 138 chunks (Adam Mackay incident, 2026-05-04) — that path is closed.
+- **Re-running with appended messages** (a fresh export from the same chat with new messages at the tail): cursor lookup finds the prior `lastIngestedMessageHash`, slices new messages, sessionizes only those, and appends new chunks at the tail of the existing `:NEXT` chain. Pre-existing chunks are never touched.
+- **Destructive rebuild** requires the explicit `--rebuild` flag — and only the operator may pass it (see Doctrine below). With `--rebuild`, the bin treats the run as first-ingest, the FIRST session's writer cleans prior chunks for the matching `archiveSha256`, the cursor is overwritten by that session's MERGE, and the heartbeat surfaces a WARN line so the destructive action is operator-visible.
+- **Re-ingesting into a previously-trashed archive** revives the parent before MERGE. If the operator drag-trashed a `:ConversationArchive` and then re-runs ingest (delta or `--rebuild`), `memory-ingest`'s `ingestConversationArchive` strips `:Trashed` from the matching `conversationIdentity` so the MERGE binds to a non-trashed parent — otherwise the chunks would land under a `:Trashed` parent the graph UI hides, making the entire archive (and every freshly-written chunk under it) invisible until something else clears the label. Mirrors the KnowledgeDocument trash-revival path.
+
+## Doctrine
+
+- **`--rebuild` is operator-issued only.** The agent must NEVER propose `--rebuild` as a fix for any FAIL phase, classifier error, oversize-session report, or partial-state recovery. The operator must type `--rebuild` themselves. Agent-autonomous `--rebuild` would re-introduce a silent-partial-wipe surface; the flag exists exclusively for operators reasoning about identifiable export bytes they want to re-classify.
+- **Use a fresh export** (different `archiveSha256`) for every legitimate re-classify case the agent surfaces. Same-bytes re-classify is the operator's call, not the agent's.
+
+## Verification (post-write)
+
+Run via `mcp__graph__maxy-graph-read_neo4j_cypher`:
+
+- `MATCH (a:ConversationArchive { conversationIdentity: $cid }) RETURN elementId(a), a.source, a.lastIngestedMessageAt, a.lastIngestedMessageHash` — `source` matches `--source`; counters agree with the JSON summary.
+- `MATCH (a:ConversationArchive { conversationIdentity: $cid })-[:HAS_SECTION]->(c:Section:Conversation) RETURN count(c)` — equals `chunks`.
+- `MATCH (a:ConversationArchive { source: $source }) RETURN count(a)` — uses the `(accountId, source)` index.
+- `MATCH (p)-[:PARTICIPANT_IN]->(:ConversationArchive { conversationIdentity: $cid }) RETURN count(p)` — equals `participantsLinked` after a first-ingest.
+- Phase 1 wrote ZERO observations: `MATCH (o:Observation)-[:OBSERVED_IN]->(:ConversationArchive { conversationIdentity: $cid }) RETURN count(o)` — should be 0 today (Phase 2 deferred).
+
+## What this is not
+
+- **Not** the live `whatsapp` plugin. That plugin (Baileys QR pairing) holds messages in an in-memory store cleared on restart. This skill imports historical exports into Neo4j as persistent graph nodes.
+- **Not** a media-transcription pipeline. Voice notes, photos, PDFs are skipped at parse with a counter logged.
+- **Not** an insight-extraction pass. Phase 2 (`:Observation` / `:Task` / `:Preference` / `:MENTIONS` derivation, anchored to chunks) ships in its own task and applies uniformly to every source.
+- **Not** an archive-wide importer. Flat datasets (LinkedIn connections, CRM exports) are first-class entities + natural edges, not `:ConversationArchive` — `feedback_archives_are_not_documents.md` stands.
+- **Not** automatic. The owner + all-participants confirmation gate is mandatory before any line is written.

package/payload/platform/plugins/memory/skills/conversation-archive-enrich/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: conversation-archive-enrich
+description: Source-agnostic Phase 2 for any `:ConversationArchive` — walks the `:Section:Conversation` chunks of one named archive and asks the operator to confirm derived claims row-by-row. Fires only when the operator names a specific archive and asks for insights/enrichment; never auto-fires on Phase 1 completion. Per-row gate (wire / skip / reject) over four kinds — `mention`, `task`, `preference`, `observed-relationship`. Re-runs are idempotent on `(elementId(chunk), kind, contentHash)`, so collapsing duplicates is structural. Invokes the read-only MCP tool `mcp__memory__conversation-archive-derive-insights` to obtain proposals; never writes from the tool's return path. Each `wire` decision runs the proposal's returned `mergeCypher` via `mcp__graph__maxy-graph-write_neo4j_cypher`, or, for `task`, mints the `:Task` via `mcp__tasks__task-create` first and then runs the REFERENCES merge.
+---
+
+# Conversation Archive — chunk-anchored insight derivation
+
+One skill. Walks one `:ConversationArchive`'s chunks in pages. Per chunk, Haiku surfaces high-confidence claims via `mcp__memory__conversation-archive-derive-insights`; per claim, the operator decides `wire / skip / reject`. The tool is read-only; the only writes happen through this skill's per-row dispatch.
+
+## When to invoke
+
+When the operator names a specific archive AND asks for insights, enrichment, or derived claims against it. Concrete triggers:
+
+- "Derive insights from the Adam Mackay WhatsApp archive."
+- "Enrich the Joel × Adam conversation archive — surface anything actionable."
+- "Run Phase 2 on `:ConversationArchive elementId=4:abcd…:42`."
+
+Never auto-fire after a Phase 1 ingest completes — `conversation-archive` (the ingest skill) explicitly writes ZERO observations. Phase 2 is operator-gated by design.
+
+## Resolve the archive
+
+Operator phrasing usually names participants or the source file, not an `elementId`. Resolve via `mcp__memory__memory-search`:
+
+```
+memory-search { query: "<operator's phrasing>", labels: ["ConversationArchive"], expandHops: 0 }
+```
+
+If multiple `:ConversationArchive` rows match, ask the operator to pick by `title` (DM and group archives have stable titles per the predecessor task). If zero match, surface the empty result and yield — never run Phase 2 against the wrong archive.
+
+## Walk the chunks in pages
+
+Page through the chunks with the read-only MCP tool. Default page size is 5 chunks.
+
+```
+mcp__memory__conversation-archive-derive-insights {
+  archiveElementId: "<elementId>",
+  chunkOffset: 0,
+  chunkLimit: 5,
+}
+```
+
+The tool returns:
+
+- A header line with `totalChunks`, `walked=from..to`, `proposalsRemaining`.
+- Zero or more `Proposal N/M` blocks, each carrying `chunkElementId`, `kind`, `contentHash`, `evidenceSnippet`, `proposedAction`, `mergeCypher`, `mergeParams`, and (for `mention` / `observed-relationship`) `resolve:` hints for the operator-confirmed entity resolution.
+
+After processing the page's proposals, advance `chunkOffset` by the page size and re-call until `proposalsRemaining=false`. Empty chunks (no high-confidence claims) are silent — the tool already filtered them.
+
+## Per-row gate
+
+Surface one operator question per proposal. The operator decides `wire`, `skip`, or `reject`. **No batch-confirm.** The doctrine is row-by-row review.
+
+Message shape:
+
+```
+Chunk K/N — kind=<X> — evidence: "<snippet>"
+Proposed: <proposedAction>
+wire / skip / reject ?
+```
+
+Operator answers `wire`, `skip`, or `reject`. Anything else: re-ask the same question.
+
+## On `wire`
+
+Dispatch per kind. Provenance (`createdByTool`, `createdBySession`, `createdAt`) is baked into the proposal's `mergeCypher`; the skill only provides the resolved entity elementIds and the optional `:Task` elementId.
+
+### `mention`
+
+The proposal carries `disambiguation.needsResolution[0]` naming the entity to resolve.
+
+1. Resolve via `mcp__memory__memory-search { query: "<displayName>", labels: ["Person", "Organization"], expandHops: 0 }`.
+2. If multiple candidates: ask the operator to pick by `elementId`. If zero candidates: ask the operator `mint via contact-create / reject`. Minting goes through `mcp__contacts__contact-create` (operator-confirmed canonical Person/Organization — never auto-mint).
+3. Run the `mergeCypher` via `mcp__graph__maxy-graph-write_neo4j_cypher` with `mergeParams` plus `targetElementId=<resolved elementId>`.
+
+A re-run against the same `(chunkElementId, target, contentHash)` collapses on the MERGE — no duplicate edges.
+
+### `task`
+
+1. Mint the `:Task` via `mcp__tasks__task-create` with `title=mergeParams.taskTitle`, optional due hint from `mergeParams.taskDueHint`, `affects=archiveElementId`, `raisedDuringConversationKey=chunkElementId`.
+2. Run the proposal's `mergeCypher` via `mcp__graph__maxy-graph-write_neo4j_cypher` with `mergeParams` plus `taskElementId=<minted Task elementId>`.
+
+The `:Task` itself is the durable artefact; the `REFERENCES` edge to the chunk records the evidence that produced it.
+
+### `preference`
+
+No disambiguation step — the `:Preference` node is account-scoped and MERGE-keyed on `(accountId, contentHash)`. Run the proposal's `mergeCypher` directly via `mcp__graph__maxy-graph-write_neo4j_cypher` with `mergeParams` (no additional substitutions).
+
+The `mergeCypher` MERGEs the `:Preference`, sets category/key/value on first create, and creates the `(:Preference)-[:OBSERVED_IN]->(chunk)` edge that ties the preference to its evidence.
+
+### `observed-relationship`
+
+Two-entity resolution. The proposal carries `disambiguation.needsResolution` with `subject` and `object`.
+
+1. Resolve each via `mcp__memory__memory-search` as in `mention`. Reject the proposal if either entity does not resolve and the operator declines to mint via `contact-create`.
+2. Run the `mergeCypher` with `mergeParams` plus `subjectElementId=<resolved>` and `objectElementId=<resolved>`.
+
+The merged `:RELATED_TO` edge carries `operatorConfirmed: true` so downstream queries can filter speculative relationships out.
+
+## On `skip` or `reject`
+
+`skip` — the operator wants to move on without writing. Note locally and continue. Skips are not persisted; the proposal re-surfaces on the next run.
+
+`reject` — the operator deems the claim wrong. Call `mcp__memory__conversation-archive-enrich-rejection` with `mode: "record"` and the proposal's `chunkElementId`, `kind`, `contentHash`, `archiveElementId`. The tool appends a line to the account's `data/accounts/<accountId>/state/conversation-archive-enrich-rejections.jsonl` sidecar; on every subsequent walk the `conversation-archive-derive-insights` tool filters proposals matching any recorded `(chunkElementId, kind, contentHash)` tuple. Duplicate `record` calls for the same key are silent no-ops.
+
+## Wire undoes prior rejection
+
+After a successful `wire` (any kind), call `mcp__memory__conversation-archive-enrich-rejection` with `mode: "undo"` and the same `(chunkElementId, kind, contentHash)` triple. Operators who change their minds and wire a once-rejected claim should not have to manage rejection state by hand — the wire-then-undo pairing keeps the JSONL aligned with the live graph. Calling `undo` for a key that was never rejected is a silent no-op (`beforeCount=0, afterCount=0`).
+
+## Observability
+
+Per the spec, the tool already emits:
+
+- `[conversation-archive-derive-insights] start accountId=<…> archiveElementId=<…> offset=<n> limit=<n> totalChunks=<N>`
+- `[conversation-archive-derive-insights] chunk=<i>/<N> proposals=<k> elementId=<…> rejections-filtered=<r>` (the `rejections-filtered` field counts proposals dropped by the rejection sidecar this page; field absence = filter not wired)
+- `[conversation-archive-derive-insights] FAIL phase=<haiku|…> reason="..."` (per failing chunk; failures do not abort the walk)
+- `[conversation-archive-derive-insights] done accountId=<…> archiveElementId=<…> walked=<n> proposals=<n> emptyChunks=<n> ms=<n>`
+
+The rejection tool emits one line per write/undo (and one per parse-skip / load-fail when the JSONL is malformed):
+
+- `[conversation-archive-enrich] rejected chunk=<eid> kind=<k> contentHash=<sha> stored` — new rejection appended (or `stored (already-present)` for an idempotent duplicate)
+- `[conversation-archive-enrich] rejection-undone chunk=<eid> kind=<k> contentHash=<sha>` — rejection removed after a wire
+- `[conversation-archive-enrich] rejection-parse-skip line=<n>` — corrupt JSONL line dropped during a walk-time load
+- `[conversation-archive-enrich] rejection-load-fail accountId=<…> reason="…"` — JSONL read errored; walk continues with an empty filter set
+
+The skill itself emits one operator-facing line per row decision:
+
+- `[conversation-archive-enrich] chunk=<i>/<N> kind=<X> action=<wired|skipped|rejected> elementId=<chunkElementId>`
+
+And one end-of-walk summary:
+
+- `[conversation-archive-enrich] done archiveElementId=<…> wired=<n> skipped=<n> rejected=<n> ms=<n>`
+
+## Failure paths
+
+- **`archive-not-found`** — the named elementId did not resolve, or the archive has zero `:Section:Conversation` chunks. LOUD-FAIL surfaced verbatim; the skill yields back to admin. Never silently substitute a different archive.
+- **`haiku` per-chunk fail** — Haiku call failed (rate-limit, network, malformed). The tool continues to the next chunk; the operator sees a `FAIL phase=haiku chunk=i/N` line. Once the page finishes, the skill can be re-invoked with the same `chunkOffset` to retry only the failed chunks.
+- **Entity resolution zero-or-multi** — handled inline in the per-row flow above. Never auto-resolve.
+
+## Verification (post-enrich)
+
+Run via `mcp__graph__maxy-graph-read_neo4j_cypher`:
+
+- All wired writes carry `createdByTool='conversation-archive-derive-insights'`. Count per kind:
+  ```
+  MATCH (c:Section:Conversation)-[m:MENTIONS]->()
+  WHERE m.createdByTool = 'conversation-archive-derive-insights'
+    AND elementId(c) IN $chunkElementIds
+  RETURN count(m)
+  ```
+  (Repeat for `:Task -[:REFERENCES]->`, `:Preference -[:OBSERVED_IN]->`, and `:RELATED_TO`.)
+
+- Idempotency: re-running this skill against the same archive (with the same operator decisions) MUST NOT increase any of the above counts — every MERGE collapses on `contentHash`.
+
+## What this is not
+
+- **Not** an automatic step. The operator names the archive and asks for Phase 2; the skill runs.
+- **Not** a batch-confirm UI. Per-row gate is doctrine; do not synthesise a "wire all visible mentions" shortcut.
+- **Not** a numeric-confidence filter. The Haiku prompt absorbs the confidence floor as a hedging-avoidance instruction — never trust a model-emitted confidence score in code.
+- **Not** a writer of `:Observation` umbrella nodes. The four kinds carry their own provenance via `createdByTool` + `chunkElementId` + `contentHash`; there is no umbrella label.

package/payload/platform/plugins/memory/skills/conversational-memory/SKILL.md

@@ -0,0 +1,108 @@
+# Conversational Memory
+
+Memory accumulates from conversation — never from questionnaires, quizzes, or onboarding forms. The owner reveals who they are and how they work through natural interaction. Your role is to notice, store, and recall that knowledge so every session feels continuous rather than starting from scratch.
+
+## Memory Tools
+
+| Tool | Purpose |
+|---|---|
+| `profile-read` | Read profile and preferences. Use `detail: true` for transparency (confidence, evidence, stats). |
+| `profile-update` | Create or update a preference. Modes: `reinforce`, `update`, `contradict`, `merge`. Also sets UserProfile fields via `profileFields`. |
+| `profile-delete` | Remove a preference. Use when the owner says to forget something. |
+| `conversation-search` | Semantic search over past messages. Use to recall specific past interactions. |
+| `session-compact` | Write session context to the graph at compaction time. |
+
+## When to Observe
+
+Store a preference when the owner reveals something about how they work — either by telling you directly or by demonstrating it through their behaviour.
+
+**Explicit signals** — the owner states something directly:
+- "I prefer short answers"
+- "Never schedule before 10am"
+- "Always CC my partner on invoices"
+- "I make decisions quickly — just give me the options"
+
+Store these with `source: "explicit"`. They carry high initial confidence because the owner said them intentionally.
+
+**Behavioural signals** — the owner demonstrates a pattern without naming it:
+- They consistently ask for summaries instead of details (→ `communication/response_detail: "prefers summaries over detail"`)
+- They always reschedule Monday tasks to Tuesday (→ `scheduling/monday_preference: "avoids Mondays for deep work"`)
+- They reject formal language in drafts and rewrite casually (→ `content/writing_tone: "casual, direct tone"`)
+
+Store these with `source: "behavioural"`. Only store after observing the pattern at least twice — a single instance is noise, not signal. Use `mode: "reinforce"` on second observation.
+
+**What NOT to observe:**
+- One-off task instructions ("send that email now") — these are commands, not preferences
+- Emotional reactions to external events — transient, not characteristic
+- Anything the owner explicitly asks you NOT to remember
+
+## How to Store
+
+Every `profile-update` call should include:
+- `category` — one of: `communication`, `scheduling`, `decision`, `workflow`, `content`, `interaction`
+- `key` — a stable identifier for this preference (e.g., `response_length`, `meeting_time`, `writing_tone`)
+- `value` — the preference in natural language
+- `source` — `"explicit"` or `"behavioural"`
+- `conversationId` — always include this for evidence linking. The conversation ID is available in the session context.
+
+### Modes
+
+- **First observation**: omit `mode` (creates new preference at confidence 0.5)
+- **Re-observation**: use `mode: "reinforce"` (boosts confidence toward 1.0)
+- **Value changed**: use `mode: "update"` (new value, same confidence)
+- **Contradicted**: use `mode: "contradict"` (drops confidence by 0.3)
+- **Overlapping preferences**: use `mode: "merge"` with `mergeSourceIds` to combine
+
+### Keys
+
+Use consistent, descriptive keys. If a preference already exists for the same concept, reinforce or update it rather than creating a duplicate with a different key.
+
+## UserProfile Fields
+
+`profile-update` also sets top-level properties on the UserProfile node via the `profileFields` parameter. This is distinct from preference management:
+
+- **Preferences** (category/key/value) — learned behavioural patterns stored as separate Preference nodes with confidence scores and evidence trails
+- **UserProfile fields** (profileFields) — account metadata stored directly on the UserProfile node: `timezone`, `locale`, `givenName`, `role`, `expertise`
+
+Use `profileFields` when the owner provides factual account information (their timezone, their name, their role) rather than a behavioural preference. Both can be set in a single `profile-update` call.
+
+## Remember and Forget
+
+When the owner explicitly asks you to remember something:
+1. Store it with `source: "explicit"` — this signals high intentionality
+2. Confirm what you stored: "I'll remember that you prefer meetings after 2pm."
+3. Do not embellish — store exactly what they said, not your interpretation
+
+When the owner asks you to forget something:
+1. Call `profile-delete` with the matching `category` and `key`
+2. Confirm: "Done — I've forgotten your preference about meeting times."
+3. If you're unsure which preference they mean, ask before deleting
+
+When the owner corrects a preference:
+1. Call `profile-update` with `mode: "update"` and the new value
+2. Confirm: "Updated — I now know you prefer Tuesdays over Wednesdays for reviews."
+
+## "What Do You Know About Me?"
+
+When the owner asks what you know about them (or any variation — "what have you learned?", "what do you remember?", "do you know my preferences?"):
+
+1. Call `profile-read` with `detail: true`
+2. Present the results conversationally — do not dump raw data
+3. Group by category, include confidence level and how you learned each preference
+4. Offer to correct or remove anything: "Want me to update or forget any of these?"
+
+The detailed response includes confidence labels (strong, moderate, fading, weak) and evidence (which conversations the preference was observed in). Use these to explain your knowledge transparently.
+
+## Memory Precedence
+
+Memory informs the current conversation — it does not override it.
+
+- If the owner's current message contradicts a stored preference, follow the current message. Call `profile-update` with `mode: "contradict"` to adjust the stored preference.
+- If a preference is labelled "fading" (confidence below 0.5), treat it as tentative — do not act on it without checking. Preferences decay over time when not re-observed.
+- If the owner's behaviour has clearly changed, update the preference rather than clinging to the old value. People evolve.
+
+## Session Context
+
+At compaction time, `session-compact` captures the session's key context (decisions, work in progress, open questions, things learned about the owner). This context can be recalled in future sessions via `session-compact-status`.
+
+Preferences captured during a session persist independently of compaction — they are written to the graph as they are observed, not batched at session end.