Files tell the readable story
Inbox notes, team notes, knowledge entries, personal notebooks, and pinned context stay easy for people and agents to inspect on disk.
Interactive system tour
How Minions remembers.
A durable trail of human context, agent learnings, and task outcomes becomes focused evidence for the next dispatch - without turning recalled text into trusted instructions.
Editorial source verified against the current consolidation, retrieval, prompt, lifecycle, and fencing code.
Task-aware
context
context
Pinnedalways first
Inboxpending notes
SQLite + FTS5structured recall
Promptbounded evidence
Filesreadable history
Episodestask outcomes
The idea in plain language
One memory system, two durable layers.
Markdown keeps the history inspectable. SQLite makes selected facts searchable and lifecycle-aware. Prompt assembly decides what is useful now.
SQLite powers focused recall
Structured records, lifecycle status, provenance, scope, and FTS5 turn a large history into a bounded candidate set for a specific task.
The prompt is the selection gate
Pinned context comes first. Then active retrieval supplies relevant records, or Minions falls back to bounded team and personal files.
Hybrid does not mean mirrored. Synchronization is directional, not a general two-way sync. SQL is authoritative for structured recall; the intentional file surfaces remain authoritative for their own content.
Evolution, verified in repository history
How memory grew with the problems it had to solve.
Each layer stayed useful after the next one arrived. The current system keeps readable files, adds focused retrieval, and falls back deliberately instead of treating older paths as obsolete.
-
Shared team memory
Problem solved: useful findings were scattered across individual task outputs.
Inbox consolidation turned agent and human notes into a deduplicated, readable team digest in notes.md, while preserving source notes in the archive.
Current role: consolidation still maintains the team-readable record; the digest is also the team half of the legacy prompt path.
-
Personal routing
Problem solved: one shared digest gave every specialist the same broad history.
Consolidation began routing configured, non-temporary authors' findings into knowledge/agents/<agent>.md, using YAML identity with a filename fallback.
Current role: these notebooks remain readable and maintained, but broad prompt injection is now a fallback rather than the default recall strategy.
-
Structured recall
Problem solved: growing team and personal files spent prompt space on history unrelated to the task.
Migration 017 added scoped SQL records and FTS5 search. Retrieval now reranks task matches and builds a bounded Relevant Memory pack with provenance, then wraps it in an UNTRUSTED-INPUT fence.
Current default: retrieval is enabled with shadow mode off and may select up to 8 records within 8,192 bytes; pinned context remains first.
-
Outcome capture and fallback
Problem solved: authored notes did not consistently preserve the normalized result of every task.
Opt-in memoryEpisodicCapture stores compact success, partial, or failure outcomes in SQL instead of intentionally collecting transcripts or chain-of-thought. It remains off by default; without a structured summary, a redacted, truncated stdout fallback can include transcript-like text.
Legacy fallback: when retrieval is off, shadowed, empty, or errors, prompt assembly uses bounded notes.md plus the assigned agent's notebook. Episode capture does not replace either file.
Milestone months follow the commits that introduced each capability; behavior labels describe the current implementation.
End-to-end data flow
Follow one useful finding.
Choose a step, use the left and right arrow keys, or play the flow. Every step remains visible as ordinary content when JavaScript is unavailable.
Sources of memory
A useful signal enters through a deliberate surface.
Humans, agents, and the engine all contribute - but not every source takes the same route.
- Quick Notes, successful agent findings, feedback, and engine alerts can create inbox files.
- Direct KB authoring writes a readable knowledge entry plus a human-trusted SQL record.
- Pinned context writes only pinned.md; episodic capture writes only SQL.
Human
Quick note · Pinned note · Knowledge entry
Quick note · Pinned note · Knowledge entry
Agent
One success-only findings file with provenance
One success-only findings file with provenance
Engine
Alerts · Feedback · Optional task outcome
Alerts · Feedback · Optional task outcome
Three routes
Inbox · Direct file + SQL · Direct SQL
Inbox · Direct file + SQL · Direct SQL
Inbox staging
The inbox is a queue, not yet team memory.
Eligible Markdown notes wait under notes/inbox/ until the consolidation threshold is met.
- The default threshold is five eligible notes.
- Items pinned against consolidation and files already in flight are excluded.
- Successful tasks write exactly one assigned note; failed tasks do not.
1 note
Waiting
Waiting
3 notes
Still waiting
Still waiting
5 eligible notes
Consolidation can begin
Consolidation can begin
Pinned inbox item
Held out of the batch
Held out of the batch
Inbox consolidation
Summarize, classify, route, then archive.
The normal path uses a direct LLM for a concise digest and falls back to deterministic regex processing when that call fails.
- Team digest content appends to notes.md under a file lock.
- Each source is classified into a readable KB category and eligible authors receive personal memory.
- Corresponding semantic records are upserted into SQL before processed inbox files are archived.
Normal batch
Digest → classify → team + KB + agent + SQL → archive
Digest → classify → team + KB + agent + SQL → archive
Important exception
If one content hash is more than 80% of the batch, Minions archives the entire batch and skips all normal writes.
If one content hash is more than 80% of the batch, Minions archives the entire batch and skips all normal writes.
Why?
A circuit breaker prevents duplicate storms from amplifying themselves.
A circuit breaker prevents duplicate storms from amplifying themselves.
Durable storage
Readable history and structured recall coexist.
The layers overlap on normal ingestion paths, but each remains authoritative for a different job.
- notes.md is the team digest and legacy team prompt input.
- knowledge/agents/<id>.md is the consolidation-owned legacy personal notebook.
- memory_records owns structured body, scope, trust, provenance, and lifecycle status.
Team notes
Shared, recent operating context
Shared, recent operating context
Per-agent memory
Agent-specific learnings; temp agents excluded
Agent-specific learnings; temp agents excluded
Knowledge base
Categorized, browsable source material
Categorized, browsable source material
SQLite + FTS5
Scoped, lifecycle-aware retrieval records
Scoped, lifecycle-aware retrieval records
Active retrieval
A task becomes a lexical, scoped search.
Minions builds the query from the work item, references, failure context, source plan, and PR metadata.
- FTS5 searches active global, current-project, and assigned-agent records.
- Agent/external procedural records are excluded unless trust is human or system.
- Deterministic reranking boosts scope, trust, paths, recency, importance, and confidence before deduplication.
Task query
At most 32 unique non-stop-word terms
At most 32 unique non-stop-word terms
FTS5 candidates
Default pool: 50
Default pool: 50
Rank + dedupe + pack
Default top K: 8 · Default budget: 8,192 bytes
Default top K: 8 · Default budget: 8,192 bytes
Prompt assembly
Always pinned; then relevant or fallback.
Prompt assembly is single-choice for broad memory: a non-empty active pack suppresses the team and personal appendices.
- Pinned context is added first and remains independent of retrieval mode.
- Shadow mode records retrieval telemetry but still injects the legacy team/personal pair.
- Every memory appendix is wrapped as untrusted evidence with source provenance.
Pinned Context
Always first · 4,096 JavaScript code units
Always first · 4,096 JavaScript code units
Relevant Memory
Or Team Notes + Personal Memory
Or Team Notes + Personal Memory
<UNTRUSTED-INPUT>
Source attributed · closing tags escaped · UTF-8 bounded
Source attributed · closing tags escaped · UTF-8 bounded
Episodic capture
The outcome can become evidence for later work.
When enabled, post-completion lifecycle stores a compact SQL episode for success, partial, and failed outcomes.
- Episodes include outcome, task, agent, project, PR, failure class, bounded files/tests, and summary.
- Secrets are redacted; injection-flagged and nonce-mismatched reports are excluded.
- Capture is best-effort and defaults off, so a write failure never changes task completion.
Preferred summary
Parsed runtime or structured completion report
Parsed runtime or structured completion report
Honest limitation
If no summary exists and stdout has no "type": marker, redacted raw stdout can supply up to 4,000 characters.
If no summary exists and stdout has no "type": marker, redacted raw stdout can supply up to 4,000 characters.
Structured episode
System trust · project, agent, or global scope
System trust · project, agent, or global scope
Interactive architecture map
Click a surface to see what it owns.
The system is intentionally not a single database. Follow the normal ingestion route, the pinned shortcut, and the outcome feedback loop.
Sources
Memory begins with bounded, attributable contributions rather than an automatic transcript of everything an agent sees.
- Human-authoredQuick Notes, pinned entries, and direct KB entries.
- Agent-authoredOne assigned success note with required agent provenance.
- System-authoredAlerts, feedback, workflow findings, and optional completion episodes.
Markdown files
Files preserve coordination and human-readable history. They are not a disposable cache of SQL.
- Pendingnotes/inbox/*.md
- Shared and personalnotes.md and knowledge/agents/*.md
- Curated and pinnedknowledge/ and pinned.md
SQLite + FTS5
memory_records owns active structured content and metadata. FTS5 is a trigger-maintained derived index.
- TypesSemantic, episodic, procedural.
- ScopesGlobal, project, agent.
- LifecycleActive, superseded, retracted, expired.
Pinned context
pinned.md is read directly for every rendered agent prompt, before either retrieval mode.
- Not structured pinningPinning a SQL record changes trust and importance; it does not edit pinned.md.
- Bound4,096 JavaScript UTF-16 code units plus a truncation notice.
Prompt assembly
The prompt receives a small, ordered evidence pack - never an unbounded dump of the knowledge base.
- OrderPinned first, then relevant memory or legacy team/personal memory.
- SafetyMemory is source-attributed and fenced as untrusted input.
Task-aware retrieval
Lexical FTS5 search produces candidates; deterministic code reranks and packs them to the configured byte budget.
- TelemetryQuery, candidate count, selected count, bytes, duration, and shadow state.
- ProvenanceEvery packed record includes id, type, scope, date, and source.
Task episodes
Post-completion capture can turn a bounded outcome into a system-trusted record for later task-aware recall.
- DefaultOff via engine.memoryEpisodicCapture.
- Failure behaviorBest effort; storage failure does not rewrite the completed task outcome.
Prompt assembly and trust
A bounded evidence pack, not a memory dump.
The final prompt preserves operator priority, selects one broad-memory mode, records provenance, and fences recalled content as data.
Pinned Context Always
Direct from pinned.md, capped before fencing.
One memory mode Either / or
Relevant Memory when active retrieval returns a non-empty pack; otherwise Team Notes + Personal Memory.
Later appendices
Project instructions and other non-memory context follow their own bounded assembly paths.
Active retrieval
Feature on, shadow off, and at least one eligible result.
- Inject task-selected Relevant Memory.
- Suppress broad team and personal appendices.
- Persist retrieval telemetry.
Legacy fallback
Feature off, shadow on, empty search, or retrieval/telemetry error.
- Inject bounded Team Notes.
- Add bounded Personal Memory for configured non-temp agents.
- Missing files are safely skipped.
Shadow mode is observational: Minions computes retrieval and stores telemetry, but the prompt still receives the legacy files.
4,096
Pinned code units
8,192 B
Retrieved pack
Top 8
Selected records
50
FTS candidates
8,192 B
Each legacy file
65,536 B
Any fence body
Untrusted-input fencing
Memory is evidence, never a new instruction channel.
The wrapper sanitizes the source attribute, escapes attempted closing tags, and truncates inside the fence on a UTF-8 boundary. Agents are told to verify recalled claims against live code.
<UNTRUSTED-INPUT
source="memory-retrieval:item=W-...">
id=M-... | type=semantic
scope=project:minions | date=...
Recalled evidence, with provenance.
</UNTRUSTED-INPUT>
source="memory-retrieval:item=W-...">
id=M-... | type=semantic
scope=project:minions | date=...
Recalled evidence, with provenance.
</UNTRUSTED-INPUT>
Operational controls
Tune selection, not the truth.
Settings change thresholds, budgets, rollout mode, and optional capture. They do not turn the file and SQL layers into a two-way mirror.
Retrieval rollout
Feature, observation mode, and selected-pack bounds.
- features.memoryRetrieval
- true
- engine.memoryRetrievalShadowMode
- false
- engine.memoryRetrievalTopK
- 8
- engine.memoryRetrievalMaxBytes
- 8,192
- engine.memoryRetrievalCandidateLimit
- 50
Capture and consolidation
When notes are processed and whether task outcomes become episodes.
- engine.inboxConsolidateThreshold
- 5
- engine.memoryEpisodicCapture
- false
- engine.autoConsolidateMemory
- true
Personal-file retention
File-backed personal history has entry and byte windows; optional summarization is conservative.
- engine.agentMemoryMaxEntries
- 300
- engine.agentMemorySummaryEnabled
- false
- engine.agentMemorySummaryThreshold
- 30
- engine.agentMemorySummaryDays
- 30
Trust and feature overrides
The fence cap is an engine default; feature resolution supports a process-level override.
- ENGINE_DEFAULTS.untrustedFenceMaxBytes
- 65,536
- MINIONS_FEATURE_MEMORYRETRIEVAL
- 1 | 0
Dashboard SettingsFeature toggle, shadow mode, episodes, retrieval bounds, inbox threshold, and automatic KB sweep.
Inbox & Memory searchQuick Notes, Team Notes, KB authoring, manual sweep, lifecycle-aware structured search, and provenance.
Local API/api/pinned, /api/knowledge, and /api/memory-records/search.
Troubleshooting and limitations
Know what "working as designed" looks like.
Open a question for the short answer. The written guide has the full operating detail and API reference.
Why do I see Team Notes instead of Relevant Memory?
The feature may be off, shadow mode may be on, the task query may have no indexable terms, FTS5 may find no eligible rows, or retrieval/telemetry may have thrown. These all intentionally select the legacy fallback.
Why is a note still waiting in the inbox?
Check the eligible count, consolidation pin state, in-flight state, write access to notes.md, and whether a required personal-memory write failed. An LLM failure alone should not strand the batch because regex fallback exists.
Why did search miss text that exists in Markdown?
Active search is lexical FTS5, not embeddings. Out-of-band edits and file-only mutation paths do not trigger a general SQL reindex, so compare SQL provenance with the current source file.
Does pinning a search result make it global prompt context?
No. A structured-record pin raises trust, confidence, and importance and restores active status. It does not edit pinned.md, bypass lexical matching, or guarantee top-K selection.
Can a duplicate-heavy batch lose its minority note?
It can leave the normal pipeline. When one hash exceeds 80% of the eligible batch, the circuit breaker archives the entire batch, including minority notes, and skips team, KB/SQL, and personal writes.
Are episodes guaranteed to contain only clean summaries?
No. Structured or parsed summaries are preferred, but raw stdout can be the redacted, 4,000-character fallback when no summary exists and no "type": marker is present.
Current boundaries to remember
There is no general two-way file/SQL mirror, no full reindex command, and no scheduled SQL-record expiry. FTS5 is lexical rather than semantic embedding search. File TTL and SQL lifecycle are separate. Never repair divergence by editing engine/state.db directly.
Minions memory is a curated trail with provenance, not a transcript and not a second command channel.