Shared Memory

The default agent memory model is per-user — every conversation builds a fact profile scoped to one (agent, user) pair. That's right for companion products and 1:1 assistants. But teams need the opposite: they want one agent serving a whole group to know what's going on across users.

Shared memory is the capability that turns a single agent into a team brain — informing user A with the context it gathered while talking to user B, with attribution, server-enforced privacy floors, and a full disclosure audit. Combined with the default-on wisdom layer (de-attributed cross-user generalisation), it gives you two complementary tiers of cross-user knowledge.

Two tiers, one capability surface

Both can run on the same agent simultaneously. wisdom is the safe layer (always behind k-anonymity); sharedMemory is the powerful one (attribution preserved) and demands deliberate opt-in.

When to turn on shared memory

Turn it on when:

• Team coordinators. "Alice owns the migration; Bob is on incident response." Every teammate joining the agent sees the current ownership picture.
• Group / party planning. "Carol brings dessert; Dave does setup." Anyone joining mid-plan picks up state without re-asking.
• Shared business workspaces. Account-level agents where every user on the account benefits from context the others have given.
• Multi-stakeholder support. Customer-success agents where the renewal context one stakeholder gave should inform the conversation with the next.

Leave it off when:

• Single-user companion products (private 1:1 relationships).
• Use cases where users would be surprised that the agent talks about them to other users.
• Compliance-sensitive contexts where cross-user disclosure isn't legally OK.

Enable shared memory

wisdom is a precondition (default-on, so usually nothing to set explicitly). Flip sharedMemory: true to opt the agent in.

// Wisdom is on by default for new agents — only set it
// explicitly if you want to override the default.
await client.agents.updateCapabilities("agent_abc", {
wisdom:       true,
sharedMemory: true,
});

You can also set it at agent-creation time:

const agent = await client.agents.create({
name:       "Team Coordinator",
project_id: "proj_abc",
tool_capabilities: {
  wisdom:        true,
  shared_memory: true,
},
});

Disable shared memory

Pass sharedMemory: false. Existing attributed facts stay in storage (you can re-enable later) but the agent stops surfacing them in context and stops getting the write tools.

await client.agents.updateCapabilities("agent_abc", {
sharedMemory: false,
});

To opt an agent out of wisdom (rare — usually only for strict single-user products):

await client.agents.updateCapabilities("agent_abc", { wisdom: false });

What changes when you turn it on

Three things flip simultaneously the moment sharedMemory: true lands:

1. Tools — the agent gets attributed-wisdom CRUD

The LLM picks up four new tools:

These are deferred tools — the LLM calls them inline; the platform processes the writes asynchronously after the turn so latency stays clean.

2. Context — the agent's prompt grows a "Shared facts" section

Every system prompt the agent runs from now on includes a Shared facts about people and entities section listing the attributed facts on file plus a discretion clause that tells the LLM how to handle disclosure ("exercise discretion; privacy over transparency"). The agent doesn't dump everything to every user — it weighs disclosure decisions per turn.

3. Privacy floor — every write is server-side validated

Before an attributed fact is persisted, the platform runs a semantic validator that rejects writes about compensation, health, politics, and other privacy-sensitive categories. This is enforced server-side, not in the prompt — even if a user explicitly asks the agent to record a salary, the write is blocked. Rejected writes appear in the disclosure audit with decision = "redacted" so you can see what was attempted and why.

Verify it's working

Three checks you can run end-to-end against staging or production. Replace $AGENT_ID, $API_KEY, and the platform URL.

1. List the attributed facts on an agent

curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/attributed?limit=20' \
  -H "Authorization: Bearer $API_KEY"

Expected: a 200 with an array of facts (entity_type, entity_id, category, value, confidence). Empty array if nothing has been written yet — that's still a healthy response.

2. Write an attributed fact directly via the API

curl -X POST 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/attributed' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "person",
    "entity_id": "alice",
    "entity_display_name": "Alice",
    "category": "role",
    "value": "Lead Engineer",
    "confidence": 0.92
  }'

Then re-run the list endpoint above. Alice's role should appear. Now any user talking to this agent will see this fact in the agent's context (subject to discretion).

3. Read the disclosure audit

curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/audit?limit=50' \
  -H "Authorization: Bearer $API_KEY"

Every time a fact is loaded into the context for a turn, an audit row is written with decision = "disclosed" and decision_why. If the privacy floor blocked something, the row will show decision = "redacted". This is your live observability — if production traffic is running with shared memory on, you'll see entries here, and you can audit any disclosure decision in retrospect.

Privacy and control

Shared memory is sensitive by design. Four layers of control sit between an LLM call and a persisted disclosure:

1. Capability gate. sharedMemory: false (the default) means none of this happens — no tools registered, no context injection, no audit rows.
2. Privacy floor. The semantic validator rejects writes in compensation, health, politics, and other configured-sensitive categories before they hit storage. Configurable per tenant.
3. Discretion clause in the prompt. Even with facts present, the agent is instructed to weigh disclosure per turn rather than dumping everything.
4. Disclosure audit. Every disclosure decision is logged with reason. You can review what the agent shared, what it withheld, and why at any time via the audit endpoint.

Hard delete stays admin-only. Agents only soft-delete (tombstone), so a misattributed fact is reversible until an admin clears it permanently.

Combines with other features

With Knowledge Base autonomous editing

knowledgeBaseWrite and sharedMemory are independent capabilities — flip them in any combination:

• KB write only: agents record facts about the world (products, policies, prices, incidents) in the project knowledge graph.
• Shared memory only: agents record facts about people in this team (roles, expertise, ownership, relationships).
• Both: full closed-loop institutional memory plus team brain. The agent learns what's true about the world and who's doing what, and every other agent on the project picks both up.

With Self-Improvement

The per-pair learning loops in Self-Improvement keep getting sharper for that user; shared memory keeps getting smarter for the whole team. Both run automatically on every sessions.End().

With Wisdom (default-on)

wisdom is the de-attributed generalisation layer; sharedMemory is the attributed cross-user layer. Both can run together. The privacy floor protects the attributed side; wisdom doesn't need it because it's k-anonymised before promotion.

Full API reference

Every shared-memory endpoint — list, upsert, replace, delete, bulk import, relations CRUD, disclosure audit — is documented with request/response shapes in the Wisdom API reference.

Next steps

• Knowledge Base — the broader multiplayer memory story (manual upload, ETL push, autonomous agent editing)
• Self-Improvement — how shared memory layers on top of per-pair online learning
• Organization Knowledge Base — tenant-wide knowledge that sits above projects
• Wisdom API — full endpoint reference