One umbrella for every way memory crosses boundaries in Sonzai — agent-to-agent (inter-agent) through the shared knowledge base, and across users sharing one agent (intra-agent) through wisdom and shared memory. A closed-loop company brain plus a team brain, combined.

The default agent memory model is per-pair — every conversation builds a fact profile scoped to one (agent, user) pair. That isolation is the right default for privacy, but the moment your product has more than one agent or more than one user per agent, you want memory to cross the boundary in controlled, observable ways.

Multiplayer memory is the umbrella for those crossing capabilities. It splits cleanly along two axes:

Axis	What crosses	Real-world shape	Capabilities
Inter-agent	Knowledge between agents on the same project (or tenant).	A closed-loop company brain — agent A learns; agent B picks it up.	`knowledgeBase` (read), `knowledgeBaseWrite` (autonomous update), `knowledgeBaseScopeMode` (org-wide cascade).
Intra-agent	Memory between users talking to the same agent.	A team brain — one agent informing user A with what it learned with user B.	`wisdom` (de-attributed, default-on), `sharedMemory` (attributed, opt-in).

Both axes can run simultaneously. The full picture: agents on the same project share the world they've learned about (inter-agent) and a single agent shares context about the people it serves (intra-agent). Same compounding curve, two dimensions.

INTER-AGENT (across agents)
            shared knowledge base, autonomous updates,
              org-wide scope, closed-loop company brain
                              |
                              v
 +-------------------------+      +-------------------------+
 |       Agent A           |      |       Agent B           |
 |  reads + writes KB      |<---->|  reads + writes KB      |
 +-------------------------+      +-------------------------+
          ^ ^ ^                                ^ ^ ^
          | | |  INTRA-AGENT (across users)    | | |
          | | |  wisdom (de-attributed),       | | |
          | | |  shared memory (attributed)    | | |
 +--------+ | +---------+              +-------+ | +---------+
 |          |           |              |         |           |
user X1   user X2     user X3        user Y1    user Y2    user Y3

 Inter-agent: anything any agent learns is grounded data
              for every other agent on the project.
 Intra-agent: a single agent carries memory across the
              users it serves -- with privacy guardrails.

Inter-agent memory — agent ↔ agent

Inter-agent memory turns the project knowledge base into a closed-loop company brain: anything one agent learns or verifies during a conversation becomes grounded data every other agent on the project retrieves on the next session. Three layers stack from baseline to organization-wide.

1. Baseline read — every agent grounds replies in the project KB

Any agent with knowledgeBase: true reads the project knowledge graph during conversations via the knowledge_search tool. The graph is hand-curated, ETL-loaded, or both — see How knowledge gets into the KB for the two ingestion paths.

await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase: true,
});

2. Autonomous editing — agents write what they learn back

Flip knowledgeBaseWrite: true and the agent gets knowledge_create / knowledge_update / knowledge_delete tools. During conversations the agent records verified facts itself, with a full audit trail (source = "agent:<agent-id>") and compare-and-swap update semantics so admin edits don't get clobbered. The next agent that runs knowledge_search on the same topic retrieves what the previous agent wrote down.

await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:      true,
  knowledgeBaseWrite: true,
});

Use this when the source of truth IS the conversation — support agents recording verified incident details, customer-success agents capturing renewal context, scribe agents writing meeting notes. Detail: Agents writing to the knowledge base.

3. Organization scope — tenant-wide knowledge above projects

Set knowledgeBaseScopeMode: "cascade" on an agent and it reads from both the project KB and the org-scope KB on every search. The org scope is for tenant-wide artefacts: policies, lore, brand, reference catalogs. Project wins on collisions; org fills in defaults.

await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:          true,
  knowledgeBaseScopeMode: "cascade",
});

Detail: Organization Knowledge Base.

Intra-agent memory turns a single agent into a team brain: one agent serving multiple users carries memory that crosses the user boundary, so it can inform user A with the context it gathered while talking to user B. Two complementary tiers.

1. Wisdom — default-on, de-attributed

wisdom is on for every new agent. A daily promotion job pulls patterns from per-user fact histories, k-anonymises them, and rewrites the result through an LLM into agent-wide knowledge. No individual user is identifiable. Every agent benefits from "what tends to work / what tends to come up" without ever leaking who said what.

// Wisdom is on by default. Pass false only to opt out
// (rare — usually only for strict single-user products).
await client.agents.updateCapabilities("agent_abc", { wisdom: false });

This is the safe intra-agent layer — privacy-protected by construction, no opt-in required.

2. Shared memory — opt-in, attributed

sharedMemory: true is the powerful intra-agent layer. The agent records person/entity-attributed facts (roles, expertise, business context, relationships) and surfaces them to other users sharing the agent — with names visible. "Alice owns the migration; Bob is on incident response." "Carol brings dessert; Dave does setup."

await client.agents.updateCapabilities("agent_abc", {
  wisdom:       true,   // precondition; default on
  sharedMemory: true,
});

Three things flip when you turn it on: the agent gets sonzai_wisdom_set/update/delete/relate tools; the prompt grows a "Shared facts" section with a discretion clause; every write is server-side validated against a privacy floor (compensation, health, politics blocked). Every disclosure is logged to the audit table. Full detail: Shared Memory.

Combining inter-agent and intra-agent

The two axes are independent — every combination is valid:

Inter-agent	Intra-agent	What you get
Off	Off	Per-pair memory only. Right default for single-user companion products.
On (read only)	Off	Agents ground replies in your KB but don't share between users. Standard read-only docs assistant.
On (read + write)	Off	Closed-loop world knowledge. Agents capture verified facts about products, prices, incidents — every other agent benefits.
Off	On	Team brain — one agent serves a group, but no shared world knowledge across agents.
On (read + write)	On	Full multiplayer memory. Closed-loop world knowledge plus a team brain. Best for shared-business-context products.

// Full multiplayer memory in one capability update
await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:          true,
  knowledgeBaseWrite:     true,    // inter-agent: closed-loop KB
  knowledgeBaseScopeMode: "cascade", // inter-agent: org scope
  wisdom:                 true,    // intra-agent: de-attributed (default on)
  sharedMemory:           true,    // intra-agent: attributed
});

How to verify it's working

Each capability has a live read endpoint you can hit to confirm the loop closes. Replace $AGENT_ID, $PROJECT_ID, $API_KEY with your own.

Inter-agent — KB writes

# Search the project KB — does an agent write show up?
curl 'https://api.sonz.ai/api/v1/projects/$PROJECT_ID/knowledge/search?q=YourQuery' \
  -H "Authorization: Bearer $API_KEY"

Intra-agent — attributed shared memory

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

# Read the disclosure audit — every fact disclosed in a turn is logged
curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/audit?limit=50' \
  -H "Authorization: Bearer $API_KEY"

Intra-agent — wisdom (default-on)

The de-attributed wisdom layer surfaces inline in every prompt the agent runs once the daily promotion job has scanned per-user fact histories — no separate read endpoint. To verify it's running, watch agent context size over a 48-hour window after multi-user traffic; you should see the wisdom block populate.

Privacy and control

Multiplayer memory is sensitive by design. Each capability has its own controls — none of them require trusting the LLM:

Capability	Server-side controls
`knowledgeBaseWrite`	Schema validation per write, write quotas, project-scope check, full audit trail (`source = "agent:<agent-id>"`), CAS update, soft-delete only (hard delete admin-only).
`wisdom`	k-anonymity threshold before promotion, LLM-gated rewrite to remove identifying detail, daily cadence so a single noisy session can't leak.
`sharedMemory`	Semantic privacy-floor validator (compensation, health, politics blocked), discretion clause in every prompt, disclosure audit on every fact load, soft-delete tombstone, source pinned to `developer_api` (callers can't spoof provenance).

Every cross-boundary flow has a corresponding read endpoint, so you can audit retrospectively at any time.

Where to dive deeper

Knowledge Base — the inter-agent surface: ingestion paths, schemas, autonomous editing detail
Organization Knowledge Base — the org-wide cascade detail
Shared Memory — the intra-agent surface: enable/disable, four wisdom tools, privacy floor, full verification probes
Self-Improvement — how multiplayer memory layers on top of per-pair online learning
Wisdom API — full endpoint reference for shared memory CRUD + audit

Multiplayer Memory