Cognition

Cognition jobs are background processes that run separately from the interactive user-reply loop. While the agent responds to your messages in real time, cognition jobs work asynchronously: reviewing past turns, consolidating working memory, and extracting facts into semantic memory.

Why background jobs?

The interactive model needs to respond quickly. But some tasks benefit from a different model, more thinking time, or batch processing across multiple turns:

• Verification review needs careful reasoning about whether the agent’s work was correct.
• Working memory consolidation needs to summarize many turns into a compact state.
• Semantic memory extraction needs to identify durable facts worth keeping long-term.

Running these in the interactive loop would make every response slower. Running them as background jobs lets each use the right model for the task, on its own schedule.

The three jobs

Verification review

After every turn, the verification review job checks the agent’s work against the available evidence. It reads the turn transcript, inspects file changes and command outputs, and produces a structured review:

• Verdict — pass, fail, or partial.
• Evidence — what was checked and what was found.
• Issues — specific problems, if any.

The review is written to /memory/cognition/state/verification_review.md. The agent can reference past reviews to avoid repeating mistakes.

This job runs on nemotron-3-ultra by default — a model optimized for careful verification rather than creative generation.

Working memory consolidation

Working memory tracks active tasks, open threads, and recent progress. But it grows with every turn. The consolidation job periodically compacts it:

• Removes completed and stale entries.
• Merges related threads.
• Preserves active tasks and open questions.
• Keeps the file under a manageable size for prompt injection.

Consolidation triggers when 6 or more turns have accumulated since the last consolidation. The job runs on deepseek-v4-flash by default — fast and cheap for a mechanical summarization task.

The consolidated output is written back to /memory/working/WORKING_MEMORY.md.

Semantic memory extraction

Semantic memory stores durable facts, user preferences, and project knowledge. The extraction job scans recent turns for information worth keeping long-term:

• Facts — confirmed information and grounded inferences.
• Preferences — user preferences and collaboration preferences.
• Projects — active projects and durable project knowledge.

Extraction runs on deepseek-v4-pro by default — strong reasoning helps distinguish durable facts from transient conversation.

Output is written to /memory/semantic/facts.md, /memory/semantic/preferences.md, and /memory/semantic/projects.md.

Trigger model

Jobs are triggered by three mechanisms:

Trigger	When	Example
Startup	Once when the agent starts	Rebuild skill catalog
Schedule	On a cron-like interval	Periodic memory consolidation
State	When a condition is met	6+ turns since last consolidation

The controller evaluates triggers after each turn and launches jobs that are due. Only one instance of a job runs at a time — if a job is already running, new triggers are skipped.

Model assignment

Each cognition job can use a different model than the interactive conversation. This is configured in the agent config:

agent:
  models:
    - deepseek-v4-flash    # interactive fallback order
    - deepseek-v4-pro
  cognition:
    models:
      - deepseek-v4-pro    # cognition fallback order
      - deepseek-v4-flash

Individual jobs can override the cognition model list. For example, to run verification review on a specific model:

switch_cognition_model(
  job_type: "verification_review",
  provider: "ollama-cloud",
  model: "nemotron-3-ultra"
)

When a job has no override, it inherits from agent.cognition.models. When that is also unset, it inherits from agent.models.

Run records

Every cognition run is recorded under /memory/cognition/runs/YYYY/MM/DD/ as a JSON file. Each record includes:

• Job type and trigger cause (startup, schedule, or state).
• Model used and provider.
• Start time, end time, and duration.
• Outcome (success, failure, or skipped).
• Summary of changes made.

Run records provide an audit trail: you can see when each job ran, what triggered it, and what it did.

Directory structure

/memory/cognition/
├── state/
│   └── verification_review.md    # latest review output
├── runs/
│   └── YYYY/MM/DD/
│       └── <job>-<timestamp>.json
└── jobs/                         # per-job persisted state

Relationship to memory

Cognition jobs are the mechanism that maintains memory. The memory system is the what — the files and collections that store information. Cognition is the how — the background processes that update those files.

See Memory for the full memory architecture.