Sharing and visibility

Which of an agent's memory can reach another agent, what has to be true before it does, and what is stripped out on the way.

In short

A learning can travel between agents; a claim cannot. A learning leaves its agent only after it has proven itself, and only the generalized rule crosses, never the cases it was learned from. Claims stay with the agent that recorded them, always.

Three questions decide whether one agent's experience can reach another: what the record is classified as, whether it has earned the crossing, and which space it would land in. This page answers all three for both shelves, because they answer them differently on purpose. Learnings are abstractions and can be shared once they are safe. Claims are made of the identifying material a learning has had scrubbed out, so they never leave the agent that recorded them.

The classification every learning carries

Every learning carries one of three classifications. It decides one thing only: whether the learning may cross the agent boundary. It does not affect whether the agent that owns it can use it, because an agent always recalls its own learnings, whatever they are classified as.

Classification	Meaning	Who can recall it
`shareable`	Universally applicable, safe to promote	The owning agent, and other agents in the organization once it is promoted
`agent_specific`	Relevant only to this agent, for example a user's preferences	The owning agent only
`sensitive`	Anything that must not cross an agent boundary	The owning agent only

The learning default is permissive; classify explicitly when you write

A learning created through the Learnings API defaults to shareable, and a stored learning whose classification is missing or unrecognized also reads back as shareable. That is deliberate on this shelf, because a scrubbed, generalized learning is the one record that is safe to default toward sharing. But it means the default is permissive, and the promotion gate below, not the classification, is what actually holds the boundary.

Classification defaults the other way on the shelves where the raw material survives: a claim and an episode both fail closed, to agent_specific, when their stored value is missing or damaged. If you write learnings programmatically and any of them are specific to one agent or one person, set privacy on the way in.

A learning is never shared because someone marked it shareable. Classification only makes it eligible. Every one of these must also hold before a learning is promoted to the organization's shared pool:

Requirement	Detail
Classified `shareable`	Anything else stays with its agent
Not archived and not superseded	Retired knowledge must never propagate; a learning may have been archived precisely because it was misleading
Not bound to a value from your own claims	A learning whose value resolves from this tenant's claims can never be promoted, in either direction: the binding is private, and the wording without it is meaningless
Shared learning enabled for the agent	On by default for hosted agents, off by default in the SDK
Trust at least agent-verified	The learning has been verified by the agent that holds it, not merely recorded
Applied at least 3 times	`promotion_min_applied`
Helpful in at least 70% of applications	`promotion_min_success_ratio`

When a learning that clears all of this is close enough to one already in the shared pool, it does not create a duplicate: it corroborates the existing record, adding its agent to the validators. Corroboration is also how a shared learning gains standing, with two validating agents raising it to source-verified and three to corroborated, while two agents finding it unhelpful pull it back down.

What crosses, and what stays behind

Promotion shares the abstraction, not the raw data. Only the generalized rule, the tools it applies to, and its trust metadata cross the boundary.

Everything below stays with the originating agent, permanently:

the specific cases the learning was formed from, and their entity values and outcomes
the original goal text of the run that produced it
the abstracted situation cue, which stays agent-local until its own promotability is proven
the goal phrases the learning applies to
the scope regions it has earned through use, and any condition bounds
any value bindings into this tenant's own claims
every claim-derived count: how many claims the agent held, how many satisfied the learning, and which ones
the dominant genre and channel of its evidence, which describe the donor's corpus and not the recipient's

Which fields may cross is declared on the learning type itself, and a schema test fails if a newly added field is classified as neither private nor promotable, so a new field cannot leak by being forgotten.

Two further properties follow from how the shared pool is read. A promoted learning is never served back to the agent that donated it, so an agent cannot corroborate itself. And a shared learning arrives unbound: the recipient re-grounds it against its own claims rather than inheriting the donor's.

Where a shared learning lands

Sharing is not org-wide by default. Every agent has one home space, and that is where its promoted learnings land. Recall reaches the spaces the caller can view, and nothing else.

That means the audience for a promoted learning is the audience of its home space: a personal space shares with no one, a department space shares with that team, and commons shares with everyone in the organization. Choosing an agent's home space is how you choose who its learnings reach. Access control covers the space kinds, the roles that govern who can publish into them, and how API key reach interacts with them.

Reading the shared pool

Two surfaces read across agents, and both require an Enterprise subscription:

POST /learnings/search with scope: "org", which searches the shared pool instead of one agent's corpus
GET /org/learnings, the tenant-wide library of promoted learnings, reported with evidence already stripped and cross-agent corroboration summarized

Both are still filtered to the spaces the caller can read. See the Learnings API for parameters and response shapes.

Claims never travel

Claims have no equivalent of promotion. There is no shared pool, no eligibility gate, and no way to mark a claim as shareable.

Private by default at the storage layer, not by policy. A claim's classification defaults to agent_specific in the database itself, and the check that reads it back fails toward private if the stored value is missing or damaged.
An agent sees only its own claims. Row-level security enforces this in the database engine, not in application code, so a caller that fails to identify itself sees zero rows rather than too many.
A claim that cannot be attributed to an organization cannot be written at all, because a claim nobody can find is a claim nobody can erase.
The org queues are curation surfaces, not sharing. GET /org/claims/quarantine and its siblings let a person review one organization's claims across its agents. They never expose one agent's claims to another agent, and a caller whose space reach is restricted gets a filtered page that says so.

Erasure works per entity, and the receipt names what it did not reach rather than implying completeness. Note in particular what that list includes: erasing an entity's claims unwinds the support they lent to your learnings, but it does not delete the learnings themselves. A generalized learning is not a record of the entity, which is the whole reason it was safe to keep.

Scrubbing happens before any of this

None of the above is what keeps credentials and personal data out of a shared learning. That work happens earlier, when the learning is first extracted, and it applies whether or not it is ever shared:

a deterministic scan for credentials, API keys, tokens, and connection strings, run over the exact text that will be stored
a scan for identifiers taken from the run itself: UUIDs, domains, email addresses, numeric IDs
a cross-check that redacts entity values the model leaked into the generalized wording
PII redaction over the learning text, with the agent's own tool names allow-listed so a tool is not mistaken for a person
the same stack over the durable situation cue, failing closed to a generic label on any hit
a floor from the sensitivity of the run as a whole: work that touched credentials, or a person's own data, pulls every learning from that run to a stricter classification

The raw goal is not stored. A learning distilled from a run keeps a scrubbed cue, never the wording of the request.

One exception, on the write path

A learning you create yourself through POST /agents/{agent_id}/learnings stores the source_goal you send, verbatim. The extraction pipeline above is what empties that field; a direct write is you asserting the content. Send generalized learnings and a description of the task, never a customer's raw request.

Learning for what a learning is and how it earns its standing
Claims for the claim shelf and why it is fenced instead of scrubbed
Episodes for the run record, which is never shared across agents
Access control (FGA and RBAC) for spaces, roles, and scopes
Security and data isolation for tenant isolation and the wider model
Learnings API for the privacy field and the org-scope surfaces

Sharing and visibility

On this page