@engramlabs/mcp 0.1.2-alpha → 0.1.4-alpha

package/skills/engram-implement/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: engram-implement
+description: Execute a plan step-by-step with a self-review loop — implement, verify with the plan's own commands, review the diff against the plan's risks, then learn from the outcome. Trigger when a plan exists (from engram-plan or given directly) and it's time to execute.
+---
+
+# engram-implement
+
+Implement with discipline: **implement → verify → self-review**, per step.
+Red tests are information, not failure. Flailing is forbidden.
+
+## Contract
+
+1. Work the plan's steps in order; verify each with its own command.
+2. Self-review every diff against the plan's Findings and Risks.
+3. Two consecutive failed verifications on one step → stop and report.
+4. The session ends with a learn pass (`engram-learn` core ideas).
+
+## Workflow
+
+### 0. Recall the plan
+
+If the plan isn't in-context:
+
+```
+recall({ "query": "PLAN <slug>" })
+```
+
+No plan anywhere? Either draft one (engram-plan, even briefly) or state
+plainly that this is plan-less execution and accept the label.
+
+### 1. Per step: implement
+
+Make the change. Small diffs. Prefer the smallest edit that satisfies the
+step — style sweeps and drive-by refactors belong in their own step
+(usually: don't).
+
+### 2. Per step: verify
+
+Run the step's verification command exactly as written in the plan. If
+the plan's command was wrong, fix the plan's command (and note it —
+that's a learning).
+
+- **Green** → self-review (step 3).
+- **Red** → read the failure; fix; re-verify. The red IS the signal.
+
+### 3. Per step: self-review
+
+Before moving on, review your diff against the plan:
+
+- Does the diff do what the step said — nothing more?
+- Did it touch any Risk-listed symbol/area? If yes, is the mitigation applied?
+- Did it break an invariant the plan's Findings flagged?
+- New behavior covered by a test (or is one honestly not warranted)?
+
+Any "no" → fix before proceeding. Skipping self-review to "come back
+later" is how bridges get broken silently.
+
+### 4. Stop conditions
+
+- All steps verified + self-reviewed → completion report → step 5.
+- Two consecutive failed verifications on the SAME step → STOP. Report:
+  the step, what you tried (both attempts), the error, your read on the
+  blocker. Do not attempt three.
+- Plan invalidated mid-flight (a finding proves wrong) → stop, report the
+  contradiction, propose the plan amendment. Don't improvise a new plan
+  silently.
+
+### 5. Completion + learn pass
+
+Report: steps done, verification results, diff summary, plan amendments
+made, risks re-checked. Then a quick learn pass — the durable bits only:
+
+```
+write_memory({ "content": "Fixed <X>: root cause was <Y>. Plan step-N command was wrong: <what worked instead>." })
+procedure_put({ "name": "<validated workflow, if one emerged>",
+  "trigger": "<when>", "steps": ["..."] })
+```
+
+## When it fails
+
+- Verify command can't run (missing tool/deps) → report immediately; do
+  not substitute a weaker check silently.
+- Scope creep detected mid-step → finish or revert the current step, then
+  raise the scope change explicitly.
+
+## Anti-patterns
+
+- Implementing multiple steps before verifying any.
+- "I'll add tests at the end."
+- Third attempt after two failures (stop means stop).
+- Editing the plan to match the code after the fact without saying so.
+
+## Final check
+
+- Every step verified green, every diff self-reviewed?
+- Risks from the plan re-checked against the final diff?
+- Did the learn pass capture the root causes, not the play-by-play?

package/skills/engram-index/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: engram-index
+description: Index a codebase AND memorize what matters about it — build the code graph, then write durable, evidence-labeled memories (stack, invariants, sharp edges, build/test procedures). Trigger on "index this repo", first session in a repository, or when the engram stale-index reminder fires.
+---
+
+# engram-index
+
+Index the code graph, then **memorize the codebase** — the graph alone is
+structure; memory is understanding. Evidence-first, always.
+
+Depth on demand: `references/rea-process.md` (the full evidence-first
+process) · `references/memorization-catalog.md` (exact write formats).
+
+## Contract
+
+1. Structure comes from `scan_repo` — never from reading files by hand first.
+2. Every memorized claim carries an evidence label: `[proven]`, `[likely]`, or `[guessed]`.
+3. Every memory written is read back — **an index that cannot be recalled is not an index.**
+4. No claim without a tool call behind it. If you cannot prove it, label it `[guessed]` or omit it.
+5. Recurring workflows become procedures — an index without runbooks is only half an index.
+
+## Workflow
+
+### 0. Scope (skip if fresh)
+
+Check staleness first. If the repo is already indexed and little changed,
+skip to phase 2 (delta-memorize) — don't rescan for nothing.
+
+```
+recall({ "query": "repo overview build test invariants" })
+```
+
+If recalled memories describe this repo adequately, go to phase 2.
+Otherwise continue.
+
+### 1. Surface map
+
+```
+scan_repo({ "path": "/absolute/path/to/repo" })
+architecture({ "limit": 20 })
+graph_health({})
+```
+
+Read the architecture output: central symbols (core abstractions), bridges
+(critical paths), communities (modules). This is the structural truth —
+do NOT open files to "get a feel".
+
+### 2. Memorize
+
+Write memories — one concern per memory, title first. Exact formats:
+`references/memorization-catalog.md`. In short:
+
+```
+write_memory({ "content": "[proven] <claim> — evidence: <tool + what it showed>" })
+```
+
+Memorize, in order of value:
+- **Stack + layout** — languages, framework, key directories (`[proven]` from the graph's file entities)
+- **Invariants** — naming rules, boundary rules, layering (e.g. "domain crates must not depend on adapters — check-contracts.sh enforces") (`[likely]` if from names alone, `[proven]` if a check/script enforces it)
+- **Sharp edges** — bridge symbols ("change_impact shows X is a bridge; touching it ripples into N areas"), god modules, known-tricky paths (`[proven]` via `change_impact`)
+- **Core abstractions** — the top 3-5 central symbols, one line each on their role
+
+Memorize procedures — the commands that build/test/verify, AND the
+recurring workflows this repo actually performs (indexing, triage,
+release, dogfood — whatever the repo's rhythm is):
+
+```
+procedure_put({ "name": "verify", "trigger": "before handoff", "steps": ["<exact command>"] })
+```
+
+Only procedures you have seen work (from READMEs, CI configs, or this
+session). Label untested steps in the trigger field ("untested").
+Check what already exists first — `procedure_list({})` — and re-put to
+update, don't duplicate.
+
+Optionally, entities + relationships for the top abstractions:
+
+```
+put_entity({ "name": "Scanner", "kind": "class" })
+put_relationship({ "subject": "Scanner", "predicate": "describes", "object": "ingest pipeline" })
+```
+
+### 3. Verify (write → read-back)
+
+Probe with three recall queries a future agent would actually ask:
+
+```
+recall({ "query": "build command" })
+recall({ "query": "<top central symbol name>" })
+recall({ "query": "<one invariant you wrote>" })
+```
+
+If a probe returns nothing (or garbage), the memory was written badly —
+rewrite it with more distinctive wording, then re-probe. Do not skip this.
+
+### 4. Report
+
+Concise, no file dumps: N symbols, M modules, core abstractions (top
+PageRank), bridges to respect, what was memorized, confidence split
+(proven/likely/guessed counts), unknowns worth investigating later.
+
+## When it fails
+
+- `scan_repo` errors → report the error; do not fall back to reading files
+  as a "quick index" — that produces structure-free memory.
+- Empty architecture → repo may be empty/non-code; say so, stop.
+- Read-back probes fail after one rewrite → report which memories didn't
+  stick; do not silently continue.
+
+## Anti-patterns
+
+- Reading source files to summarize the repo before scanning (the graph is the map).
+- Writing unlabelled claims ("the auth is in middleware" — proven? guessed?).
+- Memorizing trivia (file counts, boilerplate names).
+- One giant memory blob instead of one-concern-per-memory.
+
+## Final check
+
+- What am I missing in the overview?
+- Is every claim labeled and evidenced?
+- Would these memories survive a refactor of the code they describe?
+- Did all three probes come back?

package/skills/engram-index/references/memorization-catalog.md

@@ -0,0 +1,81 @@
+# Memorization catalog — what engram-index writes, exactly
+
+The reference for phase 2 (memorize) of engram-index. One concern per
+memory; every claim labeled; every procedure seen working.
+
+## Memory formats (write_memory)
+
+### Stack + layout
+```
+write_memory({ "content": "[proven] Rust workspace, 30+ crates; core/
+  adapters/backends split enforced by scripts/ci/check-engine-neutrality.sh
+  — evidence: architecture tool showed core crates; CI script read via
+  fetch_content" })
+```
+
+### Invariants (the rules this repo lives by)
+```
+write_memory({ "content": "[proven] engram-domain must not depend on SQL,
+  vector stores, or async runtimes — evidence: check-engine-neutrality.sh
+  gates CI; violation names engine types in core crates" })
+```
+Label `[likely]` when inferred from structure alone ("naming suggests
+layering" is not proof); upgrade to `[proven]` only when a check, test,
+or doc enforces it.
+
+### Sharp edges (what bites)
+```
+write_memory({ "content": "[proven] bridge symbol: resolve_symbol in
+  core/code — 14 dependents across 5 crates; change_impact shows ripple
+  into scanner, mcp tools, and tests. Touch last, test wide." })
+```
+Sources of sharp edges: `architecture` bridge list, `change_impact`
+output on symbols you expect to touch, temporal traps from
+`whats_changed`.
+
+### Core abstractions (the "understand this = understand the system" set)
+```
+write_memory({ "content": "[proven] MemoryService trait is the central
+  abstraction (top PageRank) — every write path flows through it;
+  adapters implement, orchestration composes. evidence: architecture
+  tool, symbol_context depth 2" })
+```
+
+## Procedure formats (procedure_put)
+
+Only procedures whose steps were SEEN working (CI configs, READMEs,
+this session). Untested steps must say so in `trigger`.
+
+```
+procedure_put({ "name": "verify",
+  "trigger": "before handoff",
+  "steps": ["cargo fmt --all", "cargo check --workspace",
+            "pnpm run typecheck", "pnpm run test",
+            "scripts/ci/check-contracts.sh"] })
+
+procedure_put({ "name": "scan-repo",
+  "trigger": "index refresh",
+  "steps": ["scan_repo {path: <repo>}", "architecture {limit: 20}",
+            "graph_health {}"] })
+```
+
+## Entity/relationship formats (put_entity / put_relationship)
+
+Top abstractions only — the graph already knows every symbol; entities
+are for the CONCEPTS the graph can't infer:
+
+```
+put_entity({ "name": "Engine Neutrality", "kind": "concept" })
+put_relationship({ "subject": "Engine Neutrality", "predicate":
+  "realized_by", "object": "check-engine-neutrality" })
+```
+
+Bridge concepts to the code that realizes them; a concept linked to
+nothing is an orphan in a disconnected subgraph.
+
+## What NOT to memorize
+
+- File counts, line counts, dependency version trivia
+- Boilerplate names, test fixture names
+- Anything `architecture`/`symbol_context` answers on demand
+- Session play-by-play (that's engram-learn's job, and only the durable parts)

package/skills/engram-index/references/rea-process.md

@@ -0,0 +1,79 @@
+# REA process for code indexing
+
+The evidence-first discipline (adapted from the REA — Reverse Engineer
+Anything — method) applied to understanding and memorizing a codebase.
+
+## The process, stage by stage
+
+### 1. Target scoping
+Define what is being understood before touching anything:
+- What kind of system is this? (service, library, app, agent tool)
+- What will "understood" mean here? (can answer where/how questions,
+  can plan changes safely, can recall invariants)
+- What is already known? (check staleness — if a fresh index exists,
+  only delta-memorize)
+
+**Stop condition:** scope stated in one sentence before any tool call.
+
+### 2. Surface mapping
+Map the terrain without reading files:
+- `scan_repo` — the structural pass (symbols, edges, communities)
+- `architecture {limit: 20}` — central symbols, bridges, stats
+- `graph_health` — is the graph trustworthy?
+
+Surface mapping answers: how big, how coupled, where does complexity
+live? It does NOT answer how anything works — that's tracing.
+
+### 3. Feature tracing
+Follow one behavior from trigger to outcome through the graph:
+- Start from the entry point (top central symbol, or a named feature)
+- `symbol_context` each hop: callers, callees, community
+- `change_impact` on bridges to understand blast radius
+- `fetch_content` the load-bearing files to verify the graph's story
+
+Record every hop: file, symbol, what the edge means. A trace that
+skips a hop is a guess, not a trace.
+
+### 4. Evidence collection
+Every claim gets its evidence AT COLLECTION TIME, not later:
+
+| Label | Meaning | Evidence standard |
+|---|---|---|
+| `[proven]` | Verified against source or graph | tool + query + what it showed |
+| `[likely]` | Strong signal, unverified | naming, structure, docs memory |
+| `[guessed]` | Hypothesis only | must say so explicitly |
+
+Rules:
+- Never claim how something works without graph/source evidence.
+- Separate facts from interpretation — the label IS the separation.
+- Start with the simplest trace that proves the behavior.
+- Pseudocode-level summaries of files you haven't fetched are `[likely]`
+  at best.
+
+### 5. Reconstruction (memorization)
+Turn findings into durable memory — one concern per memory, written so a
+future agent in a fresh session can act on it:
+- Stack + layout invariants
+- Sharp edges (bridges, god modules, temporal traps)
+- Core abstractions (top PageRank, one line each)
+- Build/test/verify procedures (exact commands, only ones seen working)
+
+An unmemorized finding is a finding you'll pay for twice.
+
+### 6. Verification (write → read-back)
+- Recall 3 probe queries a future agent would actually ask.
+- A probe that fails = a memory written badly = rewrite it.
+- **An index that cannot be recalled is not an index.**
+
+### 7. Final report
+- N symbols, M modules, core abstractions, bridges to respect
+- What was memorized + confidence split (proven/likely/guessed counts)
+- Unknowns worth investigating — honesty about holes
+
+## The final check (run before claiming done)
+
+- What am I missing in the overview?
+- Is each claim proven or just plausible?
+- Did I mistake graph structure for verified behavior?
+- Would these memories survive the next refactor?
+- What evidence would change my mind?

package/skills/engram-learn/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: engram-learn
+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.
+---
+
+# engram-learn
+
+Turn what just happened into durable memory. The agent does the extraction
+and judgment; engram stores and recalls. Learners capture **decisions,
+gotchas, and procedures** — not transcripts.
+
+## Contract
+
+1. No trivia: if a future agent wouldn't act on it, don't write it.
+2. No duplicates: recall first; update or skip if it's already known.
+3. Decisions record the *why*, not just the *what*.
+4. Source-grounded facts cite their source (`store_knowledge`, not `write_memory`).
+
+## Workflow
+
+### 1. What kind of learning is this?
+
+| Kind | Tool | Shape |
+|---|---|---|
+| Decision + rationale | `write_memory` | "Decided X over Y because Z" |
+| Gotcha / resolution | `write_memory` | "X bites when Y; fix: Z" |
+| Validated procedure | `procedure_put` | exact steps that worked |
+| Fact from a source | `store_knowledge` | entities/facts with the doc path |
+| Changed stance | `belief_get` → update or let contradiction stand | subject + new position |
+| Replayable doc | `index_docs` | verbatim, chunked for recall |
+
+### 2. Recall before writing (dedup)
+
+```
+recall({ "query": "<the learning's key terms>" })
+```
+
+If it's already there: skip (nothing new), or write only the delta
+("update: also fails on Windows"), or bump the procedure's accuracy by
+re-putting it.
+
+### 3. Write
+
+```
+write_memory({ "content": "Decided to gate npm publish on the scan gate: a package is the most-attacked surface (lesson: OpenClaw). Context: RFC-0021." })
+```
+
+```
+procedure_put({ "name": "re-tag-release", "trigger": "publish retry",
+  "steps": ["gh release delete vX --yes", "git tag -d vX",
+            "git push origin :refs/tags/vX", "git tag vX", "git push origin vX"] })
+```
+
+For stance changes, check the belief state first:
+
+```
+belief_get({ "subject": "engram-index auto-triggers" })
+```
+
+If a belief contradicts the new learning, let the contradiction stand —
+`contradiction_list` will surface the tension later. Never silently
+overwrite a belief with history behind it.
+
+For source material (RFCs, ADRs, design docs) the project should recall:
+
+```
+store_knowledge({ "entities": [], "facts": [], "relationships": [], "idempotency_key": "<doc-id>" })
+```
+
+Bridge concepts to code where you can — a concept not linked to what
+realizes it is an orphan. Use `search({ "query": "<term>" })` to find
+real symbol names before linking.
+
+### 4. Confirm
+
+One read-back per critical write:
+
+```
+recall({ "query": "<the decision's core terms>" })
+```
+
+## When it fails
+
+- `write_memory` errors → report; never retry in a loop.
+- Nothing worth learning → say "nothing durable here" and stop. Silence
+  is a valid outcome; forced learnings are noise.
+
+## Anti-patterns
+
+- Session-transcript dumps ("we ran tests, then edited X, then…").
+- Duplicating what `recall` already returns.
+- Unvalidated procedures (steps never executed).
+- Belief overwrites that erase history.
+
+## Final check
+
+- Would a future agent in a fresh session act differently because of these writes?
+- Every decision has its why?
+- Procedures were actually run?

package/skills/engram-plan/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: engram-plan
+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.
+---
+
+# engram-plan
+
+Plan from evidence, not vibes. The index already knows this repo's
+structure, invariants, history, and past failures — mine it before
+writing a line of the plan.
+
+**Pick the workflow first** — they are different disciplines:
+
+| The request smells like… | Workflow | Reference |
+|---|---|---|
+| "this is broken", unclear severity, red CI | **Triage** — classify + route, don't fix | `references/plan-triage.md` |
+| Reproduced failure, regression, crash | **Bugfix** — root cause + regression guard | `references/plan-bugfix.md` |
+| New capability, story, integration | **Story/Feature** — precedents + per-layer steps | `references/plan-story.md` |
+
+All three share the moves below; the references carry each one's
+specific discipline.
+
+## Contract
+
+1. Mine before writing: past work, past failures, invariants, blast radius, tensions.
+2. **Every plan starts with a past-pattern search** — a fix/feature that ignores how this repo solved it before is planning amnesia.
+3. Findings are evidence-labeled; risks are quantified from the graph.
+4. Every step is independently verifiable — it names the command that proves it.
+5. The plan is written to memory so `engram-implement` can recall it; recurring shapes become procedures.
+
+## Workflow (shared moves)
+
+### 1. Frame the change
+
+One paragraph: what changes, for whom, what "done" means. Ambiguity →
+list your interpretation in Open Questions; don't silently pick.
+
+### 2. Search the past (engram-search discipline)
+
+```
+recall({ "query": "<domain terms> fix design decisions" })
+search({ "query": "<likely touchpoint symbols>" })
+procedure_list({})
+contradiction_list({})
+```
+
+Mine for: past fixes with the same symptom · precedents for the same
+feature shape · indexed invariants the change must respect · existing
+runbooks (if one covers this, following it beats planning) · open
+tensions. **Record the search result either way** — "no past
+occurrences" is a finding.
+
+### 3. Map the surface
+
+```
+architecture({ "limit": 15 })
+symbol_context({ "symbol": "<touchpoint>", "depth": 2 })
+change_impact({ "target": "<touchpoint>" })
+```
+
+Blast radius per touchpoint → Risks. Crossed layers → explicit
+per-layer steps.
+
+### 4. Write the plan (fixed sections)
+
+**Overview** (the repo's vocabulary) · **Findings** (labeled, including
+the past-pattern search result) · **Risks** (blast radius + invariants
+threatened + mitigations) · **Steps** (ordered, each with its verify
+command) · **Open Questions** (what the index could NOT answer).
+
+### 5. Persist plan + workflow
+
+```
+write_memory({ "content": "PLAN <slug>: <overview>. Precedents: <found|none>. Steps: <N>. Top risks: <top risks>." })
+```
+
+When this shape recurs, capture the workflow that worked:
+
+```
+procedure_put({ "name": "plan-<workflow-type>", "trigger": "<when this shape appears>", "steps": ["<the moves that worked, in order>"] })
+```
+
+## When it fails
+
+- No index (recall/search empty) → plan against `scan_repo` + reads,
+  findings marked `[guessed]` where the graph would have proven them.
+  Suggest engram-index.
+- A recalled past fix contradicts the request's assumptions → surface
+  it before planning; the past fix is evidence, not noise.
+
+## Anti-patterns
+
+- Skipping the past-pattern search (the #1 planning failure).
+- Triage that fixes, bugfix plans without a regression test, story
+  plans without a precedent search.
+- Steps with no verification command.
+- Risks without graph evidence ("might be tricky" is not a risk).
+- Planning past an open contradiction without flagging it.
+
+## Final check
+
+- Right workflow for the request?
+- Did the past-pattern search run, and is its result in Findings?
+- Could a fresh agent implement from Findings + Steps alone?

package/skills/engram-plan/references/plan-bugfix.md

@@ -0,0 +1,66 @@
+# Plan workflow: BUGFIX
+
+Root cause first, minimal fix second, regression guard always.
+
+## When this workflow
+- Reproduced failure, cause unknown or partially known
+- Regression (something that used to work)
+- Post-triage routing (fast lane if a past pattern was recalled)
+
+## Steps
+
+### 1. Search the past — every bugfix starts here
+```
+recall({ "query": "<symptom terms> fix root cause" })
+search({ "query": "<failing symbol}" })
+procedure_list({})
+```
+- A past fix for the same symptom = the pattern to check first
+  (was it fully fixed, or did the same class resurface elsewhere?)
+- An indexed sharp edge near the failure = prime suspect
+- **Record the search**: "no past occurrences found" is itself a
+  finding ([proven] by absence, worth saying)
+
+### 2. Localize with the graph
+```
+symbol_context({ "symbol": "<failing symbol>", "depth": 2 })
+change_impact({ "target": "<suspect symbol>" })
+```
+- The failing symbol's neighborhood = the suspect pool
+- `fetch_content` the load-bearing file(s) — never theorize about code
+  you haven't read this session
+- If recently-changed code is in the neighborhood:
+  `whats_changed {}` to see what moved lately
+
+### 3. Root cause (the plan's Findings section)
+State it as a testable claim: "X fails because Y, when Z."
+Label it. `[proven]` requires either a repro trace or source evidence.
+A root cause you can't state in one sentence isn't found yet.
+
+### 4. Minimal fix + regression guard (Steps section)
+- Smallest change that removes the cause (not the symptom)
+- A test that fails before the fix and passes after — the regression
+  guard is mandatory, not optional
+- Blast radius from step 2 becomes the Risks section
+
+### 5. Persist the pattern (procedures for recurring classes)
+If this is the second+ occurrence of a failure class:
+
+```
+procedure_put({ "name": "fix-<failure-class>",
+  "trigger": "<symptom signature>",
+  "steps": ["<localization step>", "<root-cause check>",
+            "<the fix>", "<the regression test>"] })
+```
+Next triage of this class should hit the runbook, not rediscover it.
+
+## Output (hand to engram-implement)
+- **Findings**: symptom, root cause [labeled], past-occurrence search result
+- **Risks**: blast radius, what the regression test must cover
+- **Steps**: fix + test + verify command (exact)
+
+## Stop conditions
+- Root cause unprovable after localization → plan the investigation
+  (instrument, log, bisect) — don't plan a fix on a guess.
+- Fix would touch a bridge symbol → plan-wide test pass is a step, not
+  an afterthought.