Document agent-owned memory as a third memory scope - #16

Why

The memory docs described two scopes — and both were user-scoped. Every endpoint in developer/agents/memory.md is nested under /orgs/{org}/users/{user_id}/:

"Agent-specific" reads like agent-owned but isn't — it is still keyed to a person; it's what the agent remembers about you.

Agents also hold memory of their own: what the agent has learned doing its job, shared across everyone who talks to it. An agent used by a whole office shouldn't re-learn the same thing once per person, and pushing that knowledge into each user's memory instead multiplies storage, drifts as it is corrected in one place and not others, and leaks one person's context into another's profile.

It is also the correct home for knowledge that otherwise gets pushed somewhere it doesn't belong — notably the ontology layer, which is a pass-through to the systems it references and stores nothing of its own.

What changed

developer/agents/memory.md

• Overview now describes three scopes, with a Subject column making explicit which are about a user and which is about the agent.
• New Agent-Owned Memory section: what belongs there vs. user memory (side-by-side table), why it is a separate scope, and governance — no personal data, admin-reviewable, audited, scoped to one agent.
• Endpoint summary notes the two path shapes: user-scoped under /users/{user_id}/, agent-scoped under /orgs/{org}/agents/{agent}/.

os/agent-settings/memory.md

• Overview notes the panel covers both kinds.
• New Agent-owned memory section with the user-memory comparison and the one-line test: if the next person to open a conversation should benefit from it, it is agent-owned.

Please check before merging

The route slugs are deliberately not listed. The doc states they are agent-scoped and being finalized, and explicitly tells readers not to infer them from the pattern. If the real endpoints exist, please add them — I did not want to publish a path that returns 404.

Two other things worth a maintainer's eye:

• Whether agent-owned memories are extracted automatically from conversations the way user memories are, or only added deliberately. The docs currently don't claim either.
• Whether the Memory panel surfaces them today, or whether the os/ section describes intended behaviour ahead of the UI.

Related: /api/ai-mentor/orgs/{org}/metadata/ (create/update metadata for a mentor) is agent-scoped and user-independent, and has no doc page in os/ or developer/. Worth documenting separately.

🤖 Generated with Claude Code