waittim/MemoryCustodian / skills/memory-custodian
memory-custodian
FlaggedUse when a project contains docs/memory/, or when the user asks to remember, retrieve, update, compact, forget, or audit project memory. MemoryCustodian manages local plain-text project memory with minimal context loading.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.6 KB |
| references/admission-policy.md | markdown | 1.1 KB |
| references/compaction-policy.md | markdown | 4.2 KB |
| references/examples.md | markdown | 2.1 KB |
| references/forgetting-policy.md | markdown | 6.9 KB |
| references/local-overlay-policy.md | markdown | 1.5 KB |
| references/manifest-policy.md | markdown | 2.9 KB |
| references/memory-file-protocol.md | markdown | 22.3 KB |
| references/migration-policy.md | markdown | 2.7 KB |
| references/output-contract.md | markdown | 4.3 KB |
| references/platform-adapters.md | markdown | 3.9 KB |
| references/quality-audit.md | markdown | 15.4 KB |
| references/routing-policy.md | markdown | 2.0 KB |
| references/transaction-policy.md | markdown | 4.1 KB |
references/compaction-policy.md
View on GitHub# Compaction Policy
Compaction reduces context bloat while preserving durable project memory.
## When To Compact
Compact when:
- `inbox.md` has more than 30 items.
- `brief.md` exceeds its budget.
- Any active memory file exceeds its context budget.
- The same fact appears in multiple files.
- A decision or constraint has stabilized.
- A user asks to summarize or tidy memory.
## Compaction Inputs
Follow the project manifest's memory-maintenance route, then read only the candidates and potential destinations needed for review.
Do not read `archive/` unless the user asks.
## Destination Rules
- Confirmed architecture choices -> `decisions.md`
- Hard requirements -> `constraints.md`
- User style or workflow preferences -> `preferences.md`
- Rejected paths and tombstones -> `do-not-use.md`
- Task-specific rules -> `rules/*.md`
- Workflow-specific rules -> `profiles/*.md`
- Current one-screen summary -> `brief.md`
- Unclear or temporary notes -> keep in `inbox.md`
## Safety Rules
- Do not erase uncertain information silently.
- Do not resurrect topics listed in `do-not-use.md`.
- Preserve the decision, not the full conversation.
- Preserve Subject IDs, Facets, Evidence, and supersede relationships when semantically rewriting entries.
- Shorten entries over 120 tokens semantically before archiving other decisions; never truncate mechanically.
- Prefer short bullets over narrative history.
- Keep tombstones active; do not archive `do-not-use.md` entries merely to meet a budget.
- Before archiving decisions, merge superseded entries and move subsystem-specific knowledge to matched `areas/*.md`.
- Preserve every active invariant in normal task-loading paths; archive only historical rationale or inactive entries.
- Archive only complete old entries, and only when the active file remains coherent and sufficient without them.
- Record a short maintenance note in `changelog.md` if it is enabled.
## CLI Behavior
The CLI MUST NOT classify inbox entries by keywords or infer semantic destinations. It MAY report budgets and candidates, remove exact duplicate top-level bullet units, and filter exact tombstone matches. A top-level bullet unit includes all of its continuation and nested lines; exact comparison and removal operate on that complete unit, never on a nested bullet or continuation line independently. All other candidates remain in the inbox until an Agent or user reviews their scope, type, confidence, and overlap with existing memory.
Use `memory-custodian compact` to generate the candidate report and Plan ID. After review, edit the destination
Markdown directly or call `add`, then run `check`. Under Protocol 0.8, use
`memory-custodian compact --apply --confirm-plan <PLAN_ID>` only to apply the exact mechanical inbox cleanup shown
in the preview; it does not promote candidates or remove them merely because they were reported.
Protocol 0.8 applies every multi-file compaction through the shared
transaction journal. An interrupted apply is recovery-required and MUST be
reported by `audit --transactions`; never treat a cleaned private backup as
archive content or as proof of complete erasure.
At `NEAR LIMIT` (80%–100%) or `OVER BUDGET`, use `memory-custodian compact --target decisions.md` first.
`add` emits a deterministic dry-run maintenance preview when a write reaches either state, but never applies
semantic changes. With `--target`, the CLI reports the current budget state and applies only conservative
deterministic changes: exact duplicate complete top-level bullet-unit removal for simple bullet files, or older
complete H2 entry archival for supported history-like files such as `decisions.md` and `changelog.md`.
Archive files have one canonical file-level explanation. Repeated same-day compaction MUST NOT append duplicate
batch wrappers; changelog entries with the same date are grouped under one heading and remain newest-first.
Decision archival has an explicit semantic gate. First shorten long entries, consolidate, supersede, and relocate scoped knowledge; then review the dry run. The CLI blocks age-based archival while kept decisions remain over the per-entry guide. Use `--apply --archive-oldest` only when the proposed oldest entries contain no active invariant that would become unreachable. Changelog archival does not require this extra confirmation.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |