# Memory Maintenance

> Maintain manifest-driven shared/runtime memory frameworks that use file-backed shared source plus runtime working copies and SQLite sidecar indexes. Use when Codex needs to add or refactor memory families, validate/render/promote/query/compact memory stores, enforce shared-vs-local boundaries, or tune lifecycle rules such as dedupe, supersede, provenance, and temporal validity.

- **Type:** Skill
- **Install:** `agentstack add skill-sexymonk-agent-capability-core-memory-maintenance`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sexymonk](https://agentstack.voostack.com/s/sexymonk)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sexymonk](https://github.com/sexymonk)
- **Source:** https://github.com/sexymonk/agent-capability-core/tree/main/skills/memory-maintenance

## Install

```sh
agentstack add skill-sexymonk-agent-capability-core-memory-maintenance
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)
3. 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
4. Prefer the generic CLI in [memory_cli.py](../../scripts/memory_cli.py) over ad-hoc family scripts.
5. Keep old family entry points as thin wrappers when compatibility matters.
6. Rebuild indexes and digests after render-related changes.
7. Run validation before any promote logic.
8. 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](https://github.com/sexymonk)
- **Source:** [sexymonk/agent-capability-core](https://github.com/sexymonk/agent-capability-core)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sexymonk-agent-capability-core-memory-maintenance
- Seller: https://agentstack.voostack.com/s/sexymonk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.