Overview

The hygiene agent is an AI-powered tool that analyzes your project's memory items and proposes cleanup actions. It helps maintain a high-quality brain by identifying duplicates, outdated items, poorly titled entries, and other issues. The agent operates with a strict two-phase workflow to ensure safety.

Two-phase workflow

The hygiene agent never makes changes automatically. It always follows a two-phase approach:

Phase 1: Analyze

The agent reviews memory items and generates a plan of proposed actions. Each action includes a description, confidence score, and human approval flag.

Phase 2: Apply

You review the proposed actions, select the ones you approve, and apply them. Only the selected actions are executed.

This design ensures you always have full control over changes to your project memory.

Modes

Action types

The hygiene agent can propose the following actions:

RENAME_TITLE

Improves the title of a memory item for clarity and consistency.

Before: "auth stuff" After: "JWT Authentication Middleware Pattern"

RETAG

Updates the type or schema key of an item that has been miscategorized.

Example: Moving an item from root/implementation to root/architecture because it describes a pattern, not a specific feature.

MERGE_MEMORIES

Combines two or more duplicate or overlapping items into a single, comprehensive item. The merged item retains the best content from each source.

Example: Two items about "database connection pooling" with different details merged into one complete entry.

DEPRECATE_MEMORY

Marks an outdated item as deprecated. Deprecated items are removed from the brain but not permanently deleted.

Example: An item referencing Express.js when the project has since migrated to Hono.

REDACT

Removes potentially sensitive information from an item, such as API keys, passwords, or internal URLs that should not be in the memory.

FLAG_QUALITY

Flags an item for manual review without proposing a specific change. Used when the agent detects a potential issue but is not confident enough to propose a fix.

Safety guarantees

The hygiene agent is designed with safety as the top priority:

• Never auto-applies -- All actions require explicit approval before execution
• Confidence scores -- Each action includes a score (0-1) indicating the agent's confidence
• Human approval flag -- Actions marked requiresHumanApproval: true indicate higher risk and should be reviewed more carefully
• Reversible -- Deprecated items can be re-approved; merged items retain source references
• Audit trail -- All applied actions are logged in the operations history

Using the hygiene agent

In the Dashboard

1. Open the Memory page and switch to the Hygiene tab
2. Select the mode: Quick (20 recent items) or Weekly (last 7 days of items)
3. Click Run Analysis — the agent processes your items and generates a plan
4. Review the proposed actions. Each action shows:
   • Type — What kind of change (rename, merge, deprecate, etc.)
   • Target items — Which memory items are affected
   • Confidence score — How confident the agent is (0--1)
   • Human approval flag — Whether manual review is strongly recommended
5. Check the boxes next to the actions you want to apply
6. Click Apply Selected — only the selected actions are executed

Via the API

# Phase 1: Analyze
curl -X POST https://contox.dev/api/v2/hygiene \
  -H "Authorization: Bearer contox_sk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "proj_abc123", "action": "analyze", "mode": "quick"}'

# Phase 2: Apply selected actions
curl -X POST https://contox.dev/api/v2/hygiene \
  -H "Authorization: Bearer contox_sk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "action": "apply",
    "selectedActionIds": ["act_001", "act_003"],
    "plan": { ... }
  }'

Via MCP

Use the contox_hygiene tool in your MCP session:

contox_hygiene(mode: "quick")

Review the proposed actions and apply the selected ones.

Best practices

• Run quick mode regularly -- A quick analysis after every few sessions keeps memory tidy
• Run weekly mode on weekends -- A deeper pass catches issues that accumulate over time
• Review merge actions carefully -- Merges combine content from multiple items, so verify the result makes sense
• Trust high-confidence actions -- Actions with confidence above 0.9 are almost always correct
• Check flagged items -- Items flagged for quality review often reveal genuine issues

Next steps

• V2 Hygiene API -- API reference for the hygiene endpoint
• Memory Dashboard -- Manage items in the UI
• Best Practices -- General Contox best practices