Retrieving: The Strategy-First Ladder

A knowledge graph query costs tens of tokens; opening a source file costs 5,000 to 15,000 tokens. Engrams structures agent retrieval around a Strategy-First Ladder: your agent formulates and verifies implementation plans from self-sufficient graph contracts before opening a single file on disk.

The Strategy-First Ladder

1. 1. Session Briefing (engrams prime): Rehydrate high-level active context, recent decisions, and open threads.
2. 2. Architectural Brief (engrams brief <node|query>): Retrieve full decision text, exact interface contracts, file anchors with symbols, Git drift, and 1-hop neighbors.
3. 3. Search & Pre-Edit Advice (engrams query --full, engrams advise): Query with convention-aware search. If a search yields 0 hits, use the returned Miss-Guidance instead of reading raw files.
4. 4. Selective File Reading (Escalation only): Open only the specific ranges and symbols the graph identified.

1. Session Start — engrams prime

One call replaces half a dozen queries. prime fans out across active-context tracks, decisions, progress, and patterns, returning a single consolidated briefing within your token budget.

engrams prime
engrams prime --budget 1000 --paths src/ops,src/db.rs --tags database

2. The One-Call Architectural Brief — engrams brief

Assembling context around a feature previously took 5 round-trips (decision get + anchor list + pr list + link list + graph neighbors). engrams brief <node|query> collapses all five into a single call:

engrams brief "payment provider"
engrams brief decision:62 --depth 2

Example response (under 200 tokens):

{
  "brief": {
    "summary": "Stripe payment adapter",
    "contract": "fn process(amount: u64, curr: &str) -> Result<Receipt, Error>",
    "status": "active",
    "drift": {
      "stale": false,
      "base_source": "commit",
      "checked": 1
    },
    "anchors": ["src/adapters/stripe.rs"]
  },
  "neighbors": [
    {
      "node": "code:42",
      "kind": "code",
      "path": "src/adapters/stripe.rs",
      "symbols": ["StripeAdapter", "process", "refund"],
      "module_doc": "Stripe API v3 payment integration with webhook retry.",
      "line_count": 148
    }
  ]
}

3. Cross-Type Search — engrams query

Cross-type full-text search over decisions, patterns, and custom data with cross-convention matching: searching for system_user_id automatically matches systemUserId, system-user-id, and system_user_id.

# Standard snippet query
engrams query "authentication"

# Embed full summaries and implementation details (kills the 1+N decision get pattern)
engrams query "auth" --full

# Project specific fields (canonical aliases like summary/name work automatically)
engrams query "database" --fields id,summary

The Miss-Guidance Protocol

When a search matches 0 items, engrams query returns a structured miss_guidance object instead of a blank array. Agents are instructed to re-target using the nearest clusters rather than dumping raw tables into context:

{
  "results": [],
  "miss_guidance": {
    "hint": "query matched nothing; nearest clusters below — retry with one of these terms, tags, or nodes",
    "top_tags": [{"tag": "gcal-sync", "count": 14}, {"tag": "event-bus", "count": 8}],
    "token_hits": [{"token": "outlook", "decisions": 0, "patterns": 0}],
    "recent_decisions": [{"id": 42, "summary": "External calendar sync architecture"}],
    "graph_hubs": [{"node": "decision:42", "score": 0.85}]
  }
}

4. Pre-Edit Constraints — engrams advise & relevant

Run before editing any source file:

• engrams advise <paths> — Fast, machine-readable constraints and current violations for your target files.
• engrams relevant <paths> — Full decision structs with retrieval scores, anchors, and Git staleness drift indicators.

engrams advise src/db.rs src/ops
engrams relevant --staged

5. Fast Server-Side Filtering — decision list --filter

Search decisions directly from the list command without pulling the full table into prompt context:

engrams decision list --filter "payment" --limit 10