memory/ folder: Bloom’s persistent learnings from working on the system. It is deliberately a working set, not an archive — entries are tagged with who provided the feedback, and anything promoted into a reference file is pruned. If the Knowledge Base is what the agent knows about the world, memory is what it has learned on the job and not yet consolidated.
Structure: an index plus topic files
The entry point ismemory/MEMORY.md — an index, not a store. Each line links a topic file and compresses its content to one sentence, under headed sections (Patterns, Gotchas, Decisions, Feedback, Team). Bloom checks the index at the start of interactions where past context would matter; the index tells it which files exist and what they contain, so it reads only what the task needs.
Around the index sit three kinds of files:
- Four canonical topic files —
patterns.md,gotchas.md,decisions.md,feedback.md— the default homes for new learnings. - Per-topic deep-dive files — a learning substantial enough to need its own file gets one, and the index links it.
- Three structured queues (engine repository only) —
maintenance-findings.md,capability-gaps.md, andskill-regressions.md, each carrying its own entry format and lifecycle contract in its header.
The entry format
One format is specified for any skill writing memory:From tracks who on the team holds which knowledge and preferences. Applied to enables pruning: once a learning has been written into a reference file or a skill procedure, the memory entry was the vehicle, not the destination — it can be pruned in the next reflection cycle. Tagging that line Promote-to: knowledge/ nominates the entry for human-gated promotion into the knowledge base.
There is also a write threshold: memory is not a diary. The instruction to the agent is to store only learnings that will change how it operates — routine interactions produce no entry.
A synthesized example, the shape of a real entry:
The structured queues
The three queues are the most rigorously specified files in the folder — each is a small state machine.maintenance-findings.md — non-blocking findings from the engine’s self-check (blocking findings are surfaced immediately, never queued). Entries move open → proposed → resolved or rejected, with three rules: closed-loop verification (an entry resolves only when the specific guard named in its Source guard field re-runs clean — approval alone never resolves anything), dedupe (a recurring open finding updates Last seen instead of duplicating), and recurrence re-opens (a resolved finding that comes back re-opens the same entry, keeping its verification history).
capability-gaps.md — an append-only log of requests Bloom could not route to any skill. Each entry records the request near-verbatim, which registry entries were considered and why each was rejected, and the outcome. The reflect cycle clusters recurring gaps into proposals for new skills; an entry is pruned only when a skill covers the gap or it is explicitly rejected. This is the raw material the skill-creation pipeline feeds on.
skill-regressions.md — failures observed while executing a skill: wrong output, missed validation, bad routing. Two or more instances of the same failure become a fix proposal. Its lifecycle has one distinctive twist: most skill failures have no machine check, so a proposed fix is verified only by the skill’s next successful use. A single instance stays logged as a data point.
All three carry the same authority disclaimer: status bookkeeping is autonomous (these are memory files), but the fixes themselves are always human-gated proposals.
Who writes memory
Four writers, one of them automated:- Bloom, during work — after a meaningful interaction, it creates or updates a topic file and updates the index.
- A session-end hook — the one automated writer. A
Stophook script scans the session transcript for human correction patterns (a regex heuristic matching phrases like “no,”, “wrong”, “should be”, “actually” — not model-driven extraction) and appends up to five matches as a dated Session Learnings block tofeedback.md. It respects a.bloom-disabledmarker and honorsSUBSTRATE_MEMORY_DIR. - Workflows — the daily evolve/reflect cycle writes a dated cycle record to the index (consolidated, pruned, promoted, proposed, deferred); the component-build workflow records discovered patterns; the health-check workflow writes its summary.
- The routing fallback — appends to
capability-gaps.mdwhenever no skill route matches.
The trust boundary
The single most important fact about this folder is what it is allowed to touch. Autonomous writes are confined tomemory/ and references/ — never knowledge/, never skill or agent definitions. The tiers form one directed flow with one human gate:
An unattended reflection can consolidate memory and update references, and it can propose a knowledge promotion — but the knowledge base is out of scope for reflection entirely. See the promotion path for the full five-step lifecycle.
Pruning
Reflection prunes an entry when it is promoted (now lives in a reference or skill procedure), stale (describes a file, field, or pattern that no longer exists), embedded (a one-time correction since internalized into standing procedure), or superseded. Reflection runs on a daily cycle, and is also triggered by volume (roughly 8–10 new entries across topic files), open maintenance findings, or recurring skill regressions. This is why the folder stays a working set: consolidation is scheduled, not aspirational.In your project
substrate init seeds a client-owned memory in your content root: a client MEMORY.md plus the four canonical topic-file stubs, created only if missing — re-running init never clobbers what Bloom has learned about your project. The scaffolded settings wire the session-end hook with SUBSTRATE_MEMORY_DIR pointed at that client path, so corrections you make in-session accumulate locally. The three structured queues are engine-repository constructs and are not scaffolded into clients.
Knowledge Base
Where vetted, sourced learnings are promoted — and why only a human can put them there.
Bloom
The agent whose memory this is — activation, skills, and guardrails.