Auto-Observations

The auto-observation pipeline is the implicit journal that ClaudusBridge writes on the agent's behalf. Where the Memory System requires the agent to call memory_remember explicitly with a topic, the auto-observation pipeline fires from inside the dispatch path itself — every time an action succeeds with a side-effect, every time a workflow transitions to completed, every time a checkpoint is written, every time a tool call fails. The next session reads it via claudus_recall_observations without anything having to be remembered explicitly.

Think of it as the flight recorder sitting next to the engineer's notebook.

---

What gets recorded (and where)

All auto-observations land in a single append-only ring buffer:

Saved/ClaudusBridge/claudus_memory.jsonl

The buffer caps at 256 entries by default, oldest-evicted-first. Recall is keyed on tag prefix, time window, and substring match — not on the file directly. The JSONL file is the canonical raw log; the recall tool is the supported read API.

Trigger	Source string	Tags written
ai_create succeeded with a side-effect	asset-created	auto_observation, asset_created; optional kind:<sub-action> (e.g. kind:blueprint); optional path:<asset_path>
Multi-agent workflow transitioned to completed	workflow-completed	auto_observation, workflow_completed, <workflow_id>; optional mode:<mode>; optional lead:<lead>
claudus_checkpoint_workflow wrote a snapshot	workflow-checkpoint	auto_observation, workflow_checkpoint, <workflow_id>, <checkpoint_id>
Any tool call returned status != "success"	action-failed	auto_observation, action_failed, tool:<name>, severity:<high|low>; kind:unknown_command only when the failure message starts with "Unknown command:"

The agent does not have to call any tool to make these fire. They are wired into the dispatch path directly. The source field on the observation entry is set to the kebab-case string in the second column above, so you can filter by source in addition to tag content if needed.

---

The severity filter on action failures

Not every failed tool call is equally interesting. A typo on a read-only lookup is noise; a failed ai_create_blueprint is a real loss.

ClaudusBridge tags every action_failed entry with severity:high or severity:low:

Severity	Trigger
high	Tool name contains any of create_, write_, delete_, save_, modify_, rebuild_, set_, ai_create_, ai_modify_, ai_build_. These are mutation-prefixed tools — if they fail, asset state didn't change as the agent expected.
low	Everything else — read-only lookups, status queries, find_*, get_*, list_*, describe_*. Failure here just means "couldn't answer the question".

Special case: when the failure is Unknown command: <name>, the entry also gets kind:unknown_command. That's the highest-value signal — it tells the next session "this tool was attempted but didn't exist", which is the canonical input for claudus_request_native_tool_authoring (the self-improvement loop that authors a missing tool, rebuilds, and auto-retries).

---

Recall API

claudus_recall_observations accepts any subset of these filters:

Param	Type	Default	Effect
tag	string	(none)	Match observations whose tag list contains this exact string. Most common: action_failed, asset_created, workflow_completed, workflow_checkpoint
since_hours	number	0 (no time filter)	Drop entries older than now - since_hours
contains	string	(none)	Substring match on the entry's text field
limit	number	50	Hard cap on returned entries (newest first)

Examples:

# What's been created in the last day?
cb call claudus_recall_observations '{
  "tag":          "asset_created",
  "since_hours":  24
}'

# What broke recently — only mutations, not lookups?
cb call claudus_recall_observations '{
  "tag":          "action_failed",
  "since_hours":  48,
  "contains":     "severity:high"
}'

# What workflows finished in the last week?
cb call claudus_recall_observations '{
  "tag":          "workflow_completed",
  "since_hours":  168
}'

# Was there a checkpoint for this workflow?
cb call claudus_recall_observations '{
  "tag":          "workflow_checkpoint",
  "contains":     "material-rework-2026-05-15"
}'

Response shape (excerpt):

{
  "status":  "success",
  "message": "Auto-observation recall",
  "data": {
    "scanned":      256,
    "count":        4,
    "limit":        50,
    "since_hours":  168,
    "tag_filter":   "workflow_checkpoint",
    "contains":     "material-rework-2026-05-15",
    "observations": [
      {
        "id":            "12D25AD7…",
        "text":          "Workflow checkpoint `ck-material-rework-…` saved for workflow `material-rework-2026-05-15` (label: pre-bulk-recompile baseline) with 14 asset entries.",
        "source":        "workflow-checkpoint",
        "source_model":  "claude-opus-4-7[1m]",
        "created_at":    17491635.348,
        "tags":          ["auto_observation", "workflow_checkpoint", "material-rework-2026-05-15", "ck-material-rework-…"]
      },
      /* ... */
    ]
  }
}

scanned is the total ring-buffer size at recall time; count is the post-filter match count.

---

Recommended first-session reads

When a fresh AI session connects, two cheap cb call reads give it a useful picture of where the project stands:

# 1. Project baseline (asset summary, naming patterns, risks)
cb call claudus_get_project_intelligence

# 2. Recent activity journal
cb call claudus_recall_observations '{
  "since_hours":  168,
  "limit":        50
}'

The first answers "what is this project made of?" with the asset-registry summary, naming conventions, and known risks. The second answers "what did the last agents do?" — the full journal of completed workflows, created assets, snapshotted milestones, and recent failures.

A few hundred tokens total. Almost always cheaper than scanning the asset registry call by call.

---

Auto-observations vs explicit memory

Aspect	Auto-observations (claudus_recall_observations)	Explicit memory (memory_remember / memory_recall)
Who writes	The plugin's dispatch path	The agent calls memory_remember
Trigger	Success-with-mutation, workflow completion, checkpoint, tool failure	Anywhere the agent chooses
Storage	Saved/ClaudusBridge/claudus_memory.jsonl (ring buffer, 256 default)	Saved/ClaudusBridge/memory/<topic>.md + _log.jsonl (unbounded)
Schema	Fixed: id, text, source, source_model, created_at, tags[]	Free-form: topic, summary, body, kind, tags, from_session
Filters	Tag, time, substring	Topic, full-text search
Lifetime	Bounded (oldest evicted first)	Unbounded (kept until manually edited)
Best for	"What happened recently?" (audit trail)	"What did we learn that future sessions need to know?" (tribal knowledge)
Cardinality	High volume, automatic	Lower volume, curated

The two are complementary, not competing. Auto-observations give you the activity feed; memory gives you the curated playbook. Use both:

• Read claudus_recall_observations to see what happened.
• Read cb topics / cb recall <topic> to see what was learned.
• After resolving a recurring gotcha you noticed in the auto-observation feed, record the lesson via memory_remember so the next session reads it as a curated bullet instead of having to re-derive it from the journal.

---

Buffer size + retention

The ring buffer holds 256 entries by default. Old entries are evicted FIFO when the cap is reached. The cap is plugin-side, not configurable at runtime in the current build — if a longer history matters for your project, snapshot the JSONL file periodically (a Powershell scheduled task or a Python cron via claudusbridge_watcher.py patterns covers this).

The JSONL file is append-only between evictions; agents should not edit it directly. To prune, stop the editor and delete the file (it regenerates on next observation).

---

Where to go next

• Memory System — The explicit, agent-curated knowledge base that complements the auto-observation feed
• Workflow Checkpoints — The other half of the snapshot story
• Cognition Tier overview — How auto-observations sit in the larger 0.6.x picture