Memory Maintenance

Memory Maintenance

Use this skill when the task is about the memory framework itself rather than one domain memory entry.

What this skill owns

• Memory-family contract design in workspace.manifest.yaml
• Shared source vs runtime working-copy boundaries
• Generic lifecycle commands:
• render
• promote
• reindex
• query
• validate
• compact
• Durable item lifecycle rules:
• dedupe
• supersede
• temporal validity
• provenance / evidence retention
• Sidecar retrieval design using local SQLite indexes

Core model

• Shared file memory in Git is the only durable source of truth.
• Runtime memory under ~/.codex/memories is a mutable working copy.
• SQLite sidecars under ~/.codex/memories/.sidecar are derived retrieval indexes, never the primary store.
• Hot-path writes should land in runtime/local/session sinks first.
• Promotion back to shared source must stay confirmation-gated and diff-driven.

When to use

• A workspace is introducing or refactoring memory_families.
• Shared/runtime render or promote logic is duplicated across scripts and should move into the generic core.
• Retrieval quality needs sidecar search, relation expansion, temporal filtering, or better validation.
• A family needs durable lifecycle fields such as status, valid_from, valid_to, supersedes, related_refs, or confidence.
• A workspace needs dry-run promotion, digests, or non-destructive compaction/defrag behavior.

Workflow

1. Read the owning workspace manifest and identify the target memory_families.
2. Check the family contract against:

• [memory-family-v1 schema](../../schemas/memory-family-v1.md)
• [memory-v2 schema](../../schemas/memory-v2.md)

1. Implement or update the family transformer so the generic core can:

• render shared source to runtime
• stage shared source for promote
• build sidecar docs/relations
• validate domain-specific invariants

1. Prefer the generic CLI in [memorycli.py](../../scripts/memorycli.py) over ad-hoc family scripts.
2. Keep old family entry points as thin wrappers when compatibility matters.
3. Rebuild indexes and digests after render-related changes.
4. Run validation before any promote logic.
5. Keep promote non-destructive:

• preview managed-path diffs first
• apply only after explicit approval
• never replace whole roots when a scoped diff can be applied

Durable lifecycle rules

• Normalize durable memory items to the shared envelope described in schemas/memory-v2.md.
• Reject exact active duplicates instead of endlessly appending them.
• When a new active item overlaps an old active item in the same scope, mark the old item as superseded and carry the provenance forward.
• Preserve evidence/source fields instead of silently collapsing history.
• Use valid_to and status to filter historical records out of default retrieval.

Retrieval rules

• Query sidecars first.
• Apply rule-based boosts second.
• Expand relations third when the task benefits from neighboring context.
• Filter inactive or expired records by default unless the task explicitly needs history.
• Treat digests as operator summaries, not as the authoritative source.

Output / validation checklist

Before finishing, verify:

• manifest contract fields are complete and consistent
• shared source contains no absolute host paths
• local-only subtrees are preserved across render/promote
• sidecar rebuild succeeds
• promote defaults to dry-run preview
• compatibility wrappers still work if they existed before

Learning maintenance

Maintain [references/learning-log.md](references/learning-log.md) for this skill.

Record:

• durable rules about memory lifecycle and retrieval
• approved workflow promotions for reusable memory maintenance flows
• avoided paths such as destructive rewrite patterns or non-portable storage choices

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sexymonk
• Source: sexymonk/agent-capability-core
• License: MIT

Install and usage instructions live in the source repository linked above.