Overview

contox_hygiene runs the Memory Hygiene Agent to analyze and propose cleanup actions for memory items. The agent identifies issues like duplicate entries, outdated information, poor titles, missing tags, exposed secrets, and quality problems.

The tool uses a two-phase workflow:

Analyze — Call without apply to get a HygienePlan with proposed actions
Apply — Call with apply and the plan to execute selected actions

The agent never auto-applies changes. Every action must be explicitly selected for application.

Parameters

Name	Type	Required	Default	Description
`mode`	enum	No	`"quick"`	Analysis mode: `"quick"` (20 most recent items) or `"weekly"` (all items updated in the last 7 days)
`schemaKeyPrefix`	string	No	—	Filter items by schemaKey prefix (e.g., `"root/bugs"`)
`apply`	string[]	No	—	Action IDs to apply from a previous plan. Omit to analyze only
`plan`	string	No	—	JSON-stringified HygienePlan from a previous analyze call. Required when applying
`dryRun`	boolean	No	—	If true, show what would be applied without executing

Action types

The hygiene agent can propose the following types of actions:

Action	Description
Rename	Improve a memory item's title for clarity
Retag	Add, remove, or update tags on a memory item
Merge	Combine duplicate or overlapping memory items
Deprecate	Mark superseded or outdated items as deprecated
Redact	Remove sensitive information (secrets, keys, passwords)
Flag quality	Flag items with quality issues for manual review

Return value

Analyze mode (no `apply`)

Returns a formatted report including:

Field	Description
`totalMemories`	Number of items analyzed
`actionsCount`	Number of proposed actions
`promptTokens`	Tokens used for analysis prompt
`completionTokens`	Tokens used for analysis response
`summary`	Human-readable summary of findings
`warnings`	Any warnings encountered during analysis
`actions`	Detailed list of proposed actions grouped by type

Each action includes:

Field	Type	Description
`actionId`	string	Unique action identifier
`type`	string	Action type (rename, retag, merge, deprecate, redact, flag)
`reason`	string	Why this action is proposed
`confidence`	number	Confidence score (0-1)
`requiresHumanApproval`	boolean	Whether human review is recommended before applying
`targetMemoryIds`	string[]	IDs of the memory items affected

Apply mode (with `apply`)

Returns:

Field	Type	Description
`appliedActionIds`	string[]	IDs of successfully applied actions
`skippedActionIds`	string[]	IDs of skipped actions
`errors`	array	Errors encountered during application

Usage examples

Phase 1: Analyze memory

User: Check my memory for cleanup opportunities

Claude calls: contox_hygiene({ mode: "quick" })

Response:
Memory Hygiene Report (quick mode)
────────────────────────────────────
Items analyzed: 20
Actions proposed: 4
Tokens: 1200+350

3 items could benefit from improved titles. 1 potential duplicate found.

rename (2)
  - Title "stuff" is too vague, should be "JWT Token Rotation Implementation" (confidence: 0.92)
    id: action_abc | targets: mem_123
  - Title "fix" should be "Fix Session Refresh Race Condition" (confidence: 0.88)
    id: action_def | targets: mem_456

merge (1)
  - Two entries about auth middleware can be combined (confidence: 0.85) [NEEDS APPROVAL]
    id: action_ghi | targets: mem_789, mem_012

deprecate (1)
  - "Old migration notes" superseded by updated schema docs (confidence: 0.90)
    id: action_jkl | targets: mem_345

To apply actions, call contox_hygiene with:
  apply: [actionId1, actionId2, ...]
  plan: '<full JSON plan>'

Phase 2: Apply selected actions

User: Apply the renames and the deprecation, but skip the merge

Claude calls: contox_hygiene({
  apply: ["action_abc", "action_def", "action_jkl"],
  plan: "<JSON from previous response>"
})

Response:
Hygiene Apply Result:
- Applied: 3
- Skipped: 0
- Errors: 0

Dry run before applying

Claude calls: contox_hygiene({
  apply: ["action_abc"],
  plan: "<JSON>",
  dryRun: true
})

Response:
Hygiene Apply (DRY RUN) Result:
- Applied: 1
- Skipped: 0
- Errors: 0

Filtering by area

Claude calls: contox_hygiene({
  mode: "weekly",
  schemaKeyPrefix: "root/bugs"
})

Notes

The plan parameter is required when using apply. It must be the full JSON-stringified HygienePlan from the analyze phase.
Actions with requiresHumanApproval: true are flagged for manual review. They can still be applied programmatically, but the flag indicates the AI recommends human oversight.
The quick mode analyzes only the 20 most recent items, making it fast and low-cost. The weekly mode is more thorough but processes more data.
Use schemaKeyPrefix to focus the analysis on a specific area of the brain (e.g., only bugs, only implementation log).
The dryRun option in apply mode shows what would be changed without actually modifying any data.

contox_context_pack

Overview

On this page