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

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.