update-memory

name	update-memory
description	Maintain an existing project-memory store with durable facts learned during completed project work, decisions, fixes, migrations, or milestones. Use only when a usable baseline already exists; do not use for initial bootstrap, primary ingestion or refresh of an external source, read-only auditing, temporary progress, or speculative notes.

Update Memory

Record the smallest durable change supported by completed project work.

Load the Contract and Establish Context

1. Read references/memory-contract.md completely before proposing edits.
2. Resolve one project root and memory root from the user's request or current project. Ask for explicit consent before reading or writing any global store, sibling project, unrelated repository, or other root outside that project.
3. Read the active MEMORY.md and relevant local files. If no useful baseline exists, route to create-memory.
4. Gather evidence from the user's confirmed summary, adopted decisions, completed work, changed interfaces, tests, failures, and available focused repository diff or history. Treat repository state as evidence, not a substitute for user intent.
5. Route a task whose primary purpose is importing or refreshing supplied external content to ingest-memory. When a source-backed conclusion arose incidentally during project work, record full structured provenance under the contract.

Decide Whether to Write

Write only a durable architectural or product decision, workflow or integration constraint, recurring preference, resolved failure and prevention rule, shipped contract or migration, operational milestone, or source-backed fact needed later.

Skip temporary progress, unfinished experiments, routine implementation detail, information obvious from code or existing instructions, secrets, private data, raw logs or conversations, and unadopted ideas.

Use this order:

1. Update an existing focused file only when its durable truth changed.
2. Propose one focused new file when durable knowledge is absent.
3. Skip and explain temporary, redundant, unsupported, or uncertain material.

Preview file-level changes. Ask for confirmation when the root was inferred, cross-root access is involved, substantial text would be replaced, more than three files would be created, or relationships across multiple topics would change.

Update and Reconcile

1. State the new durable fact and evidence in one sentence before editing.
2. Search all local memory filenames, names, descriptions, source identities, and distinctive claims for duplicates or conflicts.
3. Determine current truth from the strongest available evidence; do not automatically prefer existing text or newer text.
4. Update the smallest focused section. Preserve dated historical context when it explains the current state, mark superseded details explicitly, and keep unresolved contradictions in a short Conflicts or Open Questions section.
5. Follow the contract exactly. Preserve or add structured provenance, keep local related filenames symmetric, and update last_updated only when durable content changes.
6. Update MEMORY.md only when a file or its purpose changes, using the exact contract grammar.

Validate and Report

Run:

python scripts/validate_memory.py <memory-root>

Fix only errors introduced within the approved scope. Report evidence used, files changed, facts skipped, duplicate or conflict decisions, validation results, and remaining limitations. Recommend audit-memory after cross-file, index, relationship, or provenance changes.