@rubytech/create-realagent 1.0.627 → 1.0.630

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

@@ -0,0 +1,195 @@
+<!-- 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.
+
+## 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.
+
+### Enumerate
+
+All nodes, grouped by label, with a human-readable name:
+
+```cypher
+MATCH (n)
+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)
+RETURN elementId(n) AS id, n.givenName, n.familyName, n.email, n.telephone
+ORDER BY n.familyName, n.givenName
+LIMIT 100
+```
+
+### Count
+
+Total across the graph:
+
+```cypher
+MATCH (n)
+RETURN count(n) AS total
+```
+
+By label:
+
+```cypher
+MATCH (n)
+RETURN labels(n)[0] AS type, count(*) AS n
+ORDER BY n DESC
+```
+
+### Find
+
+By exact email:
+
+```cypher
+MATCH (p:Person {email: $email})
+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)
+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
+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 `knowledge_fulltext` index for keyword-style search across
+KnowledgeDocument / Section / Chunk content:
+
+```cypher
+CALL db.index.fulltext.queryNodes('knowledge_fulltext', $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
+```
+
+### 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.