graph-query

name	graph-query
description	Cross-module architectural Q&A over memory — why / blast-radius / what-changed. Use to ask why something is the way it is, or /graph-query. Not for external research (research) or live status (status).

Graph-query

You answer architectural questions by traversing what the project already knows — the memory drawers, the receipt chain, and provenance — not by re-reading the codebase or searching the web. "Why is the auth boundary here?" "What breaks if I change this schema?" "What pattern keeps recurring?" You ground every answer in stored evidence (a drawer, a receipt, a decision with approved_by), and you say so when the corpus is too thin to answer. You read the knowledge graph; you do not modify it.

What this does / does not do

Does: answer why / blast-radius / pattern / what-changed questions by querying the memory substrate (mem0 → file) + provenance, returning a grounded answer with its evidence drawers. Does not: research external sources (research), report live state (status), or fix/modify anything. An answer with no backing drawer is "insufficient corpus", not a guess.

When NOT to use

• The answer needs external facts (docs, the web) — that is research, not graph-query (graph-query is internal- history only).
• The question is "what is true right now" (current health/state) — that is status.

Reference Routing

Situation	Reference
Drawer search (the substrate)	library/systems/memory/memory-search.py · providers/ (mem0)
Graph traversal (corpus ≥ gate)	library/systems/memory/graph/query.py (refresh via graph/builder.py)
Decision provenance (only approved_by: user authorizes)	library/systems/memory/README.md
Receipt write delegation	engine/shared/references/script-delegation-contract.md

Inputs

Field	Required	Description
question	yes	the architectural question (why / blast-radius / pattern / what-changed)
subject	no	the entity in focus (a module, schema, decision, boundary)
query_type	no	why | blast-radius | pattern | what-changed (else inferred)

How to do it

Step 1 — Classify the query

Type	What you answer
why	the rationale behind a decision/structure (trace to the decisions drawer that set it)
blast-radius	what depends on the subject (traverse co-occurring drawers + provenance citations)
pattern	a recurring structure/decision across the corpus
what-changed	how the subject evolved (drawer valid_from/valid_to + receipt timeline)

Step 2 — Check corpus sufficiency

Architectural traversal needs signal. Refresh the entity-graph (python library/systems/memory/graph/builder.py --workspace <ws> — incremental, cheap) and read <ws>/memory/graph/graph.json. If graph.corpus_sufficient is true (drawers ≥ the ~50 gate), traverse (Step 3). If it is false — a thin corpus — say insufficient corpus and degrade to a direct memory-search result; do not fabricate a traversal. (Premature graph traversal on a sparse store returns noise, not signal — the entity-graph Phase-5 gate.)

Step 3 — Traverse + ground

Traverse the entity-graph via library/systems/memory/graph/query.py — run_query(graph, query_type, subject) returns the resolved nodes, an evidence_drawers list, and a confidence (why / blast-radius / what-changed / pattern). Follow provenance citations and build the answer from the evidence drawers it returns. For a decision question, require approved_by: user before presenting a drawer as an authoritative decision — an inferred decision is labeled as such. (Below the gate, this step is skipped — Step 2 degraded to memory-search.)

Step 4 — Answer + receipt

Present the answer with its evidence drawer IDs and a confidence that drops when the corpus is thin or the drawers are stale. Write a receipt.

Output Contract

graph-query receipt (<workspace>/receipts/graph-query-receipt-<timestamp>.json): base + query_type, subject, answer, evidence_drawers (array of IDs), corpus_sufficient (bool), stale_evidence (count), confidence. persistence: Spec-Anchored.

Proactive Triggers

• The corpus is too thin to traverse: say "insufficient corpus" + a direct search result — never fabricate a blast-radius from nothing.
• A decisions drawer is approved_by: skill_inferred: present it as inferred, not as an authoritative human decision (only user authorizes).
• The supporting drawers are STALE/EXPIRED: flag it and lower confidence — an answer from stale knowledge is a context-poisoning risk.
• The question needs external facts: route to research; graph-query answers from internal history only.

Completion Criteria

Done when: a grounded answer is returned with its evidence drawer IDs, corpus sufficiency is stated, and a receipt is written — or "insufficient corpus" is honestly reported.

Not done if: a blast-radius/why was asserted with no backing drawer; an inferred decision was presented as authoritative; stale evidence was used without flagging.

Next step: the answer informs planning (specify/plan); research if external facts are still needed; memory-mine if the corpus gaps the question exposed should be filled.

Related Skills

• research: External-source investigation. graph-query is internal-history only; they answer different questions.
• memory-mine: Surfaces corpus gaps offline. graph-query answers a specific question; memory-mine maps what's missing.
• status: Live current-state. graph-query answers about the past/structure, grounded in drawers.