Projects and subjects

A subject is a named model-memory identity inside a project and, optionally, a customer tenant. Every inference and internalization request includes subject_id. The platform uses that ID to find the active adapter or, for a new subject, the clean base model.

Naming rulesCopy Anchor Link

Subject IDs are case-sensitive strings between 1 and 128 characters. The first character must be a letter or number. Remaining characters may include letters, numbers, underscores, dots, colons, and hyphens.

support-policy
customer_42
workspace.docs
tenant:8f14:assistant

Support and support are different subjects. Spaces, slashes, and email-address punctuation such as @ are not accepted. Prefer opaque application identifiers over names, email addresses, or private document titles, especially if your own logs record subject IDs.

Match the knowledge boundaryCopy Anchor Link

Use one subject when all callers should share the same learned knowledge. A public product manual could use one subject per product. Personalized memory generally needs a subject per user or assistant. Customer-specific procedures should not share a subject with other customers.

Use tenant_id for the authenticated customer and subject_id for the memory within that customer. The same subject name can exist independently in multiple tenants. Your server chooses the authorized tenant; never let a prompt or unchecked client input choose it. Keys can be restricted to one tenant. An unrestricted project key remains a trusted server credential that can select any tenant in the project. See Serve multiple customers.

Use separate projects when you also need separate keys, balances, or spending limits. Tenant-restricted keys are supported; balances and spending limits remain project-wide. There are no per-subject credits or per-subject API key scopes.

Creation and continuityCopy Anchor Link

The first successfully admitted operation creates a missing subject. No prior API call is necessary. A new subject starts from clean base; it never borrows an adapter from another subject or project.

Later internalizations begin from the subject's active version at admission. They create separate candidates rather than editing an existing version in place. If the subject has a saved candidate that was never activated, the next learning job still starts from the active version, not that unactivated candidate.

Inference requests do not automatically become memory. If an interaction contains something your application wants retained, select and authorize that knowledge, then submit a distinct internalization job. Your application remains responsible for deciding what deserves to become durable knowledge.

Avoid accidental resets and accidental sharingCopy Anchor Link

Keep the user-to-subject mapping in your application database. Generating a fresh subject ID on every request discards continuity. Reusing one global ID for unrelated users creates shared learned state. Neither behavior is a routing bug; both follow directly from the IDs submitted.

For a clean comparison, deliberately create a new subject ID and ask it without teaching the source. For a release, preserve the production subject and manage its versions. The current API does not expose subject rename, copy, merge, or delete operations. A new ID is an independent subject, not a copy of the old one.

See Agent memory for a server-side mapping pattern and Versions and routing for how repeated updates interact.