---
name: memory-maintenance
description: Use when writing, organizing, consolidating, or cleaning durable Memory content, or when promoting recurring lessons into long-lived insights and reflections.
---

# Memory Maintenance

## Core Principle

Keep Memory small, durable, searchable, and safe. Store only information that
will be useful beyond the current task; current execution state belongs in the
runtime recovery files named by the workspace instructions.

## Find Before Reading Broadly

1. Read the configured Memory index first.
2. Use semantic Memory search for lookup. Search one focused topic with 2–6
   discriminative terms; include exact IDs, symbols, paths, or stable phrases
   when known. Pass only the query unless a filter or larger budget is needed.
3. If results are empty, retry once with fewer, more literal terms or split
   mixed intents. Then use grep or bounded file traversal over the configured
   Memory root. When an exact unique string or path is already known, bounded
   grep may be cheaper. Never scan unrelated roots or perform an unbounded walk.
4. Read only selected result paths and line ranges needed for the task.

## Classify Durable Content

Follow the repository's current index and layout. For the standard Memory
template:

- `system/`: stable identity, goals, operating boundaries, and durable
  commitments.
- `profiles/`: user preferences and stable collaborator facts.
- `knowledge/concepts/`: durable terminology, architecture, and mental models.
- `knowledge/workflows/`: repeatable procedures, checks, and decision rules.
- `events/`: dated evidence or decisions that remain useful for later
  synthesis.
- `reflections/`: cross-event insights, lessons, and improved heuristics.

Keep the Memory index concise. It is a navigation page, not a transcript or
database. Put detail in focused files and link them from the index.

For user preferences, update the existing profile linked by the Memory index;
the managed standard template uses `profiles/user.md` under its configured
Memory root. For bound managed Memory, never redirect a user Memory request to
workspace-root `kb/`: that directory is the separate Local Knowledge Index.

## Decide What to Write

An explicit user request to remember, store, update, or forget something makes
the local Memory write the current task. Subject to the safety rules below,
complete the filesystem change before confirming that it was recorded. If the
local write fails or the changed file is outside the configured Memory root,
say it was not recorded. Verify the canonical file exists after the edit. A
successful local write does not prove cloud synchronization;
never describe it as cloud-synced unless that separate outcome is confirmed.

Write stable, future-reusable facts, preferences, decisions, workflows,
concepts, and lessons. Preserve active commitments and evidence needed to
understand a durable conclusion.

Do not store secrets, credentials, access tokens, private keys, raw chat transcripts,
command logs, temporary status, speculative claims, or details
that expire with the current task. If nothing has durable value, do not write
Memory merely to record activity.

## Maintain While Touching

When reading or updating a durable file, make a bounded consolidation pass over
that file and the index links directly affected by the change:

1. Remove expired, superseded, duplicated, overly detailed, or low-value
   material.
2. Merge scattered facts into one clear durable statement.
3. Keep dates or source references only when they are needed to judge
   freshness or support a decision.
4. Promote a stable pattern that recurs across events into a concept, workflow,
   insight, or reflection; do not promote a one-off observation prematurely.
5. Update the Memory index when a durable file is added, moved, merged, or
   removed.

Stay within the touched file and its relevant index links unless the user asks
for a broader cleanup. Preserve user intent and do not rewrite unrelated
history.

## Quality Check

Before finishing:

- Confirm the content is in the correct category and is useful after restart.
- Confirm no secret or raw transcript was introduced.
- Confirm duplicates and stale statements were reconciled.
- Confirm stable lessons were promoted to Insights or Reflections when
  warranted.
- Confirm the Memory index still points to the canonical files with concise
  descriptions.