Endpoint

POST /api/v2/hygiene

The hygiene endpoint runs an AI-powered agent that analyzes memory items and proposes cleanup actions. It operates in a safe two-phase workflow: first analyze, then apply selected actions.

Authentication

Supports Bearer token or session cookie authentication.

Request body

Field	Type	Required	Description
`projectId`	string	Yes	The project ID
`action`	string	Yes	`"analyze"` or `"apply"`
`mode`	string	No	`"quick"` (20 items) or `"weekly"` (200 items). Default: `"quick"`
`selectedActionIds`	array	Conditional	Required when `action` is `"apply"`. Array of action IDs to execute
`plan`	object	Conditional	Required when `action` is `"apply"`. The plan object from the analyze phase

Phase 1: Analyze

Request the hygiene agent to analyze items and propose actions:

bash

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"
  }'

Analysis response

json

{
  "planId": "plan_abc123",
  "itemsAnalyzed": 20,
  "actions": [
    {
      "id": "act_001",
      "type": "RENAME_TITLE",
      "itemId": "item_abc123",
      "description": "Rename 'auth stuff' to 'JWT Authentication Middleware'",
      "confidence": 0.92,
      "requiresHumanApproval": false,
      "before": "auth stuff",
      "after": "JWT Authentication Middleware"
    },
    {
      "id": "act_002",
      "type": "MERGE_MEMORIES",
      "itemIds": ["item_def456", "item_ghi789"],
      "description": "Merge duplicate items about database connection pooling",
      "confidence": 0.85,
      "requiresHumanApproval": true
    },
    {
      "id": "act_003",
      "type": "DEPRECATE_MEMORY",
      "itemId": "item_jkl012",
      "description": "Deprecate outdated reference to Express.js (project uses Hono)",
      "confidence": 0.88,
      "requiresHumanApproval": false
    }
  ]
}

Action types

Action	Description
`RENAME_TITLE`	Improve the title of a memory item for clarity
`RETAG`	Update the type or schema key of an item
`MERGE_MEMORIES`	Combine duplicate or overlapping items
`DEPRECATE_MEMORY`	Mark an outdated item as deprecated
`REDACT`	Remove potentially sensitive information
`FLAG_QUALITY`	Flag an item for manual review

Phase 2: Apply

After reviewing the proposed actions, apply the ones you approve:

bash

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": { ... }
  }'

Apply response

json

{
  "applied": 2,
  "skipped": 1,
  "results": [
    { "actionId": "act_001", "status": "success" },
    { "actionId": "act_003", "status": "success" }
  ]
}

Safety guarantees

The hygiene agent is designed with safety as a priority:

Never auto-applies -- All actions must be explicitly approved
Confidence scores -- Each action includes a confidence score to help prioritize review
Human approval flag -- Actions with requiresHumanApproval: true indicate higher risk and should be reviewed carefully
Reversible -- Deprecated items can be re-approved; merged items retain source references

Modes

Mode	Items analyzed	Use case
`quick`	20 most recent	Daily maintenance
`weekly`	Up to 200 items	Periodic deep cleanup

Next steps

Hygiene Agent Guide -- In-depth guide to using the hygiene agent
V2 Items -- Manage memory items directly
Dashboard Memory -- Review items in the UI

V2 Items

V2 Ask

On this page