| 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.
