| name | agents-using-observer |
| description | When the Retainer cog should delegate to the observer, how to brief it, what to expect back, and how to verify the result. Observer is the knowledge gateway — recent (hot index) and deep (full archive). Read before dispatching to agent_observer. |
| agents | cognitive |
Using the observer
The observer is the knowledge gateway. It looks inward — at
cycles, narrative, facts, CBR cases — AND reaches into the full
JSONL archive when needed. You reach it via agent_observer.
The observer routes recent vs deep internally. You don't need to
pre-classify the question.
When to delegate
Recent (hot index):
- "What did I do earlier?" / "what was that about?" — recall
beyond your conversation window
- "Why did cycle X fail?" / "what was the result of cycle Y?" —
cycle drill-down
- A curated summary of recent activity (3+ cycles), not one fact
lookup
Deep (full archive):
- "Have we ever seen X?" / "find every time we discussed Y" —
recall older than the librarian's 60-day hot index
- "Consolidate the last month's work into a report"
- "What patterns do we see across the case archive?" — pattern
mining for recurring shapes
- Cross-store topic mapping ("everything about auth across
narrative + facts + cases")
CBR curation:
- "Suppress this case" / "boost that one" / "annotate with this
pitfall" — operator-driven curation
- "Recall cases similar to this query" — CBR retrieval
When NOT to delegate
- A single fact lookup ("what's the value of key K?") — call
memory_read directly. The observer's get_fact is the same
data; the round-trip via delegation is wasted.
- Questions about something already in your conversation context.
- Anything requiring action on the world — the observer reads,
never writes (its only writes are CBR curation events and
consolidation reports, which are knowledge-shaped).
Briefing the observer
Be specific about the question. The observer has many tools and
you're effectively scoping it when you brief:
Recent — cycle drill-down:
"Inspect cycle abc12345. Report status, duration, and any
error."
Recent — activity recall:
"Show the last 5 narrative entries with summaries."
Recent — fact lookup:
"What's the current value of the fact user.preference.theme?"
Deep — historical search:
"Search the full narrative archive for any cycle that
discussed the auth-flow timeout. Date range: open-ended."
Deep — consolidation:
"Consolidate work from 2026-04-01 to 2026-05-01 around the
auth flow. Write a report if the digest is worth keeping."
Deep — pattern mining:
"Mine the case archive for recurring problem shapes. Min
cluster size 3."
CBR curation:
"Suppress case abc123 — operator says it's a bad pattern."
A vague brief like "what's been going on" makes the observer
guess which tool to call. Pass relevant context — operator's
prior question, the cycle ID you're curious about, the date
range, whatever scopes the work.
What to expect back
A direct text reply. Usually:
- The answer at the top
- Cycle IDs (8-char prefix) and timestamps for anything sourced
- Caveats on what couldn't be determined
- Confidence qualifiers on old material (decayed facts flagged
as decayed; old cases noted as potentially outdated approaches)
- Report file path when synthesis was the deliverable
The observer won't speculate beyond the data — if the narrative
or archive doesn't say, neither does it.
Verifying the result
- "no matching cycle" / "no fact found" / "no patterns above
threshold" are real answers, not failures. Treat them as
authoritative.
- Cycle IDs in the observer's reply are real — you can pass
them to a follow-up
inspect_cycle brief if you want more
detail on one.
- The observer doesn't fabricate. If it says X, the data
said X.
- Synthesis output (consolidation, mining) is the
observer's voice — re-reading raw excerpts isn't required,
but flag back to the user if the synthesis seems thin.
What the observer refuses / can't do
- Won't take actions on the outside world.
- Won't write to memory keys (consolidation reports + CBR
curation events are the only writes; both are
knowledge-shaped).
- Can't predict future cycles or recommend what the cog should
do.
- Doesn't replicate the cog's memory tools — for fact-key
lookups you should use
memory_read directly.
Cost awareness
The observer's react loop is max_turns=8 (was 6 before the
remembrancer fold). Recent queries usually finish in 2-3 turns;
synthesis-shaped work (consolidation, mining) can use 4-6.
Still — one or two of your direct memory tools is usually
faster than a delegation. Reserve the observer for queries
that genuinely need cycle inspection, curated recall, or
deep-archive work.