These pages explain why AgentM works the way it does — the choices behind it and the trade-offs each one accepts. If you are looking for technical specifications, see Reference. For high-level design, see Architecture.

AgentM gives your coding agent a permanent memory. It writes what it learns — about you, and about each project — as plain Markdown notes in a folder you own, brings the right notes back at the right moment, and looks after the collection over time so it gets better instead of messier. Every note is a file: readable, editable, yours, with no hidden database behind it. The agent curates that collection, but you hold the vetoes — nothing durable gets written, linked, or forgotten without you somewhere in the loop.

A note moves through six stages between the moment it's noticed and the moment it's quietly retired:

1. Capture — reflection notices something durable in a session. A confident, clear-cut signal saves straight to a curated note; a hunch lands in an inbox for you to confirm or drop. See Experience & Dreaming.
2. Index — the note is embedded into the vector index and linked to its neighbors by typed edges (uses, fixed, supersedes, and six more), so recall can follow a relationship, not just match text. See Memory index.
3. Recall — every prompt searches the vault by meaning and by keyword, on top of a small always-load floor of standing rules that never has to be searched for.
4. Heat — notes that keep getting used float up toward that always-load floor; notes nobody's touched cool back down. Forgetting is a managed policy here, not an accident.
5. Sleep — each night, the dreaming binary sinks notes nobody has recalled in a year, collapses exact copies, refiles, and redraws the maps, journaling every change it makes. A Python pass runs after it and writes no note: it lists possible twins, notes that share a key, and proposed facets on the needs-review page, where the call is yours. See Experience & Dreaming.
6. Watch — /console, the morning note the night leaves behind (see Read the morning note and the nightly scorecard), the session-start briefing (see Auto-orchestration), and the nightly health score keep the collection's shape visible, so drift shows up before it becomes a problem.

• Product intent — why we created AgentM, and who it is for.
• How the pieces fit — how the phases, adapters, templates, and scripts work together.
• Memory↔storage seam — why the engine uses an interface for generalized storage access, and why the default store is plain markdown.
• Memory↔process seam — why a process reaches the engine through a client, and why that dependency is one way.
• Soft composition and hard composition — why in plugins enhances: and requires: stay separate, and what the capability resolver does.
• Auto-detect + Auto-configure — why the first session proposes a config and waits for your approval, and why it lives in project.json.
• Auto-orchestration — why the memory skills became something automatic instead of explicitly requested, and how the briefing, idle work, and phase dispatch stay quiet until they are needed.
• Single-repo state mode — why AgentM falls back to repo-local state when there is no vault accessible.
• GitHub Projects integration — why and how the harness mirrors your work onto a GitHub board.
• Named plans — why the harness can hold more than one active plan in a single shared vault.
• Health scorecard — the nightly health-tier scorecard's own reasoning: why it's advisory-only, and why a dark check counts for neither the family score nor against it.

Designs · Architecture · Reference · Home