engram-routing

Engram Routing

The runtime includes an Engram-style lookup over approved routing instincts. It annotates the planner result, not replaces it, and is not a hard fast path.

Procedure

What ships

• agent_foundry/logging_db/: multi-head N-gram lookup, instinct storage
• agent_foundry/daemon.py: GET /engram and /plan annotation
• CLI: learn, instincts, instinct-approve

An instinct is a trigger pattern learned from execution history. It becomes eligible only after it is approved and its confidence clears the caller's threshold.

How lookup works

1. Normalize the prompt and derive ordered N-gram heads.
2. Look up approved instincts by their stored hashes.
3. Require at least two heads to agree, except legacy single-head rows.
4. Prefer a project-scoped row only after it has enough samples.
5. Return the best match with a gate score from keyword overlap.

The daemon uses a higher confidence floor for /plan annotation than for a direct /engram query. Inspect the current constants in daemon.py rather than assuming a value.

Inspect and approve

agent-foundry learn
agent-foundry instincts
agent-foundry instincts --approved
agent-foundry instincts --explain <id>
agent-foundry instinct-approve <id>

learn analyzes the execution log and updates instinct confidence. It prints new and updated counts plus the learned patterns.

Direct lookup:

curl "http://127.0.0.1:8765/engram?prompt=review%20the%20auth%20middleware"

A hit includes the skill id, trigger pattern, confidence, sample count, scope, and gate score. A miss returns null; that is a normal cold-start result.

What /plan does with a hit

/plan still runs the planner. When an Engram hit clears the confidence and gate-score checks, the response gains an engram_cache_hit field. Treat that field as evidence about routing, not as a substitute for the plan.

Limits

• A hash hit alone is weak evidence; the gate score must also clear its floor.
• Unapproved instincts never route.
• New prompts usually miss. Falling back to the planner is expected.
• Lookup is an indexed database query, not a guarantee of constant-time

behavior under every load.

• The table learns from completed executions; a fresh install has no history.

Anti-patterns

• Hard-routing on hash equality without the gate score.
• Approving instincts from a handful of runs.
• Treating /engram as a complete planner.
• Letting unapproved or stale patterns accumulate without review.
• Claiming a hit rate the repository has not measured.

Verification Checklist

• [ ] learn runs against a populated execution log.
• [ ] instincts --approved lists the pattern used for the test.
• [ ] /engram returns a hit for the known prompt and null for an unrelated one.
• [ ] /plan still returns a full plan when an Engram hit exists.
• [ ] The response names the matched instinct and its confidence.