Planning and Memory

Planning and memory

Useful continuity depends on giving each fact one clear home. dotSYSTEMX separates shared context, intended outcomes, current work, learned facts, and individual worker notes.

Where information belongs

Record inside .SYSTEMX	Keep here	Avoid duplicating
WORK/FOCUS.json → generated CURRENT.md	Selected objective, existing task IDs, optional checkpoint pointer	Hand-maintained task state, blockers, or runtime health
GLOBAL/CONTEXT.md	Purpose, constraints, terminology, authoritative sources	Whole task lists or session transcripts
PLAN/MASTER-PLAN.md	Outcomes, milestones, acceptance criteria, dependencies	A second set of task-status checkboxes
WORK/TASKS.json	Task owner, state, dependencies, evidence, history	Hand-edited copies of generated status pages
MEMORY/PROJECT.md	Verified facts, accepted decisions, lessons, historical references	Unreviewed worker conclusions or another current task list
AGENTS/<id>/MEMORY.md	One worker's scope, observations, blockers, next action	Other workers' notes or a duplicate backlog
MEMORY/sessions/	Longer, sanitized historical checkpoints	An archive that every session must fully reload

“Global” means shared across the active project's agents. Reference approved organization-wide standards with their source, version, scope, and review date. The template does not synchronize other projects' memory or change a host tool's global memory settings.

Select the active objective and existing tasks with focus. Changing focus does not change task states or delete old checkpoints. See the command reference.

Connect a milestone to work

Declare a stable milestone ID in the master plan's table:

| ID | Outcome | Acceptance evidence required | Dependencies | Task IDs |
| --- | --- | --- | --- | --- |
| M-001 | Establish the project baseline | Reviewed setup and verification evidence | None | TASK-001 |

Then create its task in an adopted project:

bash .SYSTEMX/SYSTEMX.sh task-add \
  --title 'Establish the project baseline' \
  --milestone M-001 \
  --acceptance 'Setup is reproducible and the required checks are recorded' \
  --next 'Confirm the selected runtime and existing project scripts'

Milestone IDs use M- followed by at least three digits. A task cannot reference a milestone that is not declared in the plan's Markdown table. Use the ID returned by task-add when updating the plan; TASK-001 above assumes a fresh ledger.

Checkpoint before stopping

Record the objective and task IDs, relevant revision and local changes, work completed, checks and evidence, remaining uncertainty, exact blocker, and concrete next action. Include a timestamp and author.

A useful next action is specific enough to resume: for example, “Run the focused import regression against the current fixture and compare the observed row count with the accepted contract.” A vague note such as “continue testing” forces the next session to reconstruct the work.

Use .SYSTEMX/templates/SESSION-CHECKPOINT.md for a longer record. Archive it under MEMORY/sessions/ with a unique timestamp, task ID, and agent ID. Link the record using focus --checkpoint when selecting the current objective. Keep task next actions and blockers in the ledger; the dated checkpoint retains what was observed then. Do not copy its full contents into every context file.

Resume with current evidence

bash .SYSTEMX/SYSTEMX.sh context --agent agent.0

The packet includes up to 6,000 characters of the generated current view and up to 6,000 from each of four shared/agent documents, plus up to 25 relevant open-task summaries (2,000 characters each). Selected focus tasks come first. Other workers' private memory and the historical archive are not preloaded. Truncation is labeled; read the indicated file or task directly for the remainder.

Recheck facts that can change: repository and branch, local changes, remote revisions, ports, processes, active accounts, permissions, and service state. Continue the accepted plan at the next incomplete step instead of restarting planning or rerunning all historical tests. Retain original evidence at its proven scope. Follow retained live job handles to a terminal result before starting conflicting replacement work. A timeout does not establish cancellation. See Evidence and acceptance.

Promote evidence into shared memory

Workers keep tentative findings labeled in their own notes. Agent 0 reviews the evidence and promotes durable facts, accepted decisions, and useful lessons into project memory. Include the source and the condition that would require rechecking a fact. Preserve a short reason when an old conclusion is superseded.

Project files provide persistent context when a later session reads them. They do not provide automatic model recall, prove current runtime state, or override current instructions. Keep credentials, personal data, and private transcripts out of reusable or public memory records.

For projects spanning many sessions, follow Anti-drift and long-running work. It explains bounded batches, stale evidence, interrupted jobs, ledger growth, and why checkpointing is part of continuing the same accepted plan. Copy a resume or handoff request from Prompt cookbook.

Phases, waves, and knowledge across turns

Milestones define measurable outcomes or gates; a wave groups related phases, and a phase holds a coherent task list. Optional groups, subtasks, and single actions add detail only where useful. A ready execution batch selects eligible, non-conflicting canonical tasks for actual workers; it is separate from the planning hierarchy. The optional ROOT root node command records that structure without adding status fields to WORK/TASKS.json. Current focus references selected existing tasks. Keep detailed source research indexed and load the evidence needed for the active task. See ROOT planning.

Agent 0 connects this plan to each meaningful work turn, Agent X records the time and observed evidence, Agent Y may return a bounded task-selected CLI/PR handoff, and Agent Z reviews at an acceptance boundary or on request. Accepted corrections improve shared project knowledge; they do not retrain the model or guarantee that every turn is an improvement. The one-shot guide explains the founder's shared-brain metaphor and its practical limits.

Specialist short-term detail and archives

AUTOBOT holds optional detailed working references. Its Memory.MD is short-term specialist context; Archive.MD points to superseded detail. Promote reviewed durable facts into MEMORY/PROJECT.md only when useful, with provenance, rather than copying an entire request or dataset. Agent Alpha fingerprints selected requests and reuses matching completed results without refreshing original evidence time. Raw/private/large files belong in local DATA; default context does not scan that payload tree. Each .SYSTEMXP child must explicitly initialize its own panel/storage and retains separate facts and requests.

Optional structured ROOT planning

ROOT planning, rules, and task delta adds ROOT/SX-RULES.md, ROOT/SX-MILESTONE.md, structural requests/nodes, and observed harness/bot mappings in compatible defaults. Use milestone → wave (group of phases) → phase (coherent task list) → optional group → task → optional subtask → single action. Skip levels that add no value and expand only the next useful work. RTask/STask describe request origin/delegation; events belong to Agent X. Canonical task state and acceptance stay in WORK/TASKS.json; ROOT does not create a competing master plan or completion ledger.