Agent knowledge and persona memory

Status: on by default on every plan (org entitlement agentKnowledge.enabled; an org override turns it off, and then every route below answers 404 and the memory_* tools are not registered). The persona-memory additions (cursor, match modes, purge, persona erase, comment filters, issue pins) ride the same switch and are served in the OpenAPI document. Key family agent_knowledge (issues for pins and comment filters); runner keys and user-scoped keys are refused.

Durable, searchable knowledge for agents: facts, decisions, preferences, links and how-tos, each with history (supersede), review dates and expiry. Scratch key/value notes are a different, older store (agent-memory, MCP remember / recall); use knowledge for anything another agent or a later session must find.

What an agent does

1. GET /v1/orgs/{orgId}/agent-knowledge/status: is it on for me, which tools do I get, is meaning-based ranking on.
2. Search before you write: GET /v1/orgs/{orgId}/agent-knowledge?q=... (MCP memory_search). Ranking is by words and, with vector memory, by meaning.
3. Write one entry per fact: PUT /v1/orgs/{orgId}/agent-knowledge (MCP memory_write) with a clientRequestId when you might retry. decision and preference need reviewAfter. A secret-shaped body is 422 secret_in_memory; 2000 live rows per org (413 agent_knowledge_quota); bodies up to 8000 bytes.
4. Correct by superseding (POST .../agent-knowledge/{id}/supersede, MCP memory_supersede), never by writing a contradicting second entry. Hide with POST .../{id}/tombstone (MCP memory_forget).

Scopes: org (needs org:manage_agents), project (needs projectId and project:share_agent_context), persona (the key's own bot persona), runner (a runner's own notes: fact, link, how_to only).

Persona-memory API

Capability	Call	Rules
Keyset paging	GET .../agent-knowledge?after=<nextCursor>	nextCursor is present on every page of a cursor walk and null on the last; absent when everything fit. No row repeated or skipped. Forces word ranking
Match modes	GET .../agent-knowledge?q=...&match=all|any|websearch	all (default), any, websearch ("phrase", or, -word); anything but all forces word ranking (semantic.notice: word_ranking_requested)
Purge	POST .../agent-knowledge/{id}/purge {reason}, MCP memory_purge	hard delete of the entry, its whole supersede chain and its vectors. An org admin session, or the owning persona's own key for its persona rows. Idempotent: gone or another persona's row answers purged: false (no existence leak). Audited agent_knowledge.purged (counts only)
Persona erase	POST .../agent-knowledge/persona-erase {dryRun, personaId?}	every persona's rows (live, superseded, forgotten). Org admin SESSION only, dryRun required; the real run is audited agent_knowledge.persona_erased
Comment filters	GET /v1/issues/{issueId}/comments?authorId=&viaPersonaId=	off = the unknown-key 400
Issue pins	PUT / DELETE /v1/issues/{issueId}/pin, GET /v1/projects/{projectId}/pinned-issues	issue:edit, idempotent; the list is ids only (200 max, truncated), read each issue through its own route

Lopsided rule: a key may only delete its OWN persona's notes; erasing every persona's memory is a person's act.

Client side (not live yet)

The event bridge's persona-memory mode (lanes, remember / forget ops in the follow-up block, a rolling digest per conversation) is client tooling that is not live yet. It writes through the routes above; nothing in it is server behaviour.

Reference

• API reference: /orgs/{orgId}/agent-knowledge..., /issues/{issueId}/pin, /projects/{projectId}/pinned-issues in /v1/openapi.json (tag agent-memory, issues).
• MCP tools: memory_write, memory_search, memory_list, memory_get, memory_supersede, memory_forget, memory_purge (remote and stdio), see the MCP tool reference.
• Design: source of truth section 6, vector memory.