Concepts

Knowledge & memory

Two different kinds of recall. Knowledge is a curated corpus an agent retrieves from with citations. Memory is a small set of durable facts about a person or an agent, carried between conversations. They are governed differently because they carry different risk.

	Knowledge	Memory
Holds	Documents — handbooks, policies, specs, tickets	Facts — "prefers metric units", "owns the billing service"
Written by	Upload or a synced source	The agent, mid-conversation
Read via	`search_knowledge`, with citations	`recall`, plus automatic injection
Scoped to	A ring — personal, team, or org	A user, an agent, or both
Enabled by	`knowledge:` in the agent	`memory:` in the agent

Knowledge collections

A collection is a ring-scoped bundle of documents. Attach one to an agent and search_knowledge switches on, along with the citation contract in the system prompt.

---
name: policy-answerer
model: default
knowledge:
  - hr-handbook
  - security-policies
---

Getting documents in

Upload

Drop files into a collection. PDF, DOCX, Markdown, HTML, and plain text are extracted natively.

Sync a source

Connect Confluence or Google Drive and the collection keeps itself current on a schedule.

Attach in chat

Drag a document onto a conversation to give one run its context, without adding it to a collection.

Ingestion

Store
The file lands in object storage, and the document row records its content hash.
Extract
Text is pulled out per format. Ingestion is idempotent on the content hash, so re-uploading the same bytes does no work twice.
Chunk
The text is split into overlapping passages of roughly 800 tokens, so a retrieved chunk carries enough context to stand on its own.
Embed
Each chunk is embedded and indexed for vector search. The collection shows its status while this runs.

Retrieval and citations

search_knowledge returns chunks tagged with citation ids, and the agent is instructed to cite them. Two properties matter:

Citations are real. Every id in an answer corresponds to a chunk that exists and was actually retrieved.
Absence is explicit. When nothing matches, the tool returns a clear "not in knowledge" result rather than an empty list — so the agent says it doesn't know instead of filling the gap from the model's own weights.

Synced sources and permissions

A synced collection stays current on a schedule, and the sync is careful in three ways that matter operationally:

Behaviour	Why it matters
Delta detection	Unchanged documents are not re-embedded. A large space re-syncs cheaply.
Permission-only changes are cheap	If only access changed, chunks are restamped without re-embedding.
Deletes tombstone	A document removed at the source is marked removed and its chunks are deleted, so it stops being retrievable.

Source permissions are mirrored, not flattened Each document's principal list is captured at sync time (groups expanded to members) and denormalized onto its chunks. Retrieval then filters by the run initiator's identity, on top of the usual ring visibility. A document someone cannot open in Confluence cannot be surfaced to them by an agent either — including through an agent they share with a colleague who can open it. If permissions cannot be read, the sync fails closed to the connecting user rather than guessing.

Memory

Memory is deliberately small. The agent decides what is worth keeping via remember, retrieves with recall, and the most relevant memories are injected into later turns automatically — so the user doesn't have to repeat themselves and the agent doesn't have to search every turn.

`memory:`	Scope
`user`	Facts about the person, shared across their agents.
`agent`	Facts this agent learned, not visible to other agents.
`user+agent`	Both.
omitted	No memory tools at all.

Writes are deduplicated: a fact restated in different words or a different order updates the existing entry in place rather than accumulating near-duplicates.

Memory is personal data and is treated as such. It is user-scoped by construction — one person's memories are never visible to another, and administrators do not read them at the default privacy tier. Users manage their own under Settings → Memory, including deletion.

Choosing between them

If the information…	Use
Lives in documents someone else maintains	A synced knowledge source
Is a fixed corpus you control	An uploaded knowledge collection
Matters only to this one question	A chat attachment
Is a durable fact about the person	Memory, scope `user`
Is something the agent learned about its own job	Memory, scope `agent`
Is a procedure to follow	A skill, not knowledge