Shared team memory

Let a fleet of agents share validated knowledge safely — scoped registration, lanes for isolation, global lessons, and promotion-gated org sharing.

Shared team memory is the pattern for a fleet where what one agent learns should benefit the others — without every agent seeing every agent's scratch work, and without one agent being able to poison the whole fleet. Use it when you run multiple long-lived agents on one instance (a support agent, a reviewer, an analytics agent) and you keep re-teaching each of them the same things.

How it works

Three mechanisms compose, each answering a different question:

Registration declares each agent's contract up front: the entry types it may read and write, and the lanes it participates in (shared_memory_lanes). Lanes keep day-to-day work partitioned inside a shared run. Lesson scope is the sharing dial: a lesson written with lesson_scope="global" is visible to every run on the instance — the standard way to publish team knowledge.

Org scope is different: it cannot be written, only earned. A lesson reaches org visibility exclusively through promotion — it must recur, survive a shadow-A/B audition (injected for some runs, withheld from a control arm, promoted only if the exposed arm does no worse), and carry outcome provenance from at least two distinct actors. The full ladder is in Runs, sessions, and scopes.

Walkthrough

Nimbus registers its fleet on one instance: Ari (support) and Sana (analytics) with deliberately different contracts.

# Registration: each agent's contract. Sana can read lessons and facts but
# cannot write them — an analytics agent should consume knowledge, not mint it.
client.register_agent(
    session_id="nimbus:fleet",
    agent_id="ari",
    role="support",
    read_scopes=["fact", "lesson", "rule", "trace", "handoff", "feedback"],
    write_scopes=["fact", "trace", "observation", "handoff", "feedback"],
    shared_memory_lanes=["support", "shared"],
)
client.register_agent(
    session_id="nimbus:fleet",
    agent_id="sana",
    role="analytics",
    read_scopes=["fact", "lesson"],
    write_scopes=["observation"],
    shared_memory_lanes=["analytics", "shared"],
)
 
# Day-to-day: lane-scoped writes keep scratch work out of each other's context.
client.remember(
    session_id="nimbus:fleet",
    agent_id="ari",
    content="Ticket queue spiking on CSV-export errors again",
    intent="observation",
    lane="support",
)
 
# Sharing: Ari's CSV-export lesson has held up across tickets — publish it
# instance-wide so every run (including Sana's) sees it.
client.remember(
    session_id="nimbus:ari:ticket-1102",
    agent_id="ari",
    content="When an export times out, check the report row count before "
            "retrying — over 500k rows needs the batched exporter.",
    intent="lesson",
    lesson_scope="global",     # or the alias share="global"
)
 
# Consumption: Sana, in a completely different run, gets it automatically.
digest_context = client.recall(
    session_id="nimbus:sana:weekly-digest",
    agent_id="sana",
    query="known causes of export-related ticket spikes",
    entry_types=["lesson", "fact"],
)
# → the global CSV-export lesson surfaces, with its scope confidence bonus.

What promotion quarantine looks like

Suppose Ari also writes a plausible-sounding lesson — "skip reproduction steps for Scale-plan customers, they're usually right" — and keeps reinforcing it with its own successful-looking outcomes. It recurs, so it becomes a promotion candidate toward org scope. It then stalls in quarantine: every outcome in its provenance comes from one actor (Ari), and the distinct-actors gate requires at least two. Until Rex or another principal independently validates it, the lesson stays at its written scope. If it does enter a shadow audition and the exposed arm performs worse, the candidate is rejected outright — the control stream emits context.lesson_promotion_candidate and context.lesson_promotion_rejected events you can watch (see Event-driven agents).

Why one agent can't widen scope unilaterally

Scope is injection reach. A global or org lesson gets injected into contexts of agents that never saw the evidence behind it — they will act on it with borrowed trust. If any single agent could write directly to org scope, one compromised, misconfigured, or merely overconfident agent could steer the entire fleet with a single bad write. That's why the write path is capped: share="org" is rejected by the SDK with an explanatory error (the share= alias ships in SDK v0.12.0; lesson_scope= works on all versions), and the only route to org visibility runs through recurrence, shadow validation, and multi-actor provenance. Treat direct lesson_scope="global" writes as a deliberate publishing act by an agent you trust for it — and use write_scopes at registration to deny lesson-writing entirely to agents that shouldn't publish (as Nimbus does for Sana).

When not to use it

Related

• Runs, sessions, and scopes — the scope ladder and promotion gates in full
• The learning loop — how lessons are extracted, validated, and promoted
• Trust and confidence — how scope feeds knowledge_confidence at retrieval
• Lane-scoped memory — the lanes walkthrough, including failure modes
• Multi-agent shared state — registration + handoff + feedback end to end