@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/memory/mcp/scripts/graph/accept.sh

@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# Acceptance harness for the graph MCP integration.
+#
+# Spawns the graph shim, drives it as a JSON-RPC client over stdio, runs
+# one query per acceptance class, prints PASS/FAIL per check, and exits
+# non-zero if any check fails. Assumes the brand's Neo4j is running and
+# the fixture in fixture.cypher has been seeded.
+#
+# The tools/list assertion guards against FastMCP-joiner drift: the
+# upstream server joins NEO4J_NAMESPACE to each tool name with a hyphen,
+# and the admin allowlist is string-exact. If a future upstream upgrade
+# changes the joiner, the assertion fails with a named reason before any
+# functional check runs.
+#
+# Usage:
+#   PLATFORM_ROOT=~/.maxy/platform bash accept.sh           # infers NEO4J_URI from env
+#   PLATFORM_ROOT=~/.maxy/platform NEO4J_URI=bolt://localhost:7687 bash accept.sh
+#
+# Dependencies: node, python3 (for JSON-RPC framing), uvx (via the shim).
+#
+# Exit codes:
+#   0  all PASS
+#   1  one or more FAIL
+#   2  setup error (shim missing, uvx missing, etc.)
+
+set -euo pipefail
+
+PLATFORM_ROOT="${PLATFORM_ROOT:-$(cd "$(dirname "$0")/../../../../.." && pwd)}"
+SHIM="${PLATFORM_ROOT}/lib/graph-mcp/dist/index.js"
+
+if [[ ! -f "$SHIM" ]]; then
+  echo "FAIL: shim not built at $SHIM — run 'npm run build:lib' in $PLATFORM_ROOT" >&2
+  exit 2
+fi
+
+if ! command -v uvx >/dev/null 2>&1; then
+  echo "FAIL: uvx not on PATH — run: curl -LsSf https://astral.sh/uv/install.sh | sh -s -- -y" >&2
+  exit 2
+fi
+
+PASS=0
+FAIL=0
+TOTAL=0
+
+# Exported env used by the inline Node clients below.
+export SHIM
+export PLATFORM_ROOT
+
+# ---------------------------------------------------------------------------
+# Regression guard: tools/list must register hyphen-joined names only.
+#
+# FastMCP joins NEO4J_NAMESPACE ("maxy-graph") to each upstream tool with a
+# hyphen, producing `maxy-graph-read_neo4j_cypher` and
+# `maxy-graph-get_neo4j_schema`. Claude Code's MCP client adds `mcp__graph__`
+# on top when registering the server — the admin allowlist in
+# platform/ui/app/lib/claude-agent.ts must match those exact names.
+# A future upstream version that changes the joiner (e.g. to underscore)
+# silently re-introduces a class of denial unless this fires.
+# ---------------------------------------------------------------------------
+assert_tools_list() {
+  TOTAL=$(( TOTAL + 1 ))
+  local out
+  if ! out=$(
+    node -e "
+      const { spawn } = require('node:child_process');
+      const proc = spawn('node', [process.env.SHIM], { stdio: ['pipe', 'pipe', 'inherit'] });
+      let buf = '';
+      proc.stdout.on('data', (chunk) => { buf += chunk.toString('utf8'); });
+      const send = (obj) => proc.stdin.write(JSON.stringify(obj) + '\n');
+      send({ jsonrpc: '2.0', id: 1, method: 'initialize',
+             params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'accept.sh', version: '1.0' } } });
+      setTimeout(() => {
+        send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+        send({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} });
+      }, 1500);
+      setTimeout(() => {
+        proc.kill('SIGTERM');
+        const lines = buf.split('\n').filter(Boolean);
+        for (const line of lines) {
+          try { const m = JSON.parse(line); if (m.id === 2) {
+            if (m.error) { console.error('RPC_ERROR: ' + JSON.stringify(m.error)); process.exit(1); }
+            const names = (m.result && m.result.tools || []).map(t => t.name);
+            process.stdout.write(JSON.stringify(names));
+            process.exit(0);
+          } } catch (_) {}
+        }
+        console.error('NO_RESPONSE');
+        process.exit(1);
+      }, 10000);
+    " 2>/dev/null
+  ); then
+    echo "FAIL: tools/list RPC did not respond"
+    FAIL=$(( FAIL + 1 ))
+    return 1
+  fi
+
+  local missing=""
+  for expected in "maxy-graph-read_neo4j_cypher" "maxy-graph-get_neo4j_schema"; do
+    if ! grep -q "\"$expected\"" <<<"$out"; then
+      missing+=" $expected"
+    fi
+  done
+  if [[ -n "$missing" ]]; then
+    echo "FAIL: tools/list missing hyphen-joined names —${missing} (reason: missing-hyphen-tool)"
+    echo "       received: $out"
+    FAIL=$(( FAIL + 1 ))
+    return 1
+  fi
+
+  if grep -qE 'maxy-graph_(read|get|write)' <<<"$out"; then
+    local stray
+    stray=$(grep -oE 'maxy-graph_[a-z_]+' <<<"$out" | sort -u | tr '\n' ' ')
+    echo "FAIL: tools/list contains underscore-joined variant(s) — ${stray}(reason: stray-underscore-tool)"
+    FAIL=$(( FAIL + 1 ))
+    return 1
+  fi
+
+  echo "PASS: tools/list registers hyphen-joined names only (${#out}b response)"
+  PASS=$(( PASS + 1 ))
+  return 0
+}
+
+run_check() {
+  local label="$1"
+  local query="$2"
+  local tool="${3:-maxy-graph-read_neo4j_cypher}"
+  TOTAL=$(( TOTAL + 1 ))
+
+  # Drive the shim via a short Node inline client. Exits 0 with the response
+  # body on stdout when the tool call succeeds; exits 1 on any RPC error.
+  if out=$(
+    node -e "
+      const { spawn } = require('node:child_process');
+      const shim = process.env.SHIM;
+      const tool = process.env.TOOL;
+      const query = process.env.QUERY;
+      const proc = spawn('node', [shim], { stdio: ['pipe', 'pipe', 'inherit'] });
+      let buf = '';
+      proc.stdout.on('data', (chunk) => { buf += chunk.toString('utf8'); });
+      const send = (obj) => proc.stdin.write(JSON.stringify(obj) + '\n');
+      send({ jsonrpc: '2.0', id: 1, method: 'initialize',
+             params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'accept.sh', version: '1.0' } } });
+      setTimeout(() => {
+        send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+        const params = tool === 'maxy-graph-get_neo4j_schema' ? {} : { query };
+        send({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: tool, arguments: params } });
+      }, 1500);
+      setTimeout(() => {
+        proc.kill('SIGTERM');
+        // Look for id:2 response in the buffer
+        const lines = buf.split('\n').filter(Boolean);
+        for (const line of lines) {
+          try { const m = JSON.parse(line); if (m.id === 2) {
+            if (m.error) { console.error('RPC_ERROR: ' + JSON.stringify(m.error)); process.exit(1); }
+            const text = m.result && m.result.content && m.result.content[0] && m.result.content[0].text || '';
+            process.stdout.write(text);
+            process.exit(0);
+          } } catch (_) {}
+        }
+        console.error('NO_RESPONSE');
+        process.exit(1);
+      }, 10000);
+    " 2>/dev/null
+  ); then
+    if [[ -n "$out" ]]; then
+      echo "PASS: ${label} (response ${#out}b)"
+      PASS=$(( PASS + 1 ))
+    else
+      echo "FAIL: ${label} (empty response)"
+      FAIL=$(( FAIL + 1 ))
+    fi
+  else
+    echo "FAIL: ${label} (RPC error or timeout)"
+    FAIL=$(( FAIL + 1 ))
+  fi
+}
+
+# Run the regression guard first. If it fails, abort early — running
+# functional queries with stale tool names produces misleading failures.
+if ! assert_tools_list; then
+  echo ""
+  echo "FAIL — tool registration contract violated; aborting functional checks"
+  exit 1
+fi
+
+export TOOL="maxy-graph-get_neo4j_schema"
+export QUERY=""
+run_check "get_neo4j_schema returns labels" ""
+
+export TOOL="maxy-graph-read_neo4j_cypher"
+
+export QUERY="MATCH (n) RETURN labels(n)[0] AS type, count(*) AS n ORDER BY n DESC LIMIT 20"
+run_check "enumerate by label" "$QUERY"
+
+export QUERY="MATCH (n:Task) RETURN count(n) AS total"
+run_check "count Tasks" "$QUERY"
+
+export QUERY="MATCH (p:Person {email: 'graph-accept@test.maxy.local'}) RETURN elementId(p) AS id, p.givenName, p.email LIMIT 1"
+run_check "find person by email" "$QUERY"
+
+export QUERY="MATCH (p:Person {email: 'graph-accept@test.maxy.local'})-[r]-(m) RETURN type(r) AS rel, labels(m)[0] AS neighbourType LIMIT 10"
+run_check "neighbours of fixture person" "$QUERY"
+
+export QUERY="MATCH (n) WHERE n.createdAt IS NOT NULL RETURN labels(n)[0] AS type, toString(n.createdAt) AS createdAt ORDER BY n.createdAt DESC LIMIT 5"
+run_check "recent nodes projection" "$QUERY"
+
+export QUERY="CALL db.labels() YIELD label RETURN label ORDER BY label"
+run_check "db.labels() schema introspection" "$QUERY"
+
+echo ""
+if [[ $FAIL -eq 0 ]]; then
+  echo "ALL PASS — ${PASS}/${TOTAL}"
+  exit 0
+else
+  echo "FAIL — ${PASS}/${TOTAL} passed, ${FAIL} failed"
+  exit 1
+fi

package/payload/platform/plugins/memory/mcp/scripts/graph/fixture.cypher

@@ -0,0 +1,59 @@
+// Task 557 — acceptance fixture for the graph MCP integration.
+// Seeds one node per primary label so accept.sh can verify enumerate,
+// count, find, neighbours, recent, and schema queries end-to-end.
+// Safe to re-run: MERGE on a synthetic accountId prefix + deterministic ids.
+
+MERGE (p:Person {email: 'graph-accept@test.maxy.local'})
+  ON CREATE SET p.givenName = 'Graph',
+                p.familyName = 'Accept',
+                p.telephone = '+440000557001',
+                p.status = 'active',
+                p.accountId = 'accept-557',
+                p.createdAt = datetime()
+MERGE (b:LocalBusiness {accountId: 'accept-557'})
+  ON CREATE SET b.name = 'Accept Corp',
+                b.businessType = 'test-fixture',
+                b.createdAt = datetime()
+MERGE (s:Service {serviceId: 'accept-557-service-1'})
+  ON CREATE SET s.name = 'Test Service',
+                s.accountId = 'accept-557',
+                s.createdAt = datetime()
+MERGE (t:Task {taskId: 'accept-557-task-1'})
+  ON CREATE SET t.title = 'Acceptance task',
+                t.status = 'open',
+                t.priority = 'P2',
+                t.accountId = 'accept-557',
+                t.createdAt = datetime()
+MERGE (e:Event {eventId: 'accept-557-event-1'})
+  ON CREATE SET e.name = 'Acceptance event',
+                e.status = 'scheduled',
+                e.startDate = datetime(),
+                e.accountId = 'accept-557',
+                e.createdAt = datetime()
+MERGE (c:Conversation {conversationId: 'accept-557-conv-1'})
+  ON CREATE SET c.name = 'Acceptance conversation',
+                c.agentType = 'admin',
+                c.accountId = 'accept-557',
+                c.createdAt = datetime()
+MERGE (m:Message {messageId: 'accept-557-msg-1'})
+  ON CREATE SET m.role = 'user',
+                m.content = 'Acceptance test message',
+                m.accountId = 'accept-557',
+                m.createdAt = datetime()
+MERGE (kd:KnowledgeDocument {attachmentId: 'accept-557-doc-1'})
+  ON CREATE SET kd.name = 'Acceptance document',
+                kd.accountId = 'accept-557',
+                kd.createdAt = datetime()
+MERGE (sec:Section {sectionId: 'accept-557-sec-1'})
+  ON CREATE SET sec.title = 'Section one',
+                sec.accountId = 'accept-557',
+                sec.createdAt = datetime()
+MERGE (ch:Chunk {chunkId: 'accept-557-chk-1'})
+  ON CREATE SET ch.text = 'Chunk text for acceptance.',
+                ch.accountId = 'accept-557',
+                ch.createdAt = datetime()
+MERGE (p)-[:WORKS_FOR]->(b)
+MERGE (b)-[:OFFERS]->(s)
+MERGE (kd)-[:HAS_SECTION]->(sec)
+MERGE (sec)-[:HAS_CHUNK]->(ch)
+MERGE (c)-[:HAS_MESSAGE]->(m);

package/payload/platform/plugins/memory/mcp/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    // Task 753 — narrow to `src/tools/__tests__/` so vitest does not pick up
+    // pre-existing `src/lib/__tests__/` files that use Node's built-in
+    // `node:test` runner (schema-loader / schema-validator / live-schema-source
+    // tests, Task 743). Those files run under their own harness; broadening
+    // this glob to `src/**/__tests__/**` would surface them as parse failures
+    // here without porting them — out of scope for this task.
+    include: ["src/tools/__tests__/**/*.test.ts"],
+    testTimeout: 10_000,
+  },
+});

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -0,0 +1,342 @@
+<!-- Injected into admin system prompt by claude-agent.ts when agentType === "admin". -->
+<!-- Consumed by the upstream mcp-neo4j-cypher server via `maxy-graph-read_neo4j_cypher`. -->
+<!-- Source of truth for node labels and properties: platform/neo4j/schema.cypher + plugins/memory/references/schema-*.md. -->
+
+# Graph interrogation (read-only Cypher cookbook)
+
+When a user asks a relational question about their own graph — *"list all my
+people", "how many tasks do I have", "find the person with email X", "what's
+linked to this business", "show me the 20 most recently created nodes" — use
+`maxy-graph-read_neo4j_cypher` or `maxy-graph-get_neo4j_schema`, not
+`memory-search`. Vector search is for "things like this"; Cypher is for "the
+exact set where".
+
+The connected Neo4j instance contains only this brand's data (per-brand
+instance architecture — see `.docs/neo4j.md`). You never need an account
+filter in the query.
+
+For visual exploration ("can I see this graphically?", "show me the graph"),
+tell the user to open the **Graph** menu item in the burger menu — it opens
+a Maxy-native force-directed view of their own brand's subgraph.
+Do not build ad-hoc HTML visualizations, do not start a static file server,
+do not `Write` an `.html` file and navigate Playwright to it. The one-sentence
+reply ("Open the Graph menu item in the top-right — it opens a visual view
+of your graph") is the correct answer.
+
+## When the graph tools are absent
+
+If neither `maxy-graph-read_neo4j_cypher` nor `maxy-graph-get_neo4j_schema`
+appears in your tool list, the graph MCP server failed to start on this
+device. Reply once with exactly:
+
+> The graph MCP server failed to start on this device. Run the admin
+> system-status check to diagnose — do not retry by other routes.
+
+Then stop. Do not search for a similarly-named tool via `ToolSearch`, do
+not fall back to `cypher-shell` via `Bash`, do not paraphrase — the
+deterministic path through the shim is the only supported way to read
+the graph, and any substitute path loses the read-only + namespace +
+token-limit discipline the upstream server enforces.
+
+## When the memory tools are absent
+
+If `mcp__memory__memory-write`, `mcp__memory__memory-search`,
+`mcp__memory__memory-rank`, `mcp__memory__memory-reindex`,
+`mcp__memory__session-compact`, `mcp__memory__session-compact-status`, or
+`mcp__memory__conversation-search` is missing from your tool list, the
+memory MCP server failed to start on this device. Reply once with
+exactly:
+
+> The memory MCP server failed to start on this device. Run the admin
+> system-status check to diagnose — do not retry by other routes.
+
+Then stop. Do not search for a similarly-named tool via `ToolSearch`, do
+not improvise via `maxy-graph-read_neo4j_cypher` (it is read-only — every
+write goes through the schema-aware memory tools), do not paraphrase.
+A missing memory tool is a deterministic failure of the per-account
+memory server: the platform's `[mcp-init-error] server=memory` line in
+the per-conversation stream log already names it; the user-facing reply
+exists so the operator knows the session cannot proceed without an
+operator-side fix (the loud-fail contract applies equally
+to graph and memory tool initialisation).
+
+## Mutation intents
+
+The graph tools above are read-only. Every write intent has a schema-aware
+tool that already exists — match the user's prose to a tool in this table
+rather than improvising. `mcp__admin__admin-remove` is in your initial
+tool list; the other tools below are deferred (they do not appear until
+you invoke `ToolSearch` by the exact name you pick from the table).
+Do not use `ToolSearch` to *discover* the tool by keyword — identify it
+from the table first, then fetch its schema by exact name.
+
+There is **no autonomous rule engine and no cron** for graph hygiene.
+Cleanup is agent-directed, case by case, using your judgment on the
+evidence in front of you (memory-search results, cypher reads, the
+operator-curated deny-list). Never apply a bulk transformation to the
+graph as a single action.
+
+| User intent | Tool | When to pick this, not the next row |
+|---|---|---|
+| "remove admin X", "take away their admin access", "revoke admin" | `mcp__admin__admin-remove` | Device-level admin offboarding — detaches the `(AdminUser)-[:ADMIN_OF]->(LocalBusiness)` edge and updates `platform/config/users.json`. Not for scrubbing personal data — use the GDPR contact-erase tools for that. |
+| "delete this specific node", "remove this entry by its id", "get rid of node X", "remove orphans", "prune", "clean up" | `mcp__memory__memory-delete` | Soft-deletes a single node by `elementId` (adds `:Trashed`, preserves relationships, snapshots unique keys, invisible to `memory-search` and any `notTrashed`-filtered read). For KnowledgeDocument, cascades to Sections and Chunks. Enumerate candidates first with a Cypher read, confirm with the user, then delete each by `elementId`. There is no bulk "delete everything without relationships" tool. Per the write doctrine (`.docs/neo4j.md` § Write doctrine), **new** orphans should be impossible — every writer now rejects zero-edge calls at the MCP tool-surface. Existing orphans from legacy data are legitimate backfill candidates but are not produced by any live writer; if you see a freshly-created orphan, it is a bug in a writer that bypassed `writeNodeWithEdges`, not expected state. |
+| "undo that delete", "I deleted X by mistake, bring it back", "restore the contact I just trashed" | `mcp__memory__memory-restore` | Removes `:Trashed`, restores snapshotted unique-key properties. Fails loudly when an active node already holds the unique slot (e.g. a fresh `OnboardingState` was created while the old one was in trash) — the error names the conflicting `elementId` so you can ask the user how to resolve. |
+| "empty the trash", "purge old soft-deletes", "what's been sitting in trash and ready to clear" | `mcp__memory__memory-empty-trash` | Hard-deletes trashed nodes whose `trashedAt` is older than `graceDays` (default 30); `dryRun=true` lists candidates without mutating. Use `dryRun` first, show the list to the user, then run for real. For KnowledgeDocument candidates, the on-disk attachment directory is removed too. |
+| "scrub this conversation's memory", "remove this claim the bot picked up", "forget what we said in that thread" | `mcp__memory__conversation-memory-expunge` | Removes deny-listable content from `:Memory` nodes scoped to one conversation. Requires an explicit pattern and conversationId. Not for deleting individual nodes — use `memory-delete`. |
+| "update a property", "fix a typo in a node", "change the role field on X", "null this poisonous string" | `mcp__memory__memory-update` | Targeted property edit on an existing node, schema-validated. Use to null individual string properties matching a deny-list entry once you've identified the offender via a Cypher read. Not for creating new nodes — use `memory-write`. |
+| "don't surface these substrings in future memory results", "watch for this string" | `mcp__memory__graph-prune-denylist-add` | Records a substring as operator-curated signal. Nothing auto-applies it — when a subsequent memory-search or cypher read surfaces a match, use `memory-update` or `memory-delete` with discretion to scrub it. |
+
+**Never run `cypher-shell` via `Bash` to work around the read-only tool.**
+The admin session's `Bash` surface has no path to the per-brand Neo4j
+password (it lives in `${PLATFORM_ROOT}/config/.neo4j-password`,
+unreachable from the admin account's `Bash` cwd, and pre-tool-use hooks
+block `Bash` against the code tree anyway — `.docs/neo4j.md`'s migration
+section is an operator-run runbook, not a path you should replicate in
+chat). Every write intent has a schema-aware tool above. If none of them
+fits, tell the user plainly: *"This operation is not in the admin tool
+surface. It can be added as a task."* — do not invent a workaround.
+
+**Worked example — "prune the stale AdminUsers".** When an admin asks to
+prune stale AdminUser entries (e.g., 15 nodes left over from prior
+installs, none linked by `ADMIN_OF` to a `LocalBusiness`), enumerate them
+with a Cypher read:
+
+```cypher
+MATCH (a:AdminUser) WHERE NOT (a)--() RETURN elementId(a), a.userId, a.createdAt
+```
+
+Show the list to the user. For each confirmed entry, call
+`mcp__memory__memory-delete` with the `elementId`. Do not batch-delete
+by pattern — on 2026-04-20 an autonomous orphan-delete rule wiped the
+sole `OnboardingState` node plus 18 unrelated nodes in one call, with
+no property recovery possible. Structural mass-deletion by shape is
+banned; discretion per node is the only sanctioned path.
+
+## Non-negotiable: never return raw nodes
+
+`RETURN n` dumps every property, including the 768-dim `embedding` float
+array. This blows the context budget on the first row. **Always enumerate the
+properties you want.**
+
+  Wrong: `MATCH (n:Person) RETURN n LIMIT 20`
+  Right: `MATCH (n:Person) RETURN elementId(n) AS id, n.givenName, n.familyName, n.email, n.telephone LIMIT 20`
+
+Apply this convention to every query. Only project the fields you need to
+answer the question. When in doubt, exclude `embedding`, `embeddingText`, and
+any property whose name ends in `_vector`.
+
+## Cookbook
+
+Parameterise results with `ORDER BY` and `LIMIT` every time — even an
+"inventory" query should bound itself. Default limit: 50.
+
+**Trashed nodes are excluded by default.** Every read pattern below filters
+`NOT n:Trashed AND n.deletedAt IS NULL` (the new `:Trashed` label plus the
+legacy `deletedAt` belt-and-braces). To include trashed nodes for a trash
+census or pre-empty audit, drop the filter and add `MATCH (n:Trashed)`.
+
+### Enumerate
+
+All nodes, grouped by label, with a human-readable name:
+
+```cypher
+MATCH (n)
+WHERE NOT n:Trashed AND n.deletedAt IS NULL
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.givenName + ' ' + n.familyName, n.email, '(unnamed)') AS name,
+       elementId(n) AS id
+ORDER BY type, name
+LIMIT 200
+```
+
+One label only:
+
+```cypher
+MATCH (n:Person)
+WHERE NOT n:Trashed AND n.deletedAt IS NULL
+RETURN elementId(n) AS id, n.givenName, n.familyName, n.email, n.telephone
+ORDER BY n.familyName, n.givenName
+LIMIT 100
+```
+
+### Trash census
+
+What's currently in trash, by label:
+
+```cypher
+MATCH (n:Trashed)
+RETURN labels(n) AS types, n.trashedBy AS by, count(*) AS n
+ORDER BY n DESC
+```
+
+Recently trashed (last 7 days), with provenance:
+
+```cypher
+MATCH (n:Trashed)
+WHERE n.trashedAt > datetime() - duration({days: 7})
+RETURN elementId(n) AS id,
+       labels(n) AS types,
+       n.trashedAt AS trashedAt,
+       n.trashedBy AS by,
+       n.trashReason AS reason
+ORDER BY n.trashedAt DESC
+LIMIT 50
+```
+
+Eligible for empty-trash (older than 30 days):
+
+```cypher
+MATCH (n:Trashed)
+WHERE n.trashedAt < datetime() - duration({days: 30})
+RETURN labels(n) AS types, count(*) AS readyToPurge
+ORDER BY readyToPurge DESC
+```
+
+### Count
+
+Total across the graph:
+
+```cypher
+MATCH (n)
+RETURN count(n) AS total
+```
+
+By label:
+
+```cypher
+MATCH (n)
+WHERE NOT n:Trashed AND n.deletedAt IS NULL
+RETURN labels(n)[0] AS type, count(*) AS n
+ORDER BY n DESC
+```
+
+### Find
+
+By exact email:
+
+```cypher
+MATCH (p:Person {email: $email})
+WHERE NOT p:Trashed AND p.deletedAt IS NULL
+RETURN elementId(p) AS id, p.givenName, p.familyName, p.telephone, p.status
+```
+
+Partial name, case-insensitive:
+
+```cypher
+MATCH (p:Person)
+WHERE (toLower(p.givenName) CONTAINS toLower($q)
+   OR toLower(p.familyName) CONTAINS toLower($q))
+   AND NOT p:Trashed AND p.deletedAt IS NULL
+RETURN elementId(p) AS id, p.givenName, p.familyName, p.email
+LIMIT 20
+```
+
+### Neighbours
+
+What is linked to a node (1 hop out, undirected):
+
+```cypher
+MATCH (n)-[r]-(m)
+WHERE elementId(n) = $id
+  AND NOT m:Trashed AND m.deletedAt IS NULL
+RETURN type(r) AS rel,
+       labels(m)[0] AS neighbourType,
+       coalesce(m.name, m.title, m.email, '(unnamed)') AS neighbour,
+       elementId(m) AS neighbourId
+LIMIT 50
+```
+
+### Recent
+
+Most recently created nodes (any label):
+
+```cypher
+MATCH (n)
+WHERE n.createdAt IS NOT NULL
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.givenName + ' ' + n.familyName, n.email, '(unnamed)') AS name,
+       toString(n.createdAt) AS createdAt,
+       elementId(n) AS id
+ORDER BY n.createdAt DESC
+LIMIT 20
+```
+
+Most recently updated:
+
+```cypher
+MATCH (n)
+WHERE n.updatedAt IS NOT NULL
+RETURN labels(n)[0] AS type,
+       coalesce(n.name, n.title, n.email, '(unnamed)') AS name,
+       toString(n.updatedAt) AS updatedAt,
+       elementId(n) AS id
+ORDER BY n.updatedAt DESC
+LIMIT 20
+```
+
+### Schema
+
+All labels present in the graph:
+
+```cypher
+CALL db.labels() YIELD label RETURN label ORDER BY label
+```
+
+All relationship types:
+
+```cypher
+CALL db.relationshipTypes() YIELD relationshipType RETURN relationshipType ORDER BY relationshipType
+```
+
+Or use `maxy-graph-get_neo4j_schema` for a richer one-shot structural summary.
+
+### Fulltext
+
+Use the universal `entity_search` index for keyword-style search
+across every operator-meaningful label — Person, Organization, Task, Event,
+Conversation, KnowledgeDocument, Email, etc. — on every textual property
+the platform's writers assign:
+
+```cypher
+CALL db.index.fulltext.queryNodes('entity_search', $query)
+YIELD node, score
+WHERE score > 0.5
+RETURN labels(node)[0] AS type,
+       coalesce(node.name, node.title, node.heading, '(unnamed)') AS name,
+       score,
+       elementId(node) AS id
+LIMIT 20
+```
+
+Pre-Task-748 the index was named `knowledge_fulltext` and covered only
+`KnowledgeDocument | Section | Chunk`. Existing Pis pick up the rename on
+the next install via `seed-neo4j.sh`.
+
+### Filter by status or category
+
+Events that are cancelled:
+
+```cypher
+MATCH (e:Event {status: 'cancelled'})
+RETURN elementId(e) AS id, e.name, toString(e.startDate) AS start
+ORDER BY e.startDate DESC
+LIMIT 50
+```
+
+Tasks by status:
+
+```cypher
+MATCH (t:Task {status: $status})
+RETURN elementId(t) AS id, t.title, toString(t.createdAt) AS created, t.priority
+ORDER BY t.createdAt DESC
+LIMIT 50
+```
+
+## When to switch back to memory-search
+
+- "Things similar to X" → `memory-search` (vector + BM25 hybrid)
+- "Candidates to rank by criterion Y" → `memory-rank`
+- "Conversations where we discussed Z" → `conversation-search`
+
+Cypher is for relational certainty. Vector search is for similarity. They
+answer different questions; don't use one to fake the other.