# 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 Real Agent-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 The maxy MCP tool names are bound to the live registry: the canonical long name `mcp__plugin_memory_memory__` is generated from the memory plugin's manifest, a build gate fails when any instruction names a tool the registry does not serve, and a PostToolUse hook turns a missing-tool call into a fixed envelope. So a missing memory tool is one of two distinct states, not the single "failed to start" the old contract assumed: - **Server dead.** None of the `mcp__plugin_memory_memory__*` tools appear in your tool list at all. The per-account memory server did not start; the platform's `[mcp-init-error] server=memory` line in the per-conversation stream log names it. - **Name not registered.** The server is up and other `mcp__plugin_memory_memory__*` tools are present, but a specific call returns `No such tool available`. The `mcp-tool-missing` hook has already logged `[mcp-tool-missing] server=memory tool=` and returned the deterministic envelope you are reading. In either state, reply once with exactly: > The memory MCP server is unavailable 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 `mcp__plugin_graph_graph__maxy-graph-read_neo4j_cypher` (it is read-only — every write goes through the schema-aware memory tools), do not paraphrase, do not describe the server as "warming up". The 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__plugin_admin_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__plugin_admin_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__plugin_memory_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__plugin_memory_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 `LocalBusiness` 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__plugin_memory_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__plugin_memory_memory__conversation-memory-expunge` | Removes deny-listable content from `:Memory` nodes scoped to one conversation. Requires an explicit pattern and sessionId. 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__plugin_memory_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`. | | "update X by name, search didn't return it", "wire this Org but search came back empty", "I know it exists but I don't have the elementId" | `mcp__plugin_memory_memory__memory-update-by-name` | Repair surface for the case where `memory-search` cannot return a row you know exists by name. Resolves the unique `(label, name, accountId)` tuple, then delegates to `memory-update`. Rejects loudly on zero or ambiguous matches (the rejection lists candidate elementIds so you can pick one). Trashed nodes excluded. Use this only after `memory-search` failed — for normal updates, get the elementId from search and call `memory-update` directly. | | "don't surface these substrings in future memory results", "watch for this string" | `mcp__plugin_memory_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 IDENTITY.md doctrine forbids `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__plugin_memory_memory__memory-delete` with the `elementId`. Do not batch-delete by pattern — on 2026-04-20 an autonomous orphan-delete rule wiped 19 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 ``` Earlier 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 ``` ## Projecting `memory-search` fields `memory-search` accepts an optional `fields: string[]` that narrows each result's `properties` to the named keys. Ranking is unaffected — the hybrid pipeline sees the full text either way. Only the response payload shrinks. When to project: - **Known-shape lookups.** Resolving a slug to a `name`, looking up a Person's `phoneNumber`, fetching a Task's `status`. You know which keys you need; bios, notes, source URLs do not belong on every turn. - **High-fan-out reads.** `limit: 20` against a verbose label class — trim each row to the keys you'll actually quote. When NOT to project: - **Open-ended recall.** "What do you know about Alice?" — you do not yet know which property carries the answer; omit `fields` and read the full row. - **Triage / first-contact reads.** Same reasoning. Semantics: - `fields` omitted → full payload (today's behaviour). - `fields: ["name", "slug"]` → only those keys per row. - `fields: []` → empty `properties` object — explicit "no properties", distinct from "all". - Unknown keys are silently skipped. Rows without a requested key omit it on that row. - `related[*].properties` is NOT projected (separate concern). Worked example: ```ts // Resolving a contact's phone number from a slug — payload-minimal. memory-search({ query: "alice cooper", labels: ["Person"], fields: ["name", "phoneNumber"], }); ``` ## When to switch back to memory-search - "Things similar to X" → `memory-search` (vector + BM25 hybrid) - "Candidates to rank by criterion Y" → `memory-search` for the pool, rank in-turn yourself - "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.