Background Agents

Autonomous

Intelligent background processes that maintain, optimize, and improve your AI memory automatically

What Are Background Agents?

Think of them as Redis background processes for AI memory

Background agents are autonomous processes that run on configurable intervals to maintain your memory system. They handle cleanup, consolidation, triage, graph maintenance, and context optimization without any manual intervention.

Scheduler→Agent→Memory DB→Optimized

6 Built-in Agents

Cleanup Agent

Every 24h

Removes stale data, expired entries, and orphaned records. Keeps your memory database lean.

Consolidator Agent

Every 12h

Merges duplicate or near-duplicate memories. Requires AI provider for semantic comparison.

Triage Agent

Every 6h

Categorizes untagged memories and assigns priority levels. Requires AI provider.

Graph Maintenance Agent

Every 24h

Validates relationship integrity, removes broken links, and optimizes graph traversal paths.

Context Optimizer Agent

Every 12h

Recomputes embeddings, updates search indexes, and optimizes retrieval performance.

Learning Agent

Every 6h

Extracts cross-session patterns from observations. Auto-creates memories from insights.

Check Agent Status

Monitor agent health via REST API or MCP

REST API

# Get status of all agents
curl http://localhost:7777/api/v1/agents/status \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Response:
# {
#   "agents": {
#     "cleanup": { "status": "idle", "last_run": "2026-02-07T10:00:00Z", "next_run": "2026-02-08T10:00:00Z" },
#     "consolidator": { "status": "running", "last_run": "2026-02-07T04:00:00Z" },
#     ...
#   }
# }

MCP Tool

ace_agent_status()
// Returns status of all background agents

Trigger Agents Manually

Run any agent on-demand

REST API

# Trigger cleanup agent
curl -X POST http://localhost:7777/api/v1/agents/cleanup/run \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Trigger consolidator agent
curl -X POST http://localhost:7777/api/v1/agents/consolidator/run \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

MCP Tool

ace_trigger_agent({ agent_name: "cleanup" })
// Triggers immediate execution of the specified agent

Agent Run History

Review past agent executions and results

# View last 10 runs for cleanup agent
curl "http://localhost:7777/api/v1/agents/cleanup/history?limit=10" \
  -H "Authorization: Bearer $ACE_JWT_TOKEN"

# Response:
# {
#   "runs": [
#     {
#       "id": 42,
#       "started_at": "2026-02-07T10:00:00Z",
#       "completed_at": "2026-02-07T10:00:05Z",
#       "status": "completed",
#       "items_processed": 15,
#       "items_affected": 3
#     }
#   ]
# }

Agent Requirements

Agent	Interval	AI Required	Description
Cleanup	24h	No	Remove stale/expired data
Consolidator	12h	Yes	Merge duplicate memories
Triage	6h	Yes	Categorize and prioritize
Graph Maintenance	24h	No	Validate relationships
Context Optimizer	12h	Yes	Optimize search indexes
Learning	6h	Yes	Extract patterns from observations

Best Practices

Configure an AI Provider

4 of 6 agents require AI for intelligent processing. Set up an API key in Dashboard → API Keys.

Monitor Agent History

Check agent history periodically to ensure they're running successfully and processing items.

Run Cleanup After Imports

After bulk data imports, trigger the cleanup and consolidator agents to optimize your memory store.