contox hygiene
Run the Memory Hygiene Agent to analyze and clean up memory items. This command uses a two-phase workflow: first analyze to get a plan, then selectively apply the proposed changes.
Usage
bash
contox hygiene [options]
Options
| Flag | Description | Required | Default |
|---|---|---|---|
--mode <mode> | Analysis mode | No | quick |
--schema-key <prefix> | Filter items by schema key prefix | No | -- |
--json | Output in JSON format | No | false |
--apply <file> | Apply actions from a previously saved plan file | No | -- |
--action-ids <ids> | Comma-separated list of action IDs to apply | No | -- |
--dry-run | Show what would be applied without executing | No | false |
Modes
| Mode | Description |
|---|---|
quick | Analyze the 20 most recent items (fast, low cost) |
weekly | Analyze all items updated in the last 7 days |
Two-phase workflow
The hygiene command is designed to be safe and transparent. Changes are never auto-applied.
Phase 1: Analyze
Run the hygiene agent to get a plan of proposed actions:
bash
contox hygiene
This outputs a list of proposed actions, each with:
- A unique action ID
- Description of what the action would do
- Confidence score (0 to 1)
- Whether human approval is required
Phase 2: Apply
Review the proposed actions and apply the ones you approve:
bash
contox hygiene --apply plan.json --action-ids "action1,action2,action3"
Examples
Quick analysis of recent items:
bash
contox hygiene
Weekly analysis of all recent changes:
bash
contox hygiene --mode weekly
Analyze only bug-related items:
bash
contox hygiene --schema-key root/bugs
Preview what would be applied:
bash
contox hygiene --apply plan.json --action-ids "act_1,act_2" --dry-run
Get JSON output for scripting:
bash
contox hygiene --json
What it proposes
The hygiene agent can propose the following types of actions:
| Action type | Description |
|---|---|
| Rename | Fix unclear or inconsistent titles |
| Retag | Update tags for better categorization |
| Merge | Combine duplicate or overlapping items |
| Deprecate | Mark superseded or stale items as deprecated |
| Flag | Highlight quality issues for manual review |
| Redact | Remove accidentally stored secrets or sensitive data |
Notes
- The hygiene agent never auto-applies changes. You always review and choose which actions to execute.
- Each proposed action includes a confidence score. Higher confidence means the agent is more certain the action is correct.
- Actions with
requiresHumanApproval: trueshould be carefully reviewed before applying, as they involve potentially significant changes. - Run hygiene regularly (weekly is recommended) to keep your project brain clean and well-organized.
- The
--dry-runflag on the apply phase shows what would happen without making any changes, giving you an extra safety layer.