MemoryCustodian

1) Install MemoryCustodian (choose the path that matches your agent/workflow): Pick one install method: - Ask your coding agent to install the skill from the repo: https://github.com/waittim/MemoryCustodian - Codex (local marketplace): run `codex plugin marketplace add .` from a checkout, then `codex plugin add memory-custodian@memory-custodian-dev`. - Claude Code (plugin): for local testing run `claude --plugin-dir .`, or install to personal skills with `./install.sh claude`. - Gemini-style agents: install with `./install.sh gemini` or `gemini skills link ./skills/memory-custodian`. - CLI/source checkout: run from repo via `scripts/memory-custodian ...` or install editable with `python3 -m pip install -e .` to get the `memory-custodian` command.

2) Initialize MemoryCustodian in a project (one-time per repo): Run initialization once for each target project: - If installed as a console script: `memory-custodian init --project-root /path/to/project --agent all` - From a source checkout: `scripts/memory-custodian init --project-root /path/to/project --agent all` Use `--agent codex`, `--agent claude`, `--agent gemini`, or `--agent all` to generate the thin bootstrap file(s) your agent reads.

3) Understand what initialization creates (where memory lives): Initialization creates the default durable memory set under `docs/memory/`: - `manifest.md` (routes what to load) - `brief.md` (current project shape) - `decisions.md` (key decisions) - `constraints.md` (hard requirements) - `do-not-use.md` (rejected paths / tombstones) - `inbox.md` (staging area) Platform bootstrap files (e.g., `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`) stay thin and point agents to `docs/memory/`.

4) Curate the generated brief before relying on it: After `init`, `brief.md` starts as a scaffold with TODOs. Fill it from authoritative project sources (README, code, docs) before treating memory as ready. Use `memory-custodian status --project-root /path/to/project` (or `scripts/memory-custodian status ...`) to see whether the brief is still uncurated; `status` and `check` report an uncurated brief.

5) Load the right memory for a task (manifest-first reading): The intended workflow for agents is: 1) Read `docs/memory/manifest.md`. 2) Read `docs/memory/brief.md`. 3) Load only the task-relevant files named by the manifest. For manual inspection, generate a context pack with: - `memory-custodian read --project-root /path/to/project --task planning` - `memory-custodian read --project-root /path/to/project --task implementation` - `memory-custodian read --project-root /path/to/project --task artifact`

6) Add durable memory when something should survive the current chat: Record decisions/constraints/preferences/rejected approaches using the CLI: - `memory-custodian add "We chose manifest-first loading." --type decision` - `memory-custodian add "Persist sync retry backoff." --type decision --area sync --reason "Keep retries bounded across launches."` Keep decision entries short (the tool enforces a token guide and rejects overlong writes unless you explicitly allow long entries).

7) Enable optional memory modules only when they become relevant: Optional modules (e.g., rules, profiles, areas) are opt-in and not loaded unless enabled and routed by the manifest. Enable them as needed: - `memory-custodian enable preferences` - `memory-custodian enable rules/output` - `memory-custodian enable profile/git` - `memory-custodian enable area/frontend` Enabling never overwrites an existing module file.

8) Use 'do-not-use' to preserve rejected approaches and avoid regressions: When you intentionally reject an approach (e.g., a storage backend or architecture), record it in `docs/memory/do-not-use.md` (via edits or the appropriate add/forget workflow) so future sessions don’t re-propose it.

9) Check health and protocol compatibility regularly: Run deterministic validation to ensure structure, budgets, and protocol metadata are correct: - `memory-custodian check --project-root /path/to/project` Use `memory-custodian status` for a quick overview and to detect an uncurated brief.

10) Compact and maintain memory (preview-first, safe mutations): Use maintenance commands to keep memory small and current: - `memory-custodian compact --project-root /path/to/project` Compaction is guarded and preview-first; apply changes only after reviewing the plan. Inbox compaction is conservative (e.g., exact duplicate top-level bullet-unit removal and tombstone filtering) and expects an agent/human to do semantic promotion into decisions/constraints.

11) Forget outdated information safely (preview-first): Remove or redact outdated topics with preview-first forgetting: - Preview: `memory-custodian forget "old deployment note" --mode soft --project-root /path/to/project` - Apply after review: `memory-custodian forget "old deployment note" --mode soft --apply --project-root /path/to/project` Broad matches require explicit confirmation (e.g., `--allow-broad-match`). Some cases require manual rewrite; the tool will refuse unsafe wholesale deletions.

12) Repair or replace an existing setup when needed: If files are missing or metadata needs updating without overwriting curated content: - Repair: `memory-custodian init --project-root /path/to/project --repair` If you intentionally want a full replacement, use preview-first replacement and only apply when correct: - `memory-custodian init --project-root /path/to/project --replace-existing` - then add `--apply` only if the listed files should be replaced.

13) Migrate protocol/project memory versions when the tool updates: When `check` reports old or missing protocol metadata, migrate the project manifest offline: - Preview: `memory-custodian migrate --project-root /path/to/project` - Apply after review: `memory-custodian migrate --apply --project-root /path/to/project`

14) Use the right invocation on Windows vs. source checkout: On Windows, install the console command and use `memory-custodian ...`. From a repo checkout on any platform, you can run `scripts/memory-custodian ...` as the wrapper.