From 1d89ac12d44aa74cc918d98b2f7401795244554c Mon Sep 17 00:00:00 2001 From: Miguel Amigot Date: Mon, 10 Aug 2026 14:07:45 -0400 Subject: [PATCH] Document agent-owned memory as a third memory scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The memory docs described two scopes, and both were user-scoped: global user memories (the user, across all agents) and agent-specific memories (the user, within one agent). Every endpoint reflected that, nested under /users/{user_id}/. Agents also hold memory of their own — what the agent has learned doing its job, shared across every user who talks to it. An agent used by a whole office should not re-learn the same thing once per person, and duplicating that knowledge into each user's memory multiplies storage, drifts as it is corrected in one place and not others, and leaks one person's context into another's profile. Adds the third scope to both the developer reference and the product docs: what belongs there versus in user memory, why it is separate, and the governance that follows from entries being visible to everyone (no personal data, admin-reviewable, audited, scoped to one agent). Agent-owned memory endpoints are agent-scoped rather than user-nested, following the same shape as memory-categories. The exact route slugs are not listed yet and the note says so explicitly, so nobody infers a wrong path from the pattern. Co-Authored-By: Claude Opus 5 (1M context) --- developer/agents/memory.md | 53 ++++++++++++++++++++++++++++++++----- os/agent-settings/memory.md | 18 +++++++++++++ 2 files changed, 65 insertions(+), 6 deletions(-) diff --git a/developer/agents/memory.md b/developer/agents/memory.md index 8f67076..f170131 100644 --- a/developer/agents/memory.md +++ b/developer/agents/memory.md @@ -1,17 +1,20 @@ # Memory System -The Memory System enables AI agents to remember information about users across conversations. It stores user preferences, learning progress, knowledge gaps, and personal context, making interactions more personalized and contextual. +The Memory System lets AI agents carry knowledge across conversations — both what they learn about an individual user, and what the agent itself accumulates for everyone who uses it. It stores user preferences, learning progress, knowledge gaps, personal context, and agent-level operating knowledge, making interactions more personalized, more consistent, and less repetitive. --- ## Overview -The memory system supports two scopes of memory: +The memory system supports three scopes of memory. The first two are **about a user**; the third is **about the agent**. -| Memory Type | Scope | Description | -|-------------|-------|-------------| -| **Global User Memories** | All agents | Facts about the user that apply everywhere (name, profession, preferences) | -| **Agent-Specific Memories** | Single agent | Context specific to interactions with a particular agent | +| Memory Type | Scope | Subject | Description | +|-------------|-------|---------|-------------| +| **Global User Memories** | All agents | The user | Facts about the user that apply everywhere (name, profession, preferences) | +| **Agent-Specific Memories** | Single agent | The user | Context specific to *this user's* interactions with a particular agent | +| **Agent-Owned Memories** | Single agent | The agent | What the agent has learned in general, shared across **every** user who talks to it | + +The distinction that matters: **Agent-Specific Memories** are still keyed to a person — they are what the agent remembers *about you*. **Agent-Owned Memories** belong to the agent itself and are visible to everyone it serves. See [Agent-Owned Memory](#agent-owned-memory). **Default Memory Categories (Agent-Specific):** @@ -25,6 +28,40 @@ The memory system supports two scopes of memory: --- +## Agent-Owned Memory + +An agent is rarely used by one person. A departmental assistant is used by everyone in the office; a course agent is used by a whole roster; a service-desk agent is used by every member of a support team. **Agent-owned memory is what the agent knows that is not about any one of them.** + +Where user memories answer *"what do I know about this person?"*, agent-owned memory answers *"what have I learned doing this job?"* — and the answer is available to the next person who asks, whoever they are. + +### What belongs here + +| Belongs in agent-owned memory | Belongs in user memory | +|---|---| +| A correction a reviewer made that should apply to everyone from now on | That *this* reviewer prefers terse summaries | +| A recurring edge case the team keeps hitting, and how it was resolved | That *this* user already asked about that edge case last week | +| An operating convention the office settled on | *This* user's role, goals, or progress | +| A local fact the agent had to be told once, that everyone benefits from | Anything identifying, personal, or specific to one individual | + +The test is simple: **if the next person to open a conversation should benefit from it, it is agent-owned. If it would be wrong or intrusive to surface to a different person, it is user memory.** + +### Why it is a separate scope + +Without it, an agent used by ten people re-learns the same thing ten times, and knowledge acquired by one person is invisible to their colleagues. Duplicating that knowledge into each user's memory is worse: it multiplies storage, drifts out of sync as it is corrected in one place and not others, and leaks one person's context into another's profile. + +Agent-owned memory is also the correct home for knowledge that would otherwise be pushed somewhere it does not belong — notably the ontology layer, which is a pass-through to the systems it references and stores nothing of its own. + +### Governance + +Because agent-owned memories are visible to every user of the agent, they carry stricter handling than user memories: + +- **No personal data.** Anything identifying an individual belongs in that individual's user memory, not here. Treat agent-owned memory as it will be read by a stranger, because it will be. +- **Administrator-reviewable.** Entries are listed, editable, and deletable by administrators with edit access to the agent, in the same way as the agent's other configuration. +- **Attributable.** Creation and modification are recorded in the agent's audit trail, so a behaviour change can be traced to the entry that caused it. +- **Scoped to one agent.** Agent-owned memory does not propagate to other agents. An agent that should share knowledge with another does so by being given the same skills or datasets, not by reaching into another agent's memory. + +--- + ## Architecture ### System Overview @@ -747,6 +784,10 @@ curl -X DELETE \ | PATCH | `/orgs/{org}/agents/{agent}/memory-categories/{id}/` | Update category | | DELETE | `/orgs/{org}/agents/{agent}/memory-categories/{id}/` | Deactivate category | +Note the two path shapes. Anything **about a user** is nested under `/users/{user_id}/`. Anything **belonging to the agent** — memory categories, and agent-owned memory — is agent-scoped under `/orgs/{org}/agents/{agent}/` and takes no `user_id`, because there is no user it is about. + +> **Agent-owned memory endpoints.** These follow the agent-scoped shape above rather than the user-nested one. The exact route slugs are being finalized and are intentionally not listed here yet — do not infer them from the pattern. Read them from the live API reference at [ibl.ai/developer](https://ibl.ai/developer) before integrating. + --- ## Technical Details diff --git a/os/agent-settings/memory.md b/os/agent-settings/memory.md index 5609b14..ccb5a1e 100644 --- a/os/agent-settings/memory.md +++ b/os/agent-settings/memory.md @@ -8,6 +8,8 @@ The Memory panel reviews and manages what an agent remembers about individual us Each saved memory is a card showing when it was captured (for example, "less than a minute ago"), which user it belongs to (their email), and the remembered fact (for example, "Prefers project-based learning over lecture-based content."). Memories are organized into categories and can be filtered, added, edited, and deleted by administrators. +The panel covers two different kinds of memory. Most cards are **about a user** — what the agent remembers about one person. The agent also keeps memory **of its own**, shared across everyone who talks to it: see [Agent-owned memory](#agent-owned-memory) below. + To reach this screen, open the **Edit Agent** modal, switch to the **Runtime** tab group (its sidebar lists Tasks, Memory, History, Audit, and Analytics), and select **Memory**. ## Target Audience @@ -37,6 +39,22 @@ Opens the **Add Memory** dialog: pick a **Category**, type the **Memory** conten #### Memory cards Each card shows the memory's relative timestamp, the owning user's email, and the memory text. The "..." actions menu on a card offers **Edit** (change the content or category) and **Delete** (with confirmation). A **Delete All** action is available to bulk-delete the memories in the current category filter. +## Agent-owned memory + +An agent is usually used by more than one person — a whole office, a whole course, a whole support team. **Agent-owned memory is what the agent knows that is not about any particular one of them**, and it is available to every user of that agent rather than to a single person. + +The practical difference: + +| | User memory | Agent-owned memory | +|---|---|---| +| Subject | One person | The agent itself | +| Visible to | That person's conversations | Everyone who uses the agent | +| Example | "Prefers project-based learning." | "Transfer credits from the community college are evaluated against the 2026 catalog, not the year of enrolment." | + +**Use it for what the whole team should not have to re-learn** — a correction one colleague made that everyone should inherit, a recurring edge case and how it was settled, an operating convention the office agreed on, a local fact the agent had to be told once. The test: *if the next person to open a conversation should benefit from it, it is agent-owned; if it would be wrong to surface to a different person, it belongs to that person's memory instead.* + +Because these entries are visible to every user of the agent, **keep personal data out of them** — anything identifying an individual belongs in that individual's memory. Agent-owned entries are reviewable, editable, and deletable by administrators with edit access to the agent, and changes appear in the agent's [Audit](audit.md) trail. They do not propagate to other agents; an agent that should share knowledge with another is given the same skills or datasets instead. + ## How to Use #### Step 1: Open the Memory panel