Skip to content

waittim/MemoryCustodian / skills/memory-custodian

memory-custodian

Flagged

Use 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.

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.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall