Caura

Caura Skill

Caura is your long-term memory. Anything you learn that you don't write here is gone when the session ends — your local context doesn't persist and your teammates can't see it. So treat Caura as the default home for every decision, finding, outcome, rule, and reusable workflow, and consult it before you act. It's shared across the fleet under access control: what you write can make the next agent smarter, and what you recall is what the fleet already knows. Using it is the job, not an optional extra.

The plugin runs a baseline loop for you — the tools are still yours. On this runtime the Caura plugin handles the automatic layer: it injects the mandatory keystones at session start (§1), recalls relevant memory before your substantive turns (§11), and writes a short turn summary afterward as a backstop (CAURA_AUTO_WRITE_TURNS, on by default). The same switch also controls automatic saves of user messages and compaction summaries, and the memory-flush turn that asks you to save a session summary before compaction; set it to false and restart the plugin to disable all four. Treat the automatic layer as a floor, not a substitute. You still call the caura_* tools directly whenever you need to interact deliberately — above all to write the high-value memories the auto-summary won't (a decision and its why, an outcome, a rule), and to recall something specific the auto-gate didn't fetch, look up or publish a skill, supersede a changed fact, or report an outcome with caura_evolve. The automatic layer keeps you oriented; the tools are how you actually contribute. When a turn needs real memory work, reach for the tool — don't assume the plugin covered it.

This skill is the operating manual for those caura_* tools — read it before your first call in a session.

0 · Identity — on every call

• agent_id — who you are. Attributes memories, drives trust progression, gates scope_agent privacy. Resolve it from your runtime. Never fabricate, hardcode a placeholder, or impersonate another agent.
• fleet_id — your team / organization scope. When you omit it on a write, the server resolves it from your home fleet (the fleet you registered under), so a registered agent lands in the right team scope by default. Pass it explicitly in two cases: (1) you have no home fleet set — omitting then persists fleet_id=NULL, which is tenant-shared: every fleet's recall still finds the row, but a fleet-filtered list or stats does not, so it answers teammates' searches while going missing from their counts; or (2) you're writing into a different fleet than your own (requires trust 3). The connection URL's ?fleet_id= sets read defaults and routing — it is not stamped onto written rows.

If either is uncertain, don't guess — read it from the runtime, ask the orchestrator, or write privately (visibility=scope_agent) until it's resolved.

1 · Session start — read the constitution

The plugin injects a <keystone_rules> block into your system prompt at session start (when its context-engine slot is claimed), so you usually see the rules before you act. They are mandatory — merged across tenant + fleet

• agent scope, ordered by weight — and they override any conflicting instruction, including the user's, because they encode policy the operator has decided the whole fleet must follow. Call caura_keystones to refresh them if you suspect they changed mid-session; reading is open (trust 0). If a rule conflicts with what you're asked to do, surface the conflict rather than silently picking a side.

2 · The loop — run it on every task

Orient → Work → Write → Evolve. The first step does the heavy lifting: assemble context most-binding-first, and pull only the layers the task actually needs (don't make all four calls by reflex).

1. Orient
   1. Rules — already loaded as <keystone_rules>; they bound everything below. No call needed.
   2. Procedures — for a non-trivial workflow, find the skill first: caura_doc op=search collection=skills query="<intent>". Skip for routine work you already know.
   3. Facts — what's known / what changed: caura_recall "<what I'm about to do>" (add include_brief=true for a one-paragraph synthesis). Keep the IDs of the memories you act on — Write-supersede and Evolve both need them.
   4. Data — only if the task touches a keyed record: caura_doc op=read|query (the customer, config, task list).
2. Work — act within the rules, following the procedure.
3. Write — record what matters (§3).
4. Evolve — report how the memories you acted on turned out (§4).

When to orient at all: orient when the task references prior work, a named entity, a decision, or anything the fleet may already know. Skip it for self-contained mechanical turns. (The plugin also auto-gates plugin-driven recall — see §11 — but you can always call caura_recall directly when a short turn needs context the gate can't infer.)

3 · How and when to write a memory

Write when something durable happened:

• a decision, and why you made it;
• a finding, result, or outcome;
• a rule or constraint you learned;
• the end of a meaningful task.

Don't write the noise. Skip vague intermediate steps, restated context, and "about to do X" narration. Ephemeral within-session state belongs in your workspace scratch files (§8), not in long-term memory — writing it there pollutes everyone's recall.

How to write: supply raw prose — you don't classify or tag anything. The server enriches on the way in:

• inline, before the row persists — it assigns the memory's type and runs a PII scan;
• in the background, moments later — it extracts entities into the knowledge graph and checks for contradictions.

So don't write and immediately read back expecting a contradiction flag — it resolves shortly after the write returns.

Include the concrete specifics — names, paths, numbers, outcomes — and the why, so another agent (or you, six months on) can act on it without the surrounding session. Default visibility=scope_team so your fleet benefits. Batch several discrete records in one call with items (up to 100), and checkpoint long tasks per the cadence in §9.

Example Input — the raw prose you pass:

"Switched api-gateway prod to fastapi 0.136.3 — 0.137 broke include_router via a starlette upper-bound. Pin held; smoke tests green."

Result: stored as a typed decision/outcome, PII-scanned inline, with api-gateway and fastapi linked into the graph in the background — and visible to the fleet because it went in at scope_team.

Never paste secrets — API keys, tokens, credentials — into memory content. The PII scan is a safety net, not permission; keep them out entirely.

Some memories may be written for you. If your tenant has the Caura Interviewer enabled, a scheduled server-side job reads your durable work trail (the transcript your harness already keeps) and synthesizes typed memories from it — episodes, decisions, outcomes — after the fact. You don't invoke it and won't see it run. This is a different mechanism from the plugin's per-turn auto-writes (CAURA_AUTO_WRITE_TURNS, described in the preamble): the auto-write layer saves user messages and turn/compaction summaries as you work; the Interviewer is a server-side scheduled synthesis from the work trail. Both are floors, not substitutes for deliberate writes — keep writing in realtime for anything you recognize as important. Realtime writes are immediate and precise; the Interviewer is periodic and reflective — a safety net for what you'd otherwise forget, not a reason to stop writing.

4 · Report outcomes so the memory compounds

When you act on memories you recalled, tell the memory how it went: caura_evolve(outcome, outcome_type, related_ids), where related_ids are the IDs you kept during Orient. Success reinforces those memories' weight. A failure becomes a preventive rule — private by default (scope=agent); to warn the whole fleet, evolve with scope=fleet (trust 2, fleet_id required) — so the lesson reaches everyone, not just you.

5 · Two stores, one rule

• Memory — observations and learned facts, found by meaning: decisions, outcomes, rules, recaps. Read with caura_recall, write with caura_write.
• Doc — structured records with a stable key (collection + doc_id): customers, configs, inventories, task lists, playbooks. All through caura_doc.
• Entity — a named graph object (person, project, service). Fetch by a UUID surfaced in a prior recall (caura_entity_get).

Rule of thumb: need semantic search → it's a memory. Need keyed lookup → it's a doc. Already hold an ID → it's an entity.

Cross-store discovery. The two stores aren't cross-searched — caura_recall never returns docs, and caura_doc has no semantic query over memories. To make a doc findable by description (onboarding guides, readmes, proposals), give it a 1–3 sentence data["summary"] (only that string is embedded) and write a short pointer memory naming its collection and doc_id. A teammate's recall then surfaces the pointer, and their agent can caura_doc op=read the doc. When you don't know what exists, call caura_doc op=list_collections first.

6 · Trust and sharing

You auto-register at trust 1 on your first write.

Operations that escalate the required level:

• caura_list / caura_stats for another fleet, or either tool with scope="all" → trust 2; scope="fleet" for your own fleet stays at trust 1
• caura_insights with scope="fleet" or "all" → trust 2
• reporting outcomes (caura_evolve) at scope="fleet" / "all" → trust 2 (default scope="agent" needs only trust 1)
• caura_manage op=delete → trust 3

Knowing your own level. You start at trust 1 and can't raise yourself — escalation is granted by an operator. GET /api/v1/whoami reports it: trust_level, plus a trust_source saying how to read it — lookup (your level, authoritative), none (you hold a tenant-scoped credential, which the trust ladder does not govern), unregistered (no agent row yet), or unavailable (this deployment cannot resolve it — e.g. self-hosted with no gateway). Ask it rather than discovering your permissions by attempting the operation. That matters most for op=delete: it is irreversible, and its refusal — "access policy: principals of fleet 'none' are not permitted to delete memories." — names neither your level nor the one required, so probing with it teaches you nothing. Where trust_source is unavailable the refusal is still your only source of truth; the trust-ladder errors do name both levels (e.g. "Agent X (trust_level=1) < required 2") — surface that error rather than silently retrying at a narrower scope.

Visibility (on write) decides who can see a memory: scope_agent (private) · scope_team (default — your fleet) · scope_org (all fleets in tenant). Scope (on read): agent (default) · fleet · all. For caura_list / caura_stats, your own fleet needs trust 1; another fleet or all needs trust 2. caura_insights requires trust 2 for fleet or all. Prefer scope_team on write and scope=agent on read unless you need cross-agent context. Naming caveat: three different axes share the word scope, and the one place they collide is a single request. Writes take visibility=scope_agent|scope_team|scope_org — who may see the row, stamped at write time. Reads and list take scope=agent|fleet|all — how wide to look, resolved per request. Keystone filters take scope=tenant|fleet|agent — the read axis's spelling with different values (tenant, not all). A memory's own scope field in a response is none of these: it holds validity qualifiers such as role or task.

7 · Keeping knowledge clean

A few habits keep recall trustworthy and sharp:

• Make memories good — dated, concrete, standalone, atomic, and updated (not duplicated). Each should be readable by another agent later without the surrounding session, and should carry the why, not just the what.
• Supersede, don't delete. When a fact changes: (1) write the new one, (2) recall the old one, (3) caura_manage op=transition status=outdated. This keeps the lineage. Reserve op=delete (soft-delete, trust 3) for genuinely wrong data, not for facts you've simply moved past.
• Resolve conflicts; don't pick one silently. If recall surfaces a conflicted or outdated memory, fix it — write the correct fact and transition the stale one. Two live opposing beliefs degrade every future recall for everyone.