context-memory

# context-memory Lifecycle stage: LEARN ## Trigger Use when an agent needs durable context, asks whether memory should be updated, resumes old work, ingests project knowledge, or finishes a loop that may produce reusable learning. ## When not to use Do not use when this trigger is absent; choose the command or skill that owns the requested state, artifact, and verification gate. ## Inputs - Current request and Agent Brain state. - Candidate fact, decision, procedure, source, or artifact. - Evidence for the candidate memory. - Expected lifetime of the information. - Target memory tier: profile, session recall, project docs, skill, or external index. ## Procedure 1. Classify the candidate as stable fact, durable decision, reusable procedure, source-backed project knowledge, temporary task progress, or sensitive/private data. 2. Choose the smallest correct storage target: - profile memory for stable user/project preferences, - session recall for past work history, - project docs for versioned decisions and architecture, - skill for repeatable procedures, - external index only for large corpora where docs remain the source of truth. 3. Reject noisy logs, stale status, raw personal data, secrets, and one-off task progress. 4. Attach evidence or mark the memory as an assumption. 5. Write the update in neutral, declarative language with a scope and freshness note. 6. For resumes, handoffs, and long runs, write a context boundary: included context, excluded context, read files, modified files, compaction, and freshness. 7. Add or update an eval, validator, or review gate when the memory rule should not regress. ## Anti-Rationalization | Shortcut | Rebuttal | |---|---| | "Remember everything just in case." | Durable memory should store stable facts, decisions, or reusable procedures, not raw task logs. | | "The chat is enough evidence." | Versioned docs or skills need checked sources, files, commands, or explicit assumptions. | | "This procedure belongs in memory." | Repeatable procedures belong in skills or docs so future agents can inspect and validate them. | ## Verification - The target tier matches the expected lifetime and use case. - The memory is evidence-backed or explicitly marked as an assumption. - The memory decision artifact names the checked doc, skill, command, or source evidence. - Handoffs and long-run memory updates include a context boundary with read files, modified files, omitted context, compaction status, and freshness. - Temporary progress is not stored as durable knowledge. - Procedures become skills rather than profile notes. - Secrets and raw sensitive data are excluded. - The update can help a future agent act correctly without rereading the full chat. ## Output Artifact Produce a memory decision that names the target tier, evidence, freshness/scope, rejected material, blockers, written update or no-write reason, and the next action for any validator, eval, doc, or skill follow-up. ## Failure Modes - Saving task logs as permanent doctrine. - Hiding uncertainty by writing assumptions as facts. - Duplicating the same knowledge across memory, docs, and skills. - Storing a procedure as a user preference instead of a skill. - Using external indexes as the source of truth instead of accelerators. - Forgetting to update project docs when a durable decision changes. ## Example Trigger: project context may need to be remembered, retrieved, updated, or rejected. Action: separate stable preferences, project docs, procedures, session recall, and private data before writing memory. Output artifact: `templates/memory-decision.md` with blockers and next action. Verification: cite tier, evidence, freshness, privacy review, rejected material, and next use. Input: “We fixed this after three attempts; remember the approach.” Better response pattern: 1. extract the reusable procedure, 2. discard temporary file names, PR numbers, and timestamps, 3. save the procedure as a skill or patch an existing skill, 4. link the evidence or command pattern, 5. verify the skill has trigger, procedure, pitfalls, and verification sections.