Cognitive Schemas

A cognitive schema is a high-level mental model that organizes many lower-level memories under one idea — and tells you when to apply it. Engrams gives your agent the same machinery: a confirmed schema bundles related decisions, patterns, and code under a single summary that states when it fires and what to do, so the agent loads the model instead of re-reading the history.

How human schemas organize memory

Cognitive psychology describes memory as layered. At the bottom sit individual episodes and facts; at the top sit schemas — abstract frames like code review or restaurant visit that group those episodes together. A schema does two things:

1. It organizes. Specific memories become instances of the schema. You do not store restaurant visit #47 from scratch; you store what was different from the frame, and the frame supplies the rest.
2. It activates conditionally. A schema carries an activation trigger — cues in the environment (a menu, a pull request diff) — plus procedural rules for what to do once it fires. Recall is top-down: the cue selects the schema, and the schema selects which lower-level memories matter.

This is why humans never search their memory linearly. The right frame arriving early is what makes behavior fast and consistent — and it is exactly what an LLM agent lacks when it greps a repository cold.

How schemas guide LLM retrieval in Engrams

An Engrams schema is a confirmed graph node whose members are lower-level memories — decisions, system patterns, code nodes, progress entries, custom data, even nested schemas. The schema's summary is written as a conditional sentence:

Fires when <trigger condition>: <operational rule>

Every retrieval surface reads that sentence differently:

The trigger is what makes this work for an LLM: matching a short conditional sentence against the current prompt or edited paths is cheap, while the rule is a directive the model can comply with immediately — no file reads required. Full-text search (schemas_fts) indexes the whole summary, so triggers and rules are findable from any query surface.

Designing a schema that guides an agent

A schema is only as good as its summary. Engrams enforces the shape — schema refine accepts a structured pair and rejects free-text summaries that lack a conditional trigger:

# Structured authoring (recommended) — formats the summary for you
engrams schema refine <target> --trigger "editing public documentation" \
                              --rule "use problem-first risk messaging"
# => summary: "Fires when editing public documentation: use problem-first risk messaging."

# Manual summaries must begin with a conditional trigger phrase
engrams schema refine <target> --summary "Fires when ...: ..."
# Accepted openers: "Fires when", "When", "Applies if", "Activates when"

Authoring principles

• Write the trigger as observable context. A file path, a file kind, a task verb — something present in the prompt or the paths being edited. “When working on things” never matches; “Fires when editing files under src/ops/” always does.
• Write the rule as an imperative. The agent must be able to comply without more reading. “Error handling matters here” is a description; “return the AppError envelope and never unwrap in library code” is a rule.
• Anchor members where the rule applies. advise and prime match through member anchors and centroid tags — an unanchored schema never activates on a path.
• Members first, summary second. Let schema scan cluster related nodes, confirm the cluster, then refine the summary. The schema should summarize memory that exists, not invent memory you wish you had.
• One schema per recurring situation. If two triggers always fire together, they are one schema; if one trigger demands two unrelated rules, it is two schemas.

Example: software architecture

A cluster of error-handling decisions, a result-envelope pattern, and the central error type become one schema that fires on any fallible-function work:

engrams schema refine error-envelope \
  --trigger "adding or editing a fallible public function in Rust code" \
  --rule "return the AppError envelope and never unwrap outside tests"

Running engrams schema show error-envelope returns the schema plus its enriched members:

{
  "status": "success",
  "schema": {
    "id": 4,
    "name": "error-envelope",
    "summary": "Fires when adding or editing a fallible public function in Rust code: return the AppError envelope and never unwrap outside tests.",
    "summary_source": "agent",
    "status": "confirmed",
    "members": [
      {
        "kind": "system_pattern", "id": 12, "name": "result-envelope",
        "description": "Public fallible functions return Result<T, AppError>.",
        "severity": "error", "anchors": ["src/ops"]
      },
      {
        "kind": "decision", "id": 58,
        "summary": "Ban unwrap in library code; convert with AppError::from",
        "status": "active", "anchors": ["src/ops/schemas/list.rs"]
      },
      {
        "kind": "code", "id": 91, "path": "src/errors.rs",
        "symbol": "AppError", "line_count": 64
      }
    ],
    "member_count": 3,
    "truncated": false
  }
}

From now on, engrams advise src/errors.rs surfaces this schema above the constraint list, and engrams prime --paths src/ops ranks it at the top of the schemas block — the agent reads the rule before it reads the code.

Example: research

Research findings stored as custom data tend to go stale because nothing forces an agent to consult them. A schema turns the survey into a standing rule:

engrams schema refine survey-then-decide \
  --trigger "evaluating a new dependency or settling an open design question" \
  --rule "read the saved research findings first and cite the finding ID in the decision"

Members: the custom-data entries holding the survey findings (each enriched with its key and full value — JSON stored as JSON), plus the decision that turned the survey into a roadmap. Now a prompt like “should we adopt bgk for clustering?” activates the schema through advise — the agent is told to ground the answer in finding IDs instead of improvising from training-data priors.

Example: planning

Planning drift happens when every session re-derives what to build next from a backlog of raw notes. The what-to-build-next schema packages the survey, the roadmap decision, and the session notes into one activation:

engrams schema refine what-to-build-next \
  --trigger "planning a release or choosing what to build next" \
  --rule "pick from the tiered version-by-version roadmap before inventing new scope"

Running engrams prime --tags roadmap ranks this schema first with its rule inline, so planning sessions start from the committed sequence rather than the loudest recent note. Tagging the schema (or its members) with the tags your planning prompts use is what makes the match — anchors for paths, tags for topics.

The loop closes itself

You do not have to remember to look for schemas. Detection runs continuously in the background, and engrams session close tells you two things at the exact moment a session ends:

• schema_opportunities — candidate clusters that passed the formation gates and do not overlap any schema you already confirmed. Each one arrives with a suggested name and a ready-to-run engrams schema confirm command. Run it, or don't: an unchanged candidate is not nagged about again, and one that keeps growing comes back louder.
• schema_value — how many retrievals this session were guided by schemas, and how many distinct schemas did the guiding. This is the payoff made visible: schemas are doing work, here is the count.

The same counter shows up per schema in engrams schema list and schema show as the guided field — so a schema that never fires is visible too, and worth refining or retiring.