Build agent memory

An agent-memory integration needs two decisions: what knowledge should persist, and which subject is allowed to learn it. The model can propose an internalize tool call, but your server should own both authorization and execution.

Resolve the subject on the serverCopy Anchor Link

Maintain a mapping from your authenticated user or workspace to a subject ID. Derive it from trusted application state. If the model supplies a subject argument, verify it against that mapping instead of treating it as authority to access any subject in the project.

Authenticated user
    → authorized workspace
    → server-owned subject mapping
    → scoped Internalize project key

A project key is not restricted to one subject. Separate customer projects when your application needs separate credentials or billing boundaries, and use separate subjects when learned knowledge should remain independent inside a project.

Select durable knowledgeCopy Anchor Link

Good candidates include stable preferences the user asked to retain, approved product rules, or a corrected procedure. Transient search results, unverified claims, and instructions embedded in external content need review before they become memory.

Keep the original source and its provenance in your own governed store. An adapter is not a queryable memory database and does not return a list of all learned facts. The platform's job history tracks operations and versions, not a semantic inventory of everything the model may know.

Use one tool invocation identityCopy Anchor Link

Bind the runtime's durable tool-invocation ID to the idempotency key. The key must satisfy the API's 8–128 character format; hash or map framework IDs that contain unsupported characters. Persist that mapping before submission.

If the runtime retries the tool after a timeout, recover the same job. If the user intentionally requests a different memory, create a new invocation and operation key. Do not derive the key only from the subject, because that would collide with every later update to it.

Report the real outcomeCopy Anchor Link

Return a small result containing job ID, status, candidate version, validation, and activation. Tell the agent that admission is pending work, not completed memory. A ready candidate with an activation conflict is a release decision, not a successful change to the active subject.

After confirmed activation, continue inference with the same subject and omit the learned source. Your application still supplies the new question and relevant conversation messages. Past chats do not become persistent knowledge automatically.

Control updates and costCopy Anchor Link

Queue dependent updates per subject so each one starts from the intended parent. Deduplicate repeated memory proposals in your own application before creating a new paid intent. Use project spend limits as a backstop, not as the agent's only memory policy.

Every internalization has an application-set budget and uses metered compute without a flat fee. Evaluation inference is separately billed. If an agent proposes many tiny updates, consider collecting a coherent approved passage before learning it, while staying within the content limit and preserving provenance.

For a schema and handler example, see Agent tool integration. For correction, regression, and unsupported-answer tests, see Evaluation.