KYBERNESIS
DOCUMENTATION
ACCESS_CONSOLE

Sleep Agent

Learn how Kybernesis automatically organizes, connects, and optimizes your memories in the background.

Table of Contents

What is the Sleep Agent?

The Sleep Agent is an automated maintenance system that runs every hour to keep your memory system organized and optimized. Think of it as a personal librarian that:

  • Tags your memories automatically
  • Finds connections between related content
  • Moves rarely-used memories to cheaper storage
  • Keeps your most important memories fast and accessible

You don't need to configure anything—it works automatically in the background.

What It Does

1. Auto-Tagging

Analyzes untagged memories and generates relevant tags:

  • Topic tags: "authentication", "database", "security"
  • Entity tags: "PostgreSQL", "AWS", "React"
  • Action tags: "troubleshooting", "configuration"

What you'll see:

  • Auto-generated tags appear as gray badges in the topology UI
  • Your manual tags (emerald badges) are never overwritten
  • Combined tags are used for search and connections

2. Relationship Discovery

Finds connections between memories based on:

  • Shared tags and topics
  • Similar content
  • Common source (same document, same chat session)

What you'll see:

  • New lines connecting related nodes in the topology graph
  • "Related memories" section when viewing a memory
  • Better search results that include contextually relevant content

3. Storage Optimization

Automatically moves memories between three tiers:

Hot Tier - Fast, frequently accessed

  • Memories you've viewed in the last 3 days
  • High-priority content
  • Pinned memories

Warm Tier - Normal speed, occasional access

  • Viewed within 21 days
  • Content with manual tags
  • Moderately connected memories

Archive Tier - Slower, rarely accessed

  • Not viewed for 30+ days
  • Low priority, few connections
  • Automatically compressed to save space

What you'll see:

  • Tier badges on memory nodes (Hot/Warm/Archive)
  • Faster search for frequently-used content
  • Lower storage costs as your library grows

4. Summary Generation

Updates summaries for memories that change tiers:

  • Archive tier: 3-sentence summary
  • Warm tier: 5-sentence summary
  • Preserves key information while reducing storage

When It Runs

Schedule

  • Frequency: Every 60 minutes
  • Duration: 2-5 minutes per cycle
  • Processing: 50-200 memories per cycle (oldest/most-needed first)

What Happens During a Cycle

terminal
1. Collect candidates (memories needing attention)
2. Generate tags for untagged content
3. Find new relationships between memories
4. Optimize storage tiers
5. Update summaries

All steps are tracked so if a cycle is interrupted, the next one picks up where it left off.

Viewing Sleep History

Via Web Console

  1. Visit your console at https://kybernesis.ai
  2. Navigate to the Sleep tab
  3. View recent cycles with:
    • Run time and duration
    • Status (completed, failed, in progress)
    • Tasks completed
    • Detailed notes (e.g., "Tagged 12 memories, created 18 connections, moved 8 to archive")

Via API

Fetch sleep history programmatically:

terminal
GET /telemetry/sleep?orgId=YOUR_ORG_ID&limit=10

Response:

terminal
{
  "runs": [
    {
      "runId": "sleep_run_abc123",
      "status": "completed",
      "triggeredAt": "2025-10-24T10:00:00Z",
      "completedAt": "2025-10-24T10:03:45Z",
      "durationMs": 225000,
      "tasksCompleted": 127,
      "tasksFailed": 3,
      "notes": "Tagged 12 memories, created 18 relationships, moved 8 to archive"
    }
  ]
}

Manual Triggers

You can trigger a maintenance cycle manually instead of waiting for the hourly schedule.

Via Web Console

  1. Navigate to the Sleep tab
  2. Click "Run maintenance cycle" button
  3. Results appear in 2-5 minutes

Via API

terminal
POST /scheduler/run
Authorization: Bearer YOUR_API_KEY

Response:

terminal
{
  "status": "queued",
  "runId": "sleep_run_manual_xyz",
  "message": "Sleep job enqueued. Results available in 3-5 minutes."
}

When to Trigger Manually

Use manual triggers when:

  • You just uploaded many files and want immediate tagging
  • Before a demo or presentation to ensure everything is organized
  • After connecting a new app (Google Drive, Notion) to build relationships
  • Testing if the sleep agent is working correctly

Note: If a cycle is already running, the manual trigger will wait or skip to avoid conflicts.

Understanding Results

Health Indicators

Healthy Cycle:

  • Duration: 2-5 minutes
  • Tasks completed: 50-200
  • Status: Completed
  • Failures: 0-5 (less than 5%)

Issues:

  • Duration: >10 minutes
  • Status: Failed
  • Failures: >20 (more than 10%)

Common Results

"Tagged X memories"

  • New auto-tags were generated for untagged content
  • These appear as gray badges in the UI

"Created X relationships"

  • New connections were found between related memories
  • These appear as lines in the topology graph

"Moved X to archive"

  • Rarely-used memories were moved to cheaper storage
  • They're still searchable, just slightly slower to retrieve

"Promoted X to hot tier"

  • Frequently-accessed memories were moved to faster storage
  • These will appear in search results faster

Viewing Detailed Metrics

Each cycle shows:

  • Tasks completed/failed: Overall success rate
  • Duration: How long the cycle took
  • Notes: Detailed summary of what happened

Example:

terminal
Run ID: sleep_run_abc123
Status: ✅ Completed
Duration: 3min 45sec
Tasks: 127 completed, 3 failed
Notes: Tagged 12 memories, created 18 relationships,
       moved 8 to archive, promoted 3 to hot

Performance Impact

During a Cycle (2-5 minutes)

Minimal Impact:

  • Search: +5-10ms slower (usually unnoticeable)
  • Uploads: +10-20ms slower
  • Normal browsing: No impact

After a Cycle

Improvements:

  • Search quality: 15-25% better (more relevant results)
  • Storage costs: 10-30% lower (archive tier compression)
  • Graph connections: 5-10% more relationships discovered

System Impact

The sleep agent:

  • Runs in the background without blocking your work
  • Processes memories in small batches to avoid overload
  • Automatically adjusts if the system is busy
  • Retries failed tasks in the next cycle

Next Steps

Support