Skip to main content
Version: 0.6.3

Cognition Tier — overview

ClaudusBridge 0.6.x ships a dedicated Cognition surface: a group of MCP tools that let agents reason about their own work over time, not just execute one tool call after another. Where the rest of the plugin gives the agent hands and eyes, the Cognition tier gives it a journal and a planner.

If you're connecting a fresh AI session and want to know "what did the last engineer do here?", "did anything break recently?", "did we save enough state to roll back from a risky change?", "which tool calls are silently failing?" — these are Cognition questions.

This page is the index. Each capability has its own deep-dive guide.

What's in the Cognition tier​

CapabilityToolsPersistenceGuide
Workflow checkpointsclaudus_checkpoint_workflow, claudus_list_workflow_checkpointsSaved/ClaudusBridge/WorkflowCheckpoints/<id>.jsonWorkflow Checkpoints
Auto-observationsclaudus_recall_observations (recall side) — observations fire automatically from ExecuteNativeAction, UpdateMultiAgentWorkflow, CheckpointWorkflow, the ai_create success pathSaved/ClaudusBridge/claudus_memory.jsonl (ring buffer, default 256 entries)Auto-Observations
Multi-agent workflowsclaudus_start_multi_agent_workflow, claudus_get_multi_agent_workflow, claudus_list_multi_agent_workflows, claudus_update_multi_agent_workflow, claudus_cancel_multi_agent_workflow, claudus_workflow_timelineSaved/ClaudusBridge/MultiAgentWorkflows/<id>.jsonMulti-Agent Workflows
Workflow templates + smart startclaudus_list_workflow_templates, claudus_instantiate_workflow_template, claudus_smart_startSame as multi-agent workflows(covered in Multi-Agent Workflows)
Continuation-batch savingsclaudus_continuation_statsStateless (reads internal counters)(covered below)
Provider auth visibilityclaudus_get_last_auth_stateReads <installRoot>/last-auth-state.json written by the Node runtime(covered below)
Task plansclaudus_create_task_plan, claudus_list_task_plans, claudus_get_task_plan, claudus_update_task_planSaved/ClaudusBridge/TaskPlans/<id>.json(covered in Multi-Agent Workflows)
Native tool / skill authoringclaudus_request_native_tool_authoring, claudus_request_self_programming, claudus_create_skillAction queue + scoped plugin file tools(out of scope for this page — see the auto-generated CLAUDUS_AI_SKILL.md)

Self-healing provider pipeline (dispatch.json mtime detection + connect-error retry) is infrastructure for the Cognition tier rather than part of it — see Self-Healing Provider.

How the pieces fit together​

Two complementary loops:

1. Audit loop (what happened?)​

agent does work
  ↓
ExecuteNativeAction routes the call
  ↓
on success-with-mutation → AutoObserve(asset_created, kind:<sub-action>, path:<asset_path>)
on workflow completion  → AutoObserve(workflow_completed, workflow_id:<id>, mode:<mode>, lead:<lead>)
on workflow checkpoint  → AutoObserve(workflow_checkpoint, workflow_id:<id>, checkpoint_id:<id>)
on tool failure         → AutoObserve(action_failed, tool:<name>, severity:<high|low>, [kind:unknown_command])
  ↓
ring buffer at Saved/ClaudusBridge/claudus_memory.jsonl
  ↓
next session reads it via claudus_recall_observations(tag=…, since_hours=…, contains=…, limit=…)

Nothing in this loop requires the agent to call a tool. The hooks fire from the dispatch path itself. The next session sees the audit trail for free.

2. Snapshot loop (what state did we have?)​

agent reaches a milestone
  ↓
claudus_checkpoint_workflow(workflow_id, label?, asset_paths|scan_paths?)
  ↓
Saved/ClaudusBridge/WorkflowCheckpoints/<id>.json
  ↓
later: claudus_list_workflow_checkpoints(workflow_id?) → inventory
  ↓
later: read the JSON directly to diff what changed (rollback is intentionally out of scope in v1)

This loop is opt-in. Call claudus_checkpoint_workflow before any risky change you might want to walk back from, and the journal records the snapshot point automatically via the audit loop.

Continuation-batch savings telemetry​

The async continuation pipeline batches multiple action results that land inside ~500 ms into a single provider continuation. Two counters accumulate:

  • AutoContinuationFiredCount — provider continuations that actually went out
  • AutoContinuationBatchedCount — results that fell inside the debounce window after a recently-fired continuation; their chat-log entries still reach the provider via context, no info is lost
cb call claudus_continuation_stats

Returns:

{
  "continuations_fired": 4,
  "continuations_batched": 7,
  "total_action_continuations": 11,
  "batch_rate": 0.636,
  "batch_window_ms": 500,
  "assumed_inference_ms_per_skipped_continuation": 1500,
  "estimated_saved_inference_ms": 10500,
  "notes": "..."
}

Multiply continuations_batched by your observed average inference time for a sharper saved-ms number. The default 1500 ms reflects the typical Opus 4.7 / Sonnet 4.6 round-trip latency.

Provider auth visibility​

The Node provider runtime writes a sanitized last-auth-state.json to &lt;LOCALAPPDATA&gt;/ClaudusBridge/ProviderRuntime/ at startup, every 5 min, and on shutdown. It records presence + last-modified timestamp for each provider credential file (Claude .credentials.json, ChatGPT ~/.codex/auth.json, Gemini ~/.gemini/oauth_creds.json) — never token values.

cb call claudus_get_last_auth_state

Returns the raw snapshot plus a coarse verdict:

VerdictMeaning
okClaude credentials are present (the canonical default)
anthropic_missing_but_alt_presentNo Claude creds but ChatGPT or Gemini are available — log in to Claude if you want the default model
needs_loginNo provider creds at all — agent_login from any compatible client to bootstrap

This is the observability layer. Token persistence itself stays with the upstream provider tooling (CCAG owns Claude/ChatGPT, the Gemini CLI owns Gemini). The plugin never reads or stores tokens.

Recall is the entry point for a fresh session​

Most agents connecting to a project for the first time should run two cheap reads before any structural inspection:

cb call claudus_get_project_intelligence        # baseline: asset summary, naming patterns, risks, recommendations
cb call claudus_recall_observations '{"since_hours": 168, "limit": 50}'

The first gives a snapshot of the project shape. The second gives the journal of what recent sessions did, created, completed, and broke. With those two reads (a few hundred tokens total) the agent knows where it walked into instead of re-scanning the asset registry call by call.

Where to go next​