@engramlabs/mcp 0.1.2-alpha → 0.1.3-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,81 @@
1
+ # Memorization catalog — what engram-index writes, exactly
2
+
3
+ The reference for phase 2 (memorize) of engram-index. One concern per
4
+ memory; every claim labeled; every procedure seen working.
5
+
6
+ ## Memory formats (write_memory)
7
+
8
+ ### Stack + layout
9
+ ```
10
+ write_memory({ "content": "[proven] Rust workspace, 30+ crates; core/
11
+ adapters/backends split enforced by scripts/ci/check-engine-neutrality.sh
12
+ — evidence: architecture tool showed core crates; CI script read via
13
+ fetch_content" })
14
+ ```
15
+
16
+ ### Invariants (the rules this repo lives by)
17
+ ```
18
+ write_memory({ "content": "[proven] engram-domain must not depend on SQL,
19
+ vector stores, or async runtimes — evidence: check-engine-neutrality.sh
20
+ gates CI; violation names engine types in core crates" })
21
+ ```
22
+ Label `[likely]` when inferred from structure alone ("naming suggests
23
+ layering" is not proof); upgrade to `[proven]` only when a check, test,
24
+ or doc enforces it.
25
+
26
+ ### Sharp edges (what bites)
27
+ ```
28
+ write_memory({ "content": "[proven] bridge symbol: resolve_symbol in
29
+ core/code — 14 dependents across 5 crates; change_impact shows ripple
30
+ into scanner, mcp tools, and tests. Touch last, test wide." })
31
+ ```
32
+ Sources of sharp edges: `architecture` bridge list, `change_impact`
33
+ output on symbols you expect to touch, temporal traps from
34
+ `whats_changed`.
35
+
36
+ ### Core abstractions (the "understand this = understand the system" set)
37
+ ```
38
+ write_memory({ "content": "[proven] MemoryService trait is the central
39
+ abstraction (top PageRank) — every write path flows through it;
40
+ adapters implement, orchestration composes. evidence: architecture
41
+ tool, symbol_context depth 2" })
42
+ ```
43
+
44
+ ## Procedure formats (procedure_put)
45
+
46
+ Only procedures whose steps were SEEN working (CI configs, READMEs,
47
+ this session). Untested steps must say so in `trigger`.
48
+
49
+ ```
50
+ procedure_put({ "name": "verify",
51
+ "trigger": "before handoff",
52
+ "steps": ["cargo fmt --all", "cargo check --workspace",
53
+ "pnpm run typecheck", "pnpm run test",
54
+ "scripts/ci/check-contracts.sh"] })
55
+
56
+ procedure_put({ "name": "scan-repo",
57
+ "trigger": "index refresh",
58
+ "steps": ["scan_repo {path: <repo>}", "architecture {limit: 20}",
59
+ "graph_health {}"] })
60
+ ```
61
+
62
+ ## Entity/relationship formats (put_entity / put_relationship)
63
+
64
+ Top abstractions only — the graph already knows every symbol; entities
65
+ are for the CONCEPTS the graph can't infer:
66
+
67
+ ```
68
+ put_entity({ "name": "Engine Neutrality", "kind": "concept" })
69
+ put_relationship({ "subject": "Engine Neutrality", "predicate":
70
+ "realized_by", "object": "check-engine-neutrality" })
71
+ ```
72
+
73
+ Bridge concepts to the code that realizes them; a concept linked to
74
+ nothing is an orphan in a disconnected subgraph.
75
+
76
+ ## What NOT to memorize
77
+
78
+ - File counts, line counts, dependency version trivia
79
+ - Boilerplate names, test fixture names
80
+ - Anything `architecture`/`symbol_context` answers on demand
81
+ - Session play-by-play (that's engram-learn's job, and only the durable parts)
@@ -0,0 +1,79 @@
1
+ # REA process for code indexing
2
+
3
+ The evidence-first discipline (adapted from the REA — Reverse Engineer
4
+ Anything — method) applied to understanding and memorizing a codebase.
5
+
6
+ ## The process, stage by stage
7
+
8
+ ### 1. Target scoping
9
+ Define what is being understood before touching anything:
10
+ - What kind of system is this? (service, library, app, agent tool)
11
+ - What will "understood" mean here? (can answer where/how questions,
12
+ can plan changes safely, can recall invariants)
13
+ - What is already known? (check staleness — if a fresh index exists,
14
+ only delta-memorize)
15
+
16
+ **Stop condition:** scope stated in one sentence before any tool call.
17
+
18
+ ### 2. Surface mapping
19
+ Map the terrain without reading files:
20
+ - `scan_repo` — the structural pass (symbols, edges, communities)
21
+ - `architecture {limit: 20}` — central symbols, bridges, stats
22
+ - `graph_health` — is the graph trustworthy?
23
+
24
+ Surface mapping answers: how big, how coupled, where does complexity
25
+ live? It does NOT answer how anything works — that's tracing.
26
+
27
+ ### 3. Feature tracing
28
+ Follow one behavior from trigger to outcome through the graph:
29
+ - Start from the entry point (top central symbol, or a named feature)
30
+ - `symbol_context` each hop: callers, callees, community
31
+ - `change_impact` on bridges to understand blast radius
32
+ - `fetch_content` the load-bearing files to verify the graph's story
33
+
34
+ Record every hop: file, symbol, what the edge means. A trace that
35
+ skips a hop is a guess, not a trace.
36
+
37
+ ### 4. Evidence collection
38
+ Every claim gets its evidence AT COLLECTION TIME, not later:
39
+
40
+ | Label | Meaning | Evidence standard |
41
+ |---|---|---|
42
+ | `[proven]` | Verified against source or graph | tool + query + what it showed |
43
+ | `[likely]` | Strong signal, unverified | naming, structure, docs memory |
44
+ | `[guessed]` | Hypothesis only | must say so explicitly |
45
+
46
+ Rules:
47
+ - Never claim how something works without graph/source evidence.
48
+ - Separate facts from interpretation — the label IS the separation.
49
+ - Start with the simplest trace that proves the behavior.
50
+ - Pseudocode-level summaries of files you haven't fetched are `[likely]`
51
+ at best.
52
+
53
+ ### 5. Reconstruction (memorization)
54
+ Turn findings into durable memory — one concern per memory, written so a
55
+ future agent in a fresh session can act on it:
56
+ - Stack + layout invariants
57
+ - Sharp edges (bridges, god modules, temporal traps)
58
+ - Core abstractions (top PageRank, one line each)
59
+ - Build/test/verify procedures (exact commands, only ones seen working)
60
+
61
+ An unmemorized finding is a finding you'll pay for twice.
62
+
63
+ ### 6. Verification (write → read-back)
64
+ - Recall 3 probe queries a future agent would actually ask.
65
+ - A probe that fails = a memory written badly = rewrite it.
66
+ - **An index that cannot be recalled is not an index.**
67
+
68
+ ### 7. Final report
69
+ - N symbols, M modules, core abstractions, bridges to respect
70
+ - What was memorized + confidence split (proven/likely/guessed counts)
71
+ - Unknowns worth investigating — honesty about holes
72
+
73
+ ## The final check (run before claiming done)
74
+
75
+ - What am I missing in the overview?
76
+ - Is each claim proven or just plausible?
77
+ - Did I mistake graph structure for verified behavior?
78
+ - Would these memories survive the next refactor?
79
+ - What evidence would change my mind?
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: engram-learn
3
+ description: Distill durable learnings from a session, doc, or fix into engram — decisions with rationale, gotchas and resolutions, validated procedures, source-grounded facts, belief updates. Trigger on "remember this", "learn from this session", after a meaningful bug fix, or at the end of a substantive work session.
4
+ ---
5
+
6
+ # engram-learn
7
+
8
+ Turn what just happened into durable memory. The agent does the extraction
9
+ and judgment; engram stores and recalls. Learners capture **decisions,
10
+ gotchas, and procedures** — not transcripts.
11
+
12
+ ## Contract
13
+
14
+ 1. No trivia: if a future agent wouldn't act on it, don't write it.
15
+ 2. No duplicates: recall first; update or skip if it's already known.
16
+ 3. Decisions record the *why*, not just the *what*.
17
+ 4. Source-grounded facts cite their source (`store_knowledge`, not `write_memory`).
18
+
19
+ ## Workflow
20
+
21
+ ### 1. What kind of learning is this?
22
+
23
+ | Kind | Tool | Shape |
24
+ |---|---|---|
25
+ | Decision + rationale | `write_memory` | "Decided X over Y because Z" |
26
+ | Gotcha / resolution | `write_memory` | "X bites when Y; fix: Z" |
27
+ | Validated procedure | `procedure_put` | exact steps that worked |
28
+ | Fact from a source | `store_knowledge` | entities/facts with the doc path |
29
+ | Changed stance | `belief_get` → update or let contradiction stand | subject + new position |
30
+ | Replayable doc | `index_docs` | verbatim, chunked for recall |
31
+
32
+ ### 2. Recall before writing (dedup)
33
+
34
+ ```
35
+ recall({ "query": "<the learning's key terms>" })
36
+ ```
37
+
38
+ If it's already there: skip (nothing new), or write only the delta
39
+ ("update: also fails on Windows"), or bump the procedure's accuracy by
40
+ re-putting it.
41
+
42
+ ### 3. Write
43
+
44
+ ```
45
+ write_memory({ "content": "Decided to gate npm publish on the scan gate: a package is the most-attacked surface (lesson: OpenClaw). Context: RFC-0021." })
46
+ ```
47
+
48
+ ```
49
+ procedure_put({ "name": "re-tag-release", "trigger": "publish retry",
50
+ "steps": ["gh release delete vX --yes", "git tag -d vX",
51
+ "git push origin :refs/tags/vX", "git tag vX", "git push origin vX"] })
52
+ ```
53
+
54
+ For stance changes, check the belief state first:
55
+
56
+ ```
57
+ belief_get({ "subject": "engram-index auto-triggers" })
58
+ ```
59
+
60
+ If a belief contradicts the new learning, let the contradiction stand —
61
+ `contradiction_list` will surface the tension later. Never silently
62
+ overwrite a belief with history behind it.
63
+
64
+ For source material (RFCs, ADRs, design docs) the project should recall:
65
+
66
+ ```
67
+ store_knowledge({ "entities": [], "facts": [], "relationships": [], "idempotency_key": "<doc-id>" })
68
+ ```
69
+
70
+ Bridge concepts to code where you can — a concept not linked to what
71
+ realizes it is an orphan. Use `search({ "query": "<term>" })` to find
72
+ real symbol names before linking.
73
+
74
+ ### 4. Confirm
75
+
76
+ One read-back per critical write:
77
+
78
+ ```
79
+ recall({ "query": "<the decision's core terms>" })
80
+ ```
81
+
82
+ ## When it fails
83
+
84
+ - `write_memory` errors → report; never retry in a loop.
85
+ - Nothing worth learning → say "nothing durable here" and stop. Silence
86
+ is a valid outcome; forced learnings are noise.
87
+
88
+ ## Anti-patterns
89
+
90
+ - Session-transcript dumps ("we ran tests, then edited X, then…").
91
+ - Duplicating what `recall` already returns.
92
+ - Unvalidated procedures (steps never executed).
93
+ - Belief overwrites that erase history.
94
+
95
+ ## Final check
96
+
97
+ - Would a future agent in a fresh session act differently because of these writes?
98
+ - Every decision has its why?
99
+ - Procedures were actually run?
@@ -0,0 +1,104 @@
1
+ ---
2
+ name: engram-plan
3
+ description: Plan a change by mining the engram index first — past issues, patterns, invariants, blast radius — using the right workflow for the job. Triage (classify + route), Bugfix (root cause + regression guard), or Story/Feature (precedents + per-layer steps). Trigger when asked to solve/plan/triage/implement anything non-trivial, before editing.
4
+ ---
5
+
6
+ # engram-plan
7
+
8
+ Plan from evidence, not vibes. The index already knows this repo's
9
+ structure, invariants, history, and past failures — mine it before
10
+ writing a line of the plan.
11
+
12
+ **Pick the workflow first** — they are different disciplines:
13
+
14
+ | The request smells like… | Workflow | Reference |
15
+ |---|---|---|
16
+ | "this is broken", unclear severity, red CI | **Triage** — classify + route, don't fix | `references/plan-triage.md` |
17
+ | Reproduced failure, regression, crash | **Bugfix** — root cause + regression guard | `references/plan-bugfix.md` |
18
+ | New capability, story, integration | **Story/Feature** — precedents + per-layer steps | `references/plan-story.md` |
19
+
20
+ All three share the moves below; the references carry each one's
21
+ specific discipline.
22
+
23
+ ## Contract
24
+
25
+ 1. Mine before writing: past work, past failures, invariants, blast radius, tensions.
26
+ 2. **Every plan starts with a past-pattern search** — a fix/feature that ignores how this repo solved it before is planning amnesia.
27
+ 3. Findings are evidence-labeled; risks are quantified from the graph.
28
+ 4. Every step is independently verifiable — it names the command that proves it.
29
+ 5. The plan is written to memory so `engram-implement` can recall it; recurring shapes become procedures.
30
+
31
+ ## Workflow (shared moves)
32
+
33
+ ### 1. Frame the change
34
+
35
+ One paragraph: what changes, for whom, what "done" means. Ambiguity →
36
+ list your interpretation in Open Questions; don't silently pick.
37
+
38
+ ### 2. Search the past (engram-search discipline)
39
+
40
+ ```
41
+ recall({ "query": "<domain terms> fix design decisions" })
42
+ search({ "query": "<likely touchpoint symbols>" })
43
+ procedure_list({})
44
+ contradiction_list({})
45
+ ```
46
+
47
+ Mine for: past fixes with the same symptom · precedents for the same
48
+ feature shape · indexed invariants the change must respect · existing
49
+ runbooks (if one covers this, following it beats planning) · open
50
+ tensions. **Record the search result either way** — "no past
51
+ occurrences" is a finding.
52
+
53
+ ### 3. Map the surface
54
+
55
+ ```
56
+ architecture({ "limit": 15 })
57
+ symbol_context({ "symbol": "<touchpoint>", "depth": 2 })
58
+ change_impact({ "target": "<touchpoint>" })
59
+ ```
60
+
61
+ Blast radius per touchpoint → Risks. Crossed layers → explicit
62
+ per-layer steps.
63
+
64
+ ### 4. Write the plan (fixed sections)
65
+
66
+ **Overview** (the repo's vocabulary) · **Findings** (labeled, including
67
+ the past-pattern search result) · **Risks** (blast radius + invariants
68
+ threatened + mitigations) · **Steps** (ordered, each with its verify
69
+ command) · **Open Questions** (what the index could NOT answer).
70
+
71
+ ### 5. Persist plan + workflow
72
+
73
+ ```
74
+ write_memory({ "content": "PLAN <slug>: <overview>. Precedents: <found|none>. Steps: <N>. Top risks: <top risks>." })
75
+ ```
76
+
77
+ When this shape recurs, capture the workflow that worked:
78
+
79
+ ```
80
+ procedure_put({ "name": "plan-<workflow-type>", "trigger": "<when this shape appears>", "steps": ["<the moves that worked, in order>"] })
81
+ ```
82
+
83
+ ## When it fails
84
+
85
+ - No index (recall/search empty) → plan against `scan_repo` + reads,
86
+ findings marked `[guessed]` where the graph would have proven them.
87
+ Suggest engram-index.
88
+ - A recalled past fix contradicts the request's assumptions → surface
89
+ it before planning; the past fix is evidence, not noise.
90
+
91
+ ## Anti-patterns
92
+
93
+ - Skipping the past-pattern search (the #1 planning failure).
94
+ - Triage that fixes, bugfix plans without a regression test, story
95
+ plans without a precedent search.
96
+ - Steps with no verification command.
97
+ - Risks without graph evidence ("might be tricky" is not a risk).
98
+ - Planning past an open contradiction without flagging it.
99
+
100
+ ## Final check
101
+
102
+ - Right workflow for the request?
103
+ - Did the past-pattern search run, and is its result in Findings?
104
+ - Could a fresh agent implement from Findings + Steps alone?
@@ -0,0 +1,66 @@
1
+ # Plan workflow: BUGFIX
2
+
3
+ Root cause first, minimal fix second, regression guard always.
4
+
5
+ ## When this workflow
6
+ - Reproduced failure, cause unknown or partially known
7
+ - Regression (something that used to work)
8
+ - Post-triage routing (fast lane if a past pattern was recalled)
9
+
10
+ ## Steps
11
+
12
+ ### 1. Search the past — every bugfix starts here
13
+ ```
14
+ recall({ "query": "<symptom terms> fix root cause" })
15
+ search({ "query": "<failing symbol}" })
16
+ procedure_list({})
17
+ ```
18
+ - A past fix for the same symptom = the pattern to check first
19
+ (was it fully fixed, or did the same class resurface elsewhere?)
20
+ - An indexed sharp edge near the failure = prime suspect
21
+ - **Record the search**: "no past occurrences found" is itself a
22
+ finding ([proven] by absence, worth saying)
23
+
24
+ ### 2. Localize with the graph
25
+ ```
26
+ symbol_context({ "symbol": "<failing symbol>", "depth": 2 })
27
+ change_impact({ "target": "<suspect symbol>" })
28
+ ```
29
+ - The failing symbol's neighborhood = the suspect pool
30
+ - `fetch_content` the load-bearing file(s) — never theorize about code
31
+ you haven't read this session
32
+ - If recently-changed code is in the neighborhood:
33
+ `whats_changed {}` to see what moved lately
34
+
35
+ ### 3. Root cause (the plan's Findings section)
36
+ State it as a testable claim: "X fails because Y, when Z."
37
+ Label it. `[proven]` requires either a repro trace or source evidence.
38
+ A root cause you can't state in one sentence isn't found yet.
39
+
40
+ ### 4. Minimal fix + regression guard (Steps section)
41
+ - Smallest change that removes the cause (not the symptom)
42
+ - A test that fails before the fix and passes after — the regression
43
+ guard is mandatory, not optional
44
+ - Blast radius from step 2 becomes the Risks section
45
+
46
+ ### 5. Persist the pattern (procedures for recurring classes)
47
+ If this is the second+ occurrence of a failure class:
48
+
49
+ ```
50
+ procedure_put({ "name": "fix-<failure-class>",
51
+ "trigger": "<symptom signature>",
52
+ "steps": ["<localization step>", "<root-cause check>",
53
+ "<the fix>", "<the regression test>"] })
54
+ ```
55
+ Next triage of this class should hit the runbook, not rediscover it.
56
+
57
+ ## Output (hand to engram-implement)
58
+ - **Findings**: symptom, root cause [labeled], past-occurrence search result
59
+ - **Risks**: blast radius, what the regression test must cover
60
+ - **Steps**: fix + test + verify command (exact)
61
+
62
+ ## Stop conditions
63
+ - Root cause unprovable after localization → plan the investigation
64
+ (instrument, log, bisect) — don't plan a fix on a guess.
65
+ - Fix would touch a bridge symbol → plan-wide test pass is a step, not
66
+ an afterthought.
@@ -0,0 +1,84 @@
1
+ # Plan workflow: STORY / FEATURE
2
+
3
+ New capability work. The mine-first discipline matters most here:
4
+ stories die from unknown unknowns, and the index is where the unknowns
5
+ are already written down.
6
+
7
+ ## When this workflow
8
+ - New feature, story, or capability request
9
+ - Refactor with a goal (not a bug, not a rename)
10
+ - Integration of a new component
11
+
12
+ ## Steps
13
+
14
+ ### 1. Search the past — patterns, precedents, near-misses
15
+ ```
16
+ recall({ "query": "<feature domain terms> design decisions" })
17
+ search({ "query": "<adjacent existing capability>" })
18
+ procedure_list({})
19
+ ```
20
+ Mine for:
21
+ - **Precedents**: was a similar feature planned/built/abandoned
22
+ before? (abandoned plans + their reasons are gold)
23
+ - **Invariants** the feature must respect (indexed `[proven]` rules)
24
+ - **Adjacent patterns**: how does this repo solve analogous problems?
25
+ (find the closest existing feature and mirror its shape)
26
+ - **Open tensions**: `contradiction_list({})` — building on top of an
27
+ unresolved contradiction is planning to fail
28
+
29
+ ### 2. Map the integration surface
30
+ ```
31
+ architecture({ "limit": 15 })
32
+ symbol_context({ "symbol": "<primary touchpoint>", "depth": 2 })
33
+ change_impact({ "target": "<each touchpoint>" })
34
+ ```
35
+ - Where does the feature ATTACH? (ports, facades, tool registries)
36
+ - What must NOT move? (bridges, invariants)
37
+ - Which layers does it cross? (crossing layers = the plan needs
38
+ explicit steps per layer, or it will stop at the first boundary)
39
+
40
+ ### 3. Design in the repo's shape
41
+ One paragraph: the feature in this repo's own vocabulary, mirroring
42
+ the closest existing pattern found in step 1. A design that invents a
43
+ new shape when a proven one exists needs a stated reason (that's an
44
+ Open Question, not a surprise).
45
+
46
+ ### 4. Steps with per-layer verification
47
+ Each step lands ONE layer and names its verify command:
48
+ ```
49
+ 1. Domain types + contracts (core/<crate>)
50
+ Verify: cargo check -p engram-<crate> + check-contracts.sh
51
+ 2. Adapter behavior (adapters/<area>)
52
+ Verify: cargo test -p engram-<adapter>
53
+ 3. Facade/registry wiring
54
+ Verify: <the exact test that proves reachability>
55
+ 4. Agent surface (tool/skill/README)
56
+ Verify: <driver call or surface-parity check>
57
+ ```
58
+ Steps without a verify command are wishes, not steps.
59
+
60
+ ### 5. Persist the plan AND the workflow
61
+ ```
62
+ write_memory({ "content": "PLAN <slug>: <overview>. Precedents mined:
63
+ <what step 1 found>. Top risks: <...>. Steps: <N>, per-layer verify." })
64
+ ```
65
+ If this feature type recurs, the successful shape becomes a procedure:
66
+
67
+ ```
68
+ procedure_put({ "name": "add-<feature-type>",
69
+ "trigger": "new <feature-type> request",
70
+ "steps": ["<mine precedents>", "<map surface>", "<per-layer steps>",
71
+ "<verify each>", "<learn pass>"] })
72
+ ```
73
+
74
+ ## Output
75
+ Overview / Findings (with the precedent search result — including
76
+ "none found") / Risks (invariants + bridges) / Steps (per-layer) /
77
+ Open Questions.
78
+
79
+ ## Stop conditions
80
+ - Design contradicts an indexed `[proven]` invariant → stop; either
81
+ the invariant is wrong (an ADR-level change — say so) or the design
82
+ is. Don't plan past a contradiction.
83
+ - No precedent found AND high blast radius → the first plan step is a
84
+ spike/prototype, explicitly labeled as such.
@@ -0,0 +1,54 @@
1
+ # Plan workflow: TRIAGE
2
+
3
+ Rapid assessment of a reported problem. Triage does NOT fix — it
4
+ classifies and routes. Time-boxed: if this takes more than a few tool
5
+ calls, it's a bugfix, not a triage.
6
+
7
+ ## When this workflow
8
+ - A bug/error report arrives with unclear severity
9
+ - CI is red and nobody knows why
10
+ - "Something is broken" with no repro
11
+
12
+ ## Steps
13
+
14
+ ### 1. Reproduce (or fail to, honestly)
15
+ Run the failing thing. If you cannot reproduce, that IS the triage
16
+ output: "not reproducible as described; likely <hypothesis [likely]>".
17
+
18
+ ### 2. Search the past (engram-search core move)
19
+ ```
20
+ recall({ "query": "<error text core terms>" })
21
+ search({ "query": "<failing symbol or area>" })
22
+ procedure_list({})
23
+ ```
24
+ - Has this exact failure happened before? (past fixes = fastest path)
25
+ - Is there a known sharp edge here? (indexed `[proven]` memory)
26
+ - Is there a runbook that already covers it?
27
+
28
+ ### 3. Classify
29
+
30
+ | Class | Criteria | Route |
31
+ |---|---|---|
32
+ | Known + runbook exists | recall hit + procedure covers it | Follow the procedure; skip planning |
33
+ | Known pattern, no runbook | similar past fix recalled | plan-bugfix (fast lane — the pattern is known) |
34
+ | New failure mode | no past hits | plan-bugfix full workflow |
35
+ | Not a bug (works as designed) | repro shows intended behavior | Report; maybe docs/engram-learn |
36
+ | Severity: blocks release/CI | red main, broken publish | plan-bugfix immediately + flag urgency |
37
+
38
+ ### 4. Record the triage
39
+ ```
40
+ write_memory({ "content": "TRIAGE <one-line>: <report> → <class>.
41
+ Root-cause hypothesis: <...> [likely]. Past evidence: <recall hit or
42
+ 'none'>" })
43
+ ```
44
+ If a runbook WAS missing but would have helped, note that — it feeds
45
+ engram-learn later.
46
+
47
+ ## Output
48
+ One paragraph: what was reported, what reproduced, the class, the
49
+ route, the hypothesis. No fix, no plan steps — routing only.
50
+
51
+ ## Stop conditions
52
+ - Cannot reproduce → report that, stop.
53
+ - Runbook found → execute it, stop (that's not triage anymore).
54
+ - Classification clear → hand to plan-bugfix, stop.
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: engram-search
3
+ description: Agentic search over the code graph and memory to find or solve problems — "where is X", "how does Y work", "why did Z break", "find the code that...". An iterative hypothesis→retrieve→verify loop, not a one-shot lookup. Trigger on any codebase question where the answer should be evidenced.
4
+ ---
5
+
6
+ # engram-search
7
+
8
+ Answer codebase questions with evidence. A loop: **hypothesis → retrieve
9
+ → verify → refine**. Stop when the claim is `[proven]` — or honestly
10
+ unproven.
11
+
12
+ ## Contract
13
+
14
+ 1. Never claim file contents from memory alone — verify with `fetch_content`.
15
+ 2. Every claim in the answer carries its evidence: the tool + query that proved it.
16
+ 3. Two fruitless iterations → say what you looked for and stop.
17
+ 4. Labels: `[proven]` (verified against source/graph), `[likely]` (strong signal, unverified), `[guessed]` (hypothesis only — say so).
18
+
19
+ ## Workflow
20
+
21
+ ### 1. State the hypothesis
22
+
23
+ Before any tool call, write one line: *"I expect X lives in Y because Z."*
24
+ This anchors the search and makes refinement measurable.
25
+
26
+ ### 2. Retrieve from two angles
27
+
28
+ ```
29
+ recall({ "query": "<the question's key terms>" })
30
+ search({ "query": "<the likely symbol/term name>" })
31
+ ```
32
+
33
+ `recall` covers memories + knowledge + docs (the "why"); `search` covers
34
+ the code graph (the "where").
35
+
36
+ ### 3. Drill the neighborhood
37
+
38
+ For the best candidate symbol:
39
+
40
+ ```
41
+ symbol_context({ "symbol": "<name>", "depth": 2 })
42
+ ```
43
+
44
+ For an area rather than a symbol:
45
+
46
+ ```
47
+ explore({ "query": "<area terms>", "depth": 2 })
48
+ ```
49
+
50
+ ### 4. Verify against source
51
+
52
+ Before asserting what code does:
53
+
54
+ ```
55
+ fetch_content({ "path": "<file path from the graph>" })
56
+ ```
57
+
58
+ Graph and memory say where; the file says what. If they disagree, the
59
+ index is stale — say so (`[likely]` at best).
60
+
61
+ ### 5. Refine or stop
62
+
63
+ - Found and verified → answer.
64
+ - Found but unverified → answer with `[likely]`, offer to fetch.
65
+ - Nothing → refine the query with terms the graph revealed (community
66
+ names, related symbols), one more iteration. After two empty
67
+ iterations, report the queries tried and stop.
68
+
69
+ ## Output format
70
+
71
+ ```
72
+ <answer, one paragraph>
73
+
74
+ Evidence:
75
+ - [proven] <claim> — symbol_context(X): called by A, B; fetch_content(file.rs)
76
+ - [likely] <claim> — recall hit "…" (indexed Oct 2026; may be stale)
77
+ - [guessed] <claim> — naming convention only
78
+ ```
79
+
80
+ ## When it fails
81
+
82
+ - Empty store (no index yet) → say "not indexed; run engram-index or
83
+ scan_repo first" and stop. Do not fall back to grepping as if indexed.
84
+ - Stale-index signals (symbols that no longer exist per `fetch_content`) →
85
+ flag the staleness in the answer; suggest `scan_repo`.
86
+ - Ambiguous symbol (many same-name entities) → disambiguate with
87
+ `symbol_context` per candidate, or ask; don't average.
88
+
89
+ ## Anti-patterns
90
+
91
+ - Claiming behavior from memory alone (no `fetch_content`).
92
+ - One query, one give-up.
93
+ - Answering from general language knowledge instead of this repo's graph.
94
+ - Skipping the hypothesis line.
95
+
96
+ ## Final check
97
+
98
+ - Is every claim labeled?
99
+ - Did I read the actual file for the load-bearing claims?
100
+ - Would the evidence chain convince a skeptical reviewer?