Adds molo::google::apis (api_catalog) as the code source of truth, src/google/APIS.md, a Required APIs section per module SPEC, and the vendor key consoles in src/llm/SPEC.md. Placeholder project example-214512124. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
13 KiB
Google Agent Sessions and Memory Bank - Specification
Owned directory: src/google/sessions/. Namespace molo::google::sessions.
Depends on the src/google foundation (GoogleClient, Service, Operation,
wait_operation, list_all, gemini_types.h). Does not depend on the runtime
module: the Agent Engine is accepted as a validated resource-name string.
1. Scope
Gemini Enterprise Agent Platform, Agent Engine (reasoningEngines) children:
- Agent Sessions: create (custom session id), get, list, patch, delete, compact, appendEvent, list events.
- Agent Memory Bank: generate (from a session, a conversation, or given facts), ingestEvents (streaming), retrieve (scope, similarity search, metadata filters), retrieveProfiles (Memory Profiles, low-latency structured recall), create, get, list, patch, delete, purge (explicit, guarded), revisions (list, get), rollback, topics (managed and custom), scope maps, metadata.
- Long-running operations: every mutating call returns an Operation; the module
waits with
wait_operation(hard caps inOperationCaps). All five Discovery operations methods (get, list, cancel, delete, wait) are wrapped for the four places Discovery puts them: under the engine, under a session, under a memory and under a serving profile (20 table rows).operation(),list_operations(),cancel_operation(),delete_operation(),wait()(client polling) andwait_server()(one POST:wait?timeout=Ns, 1..60 s) work for one root only: the engine, or the location for serving profiles. - Serving profiles (
projects.locations.servingProfiles, location level, not engine scoped): create (waits), get, list, patch, delete, with scopeGEMINI_LIVE,INTERACTIONS_APIorRESPONSE_API, optional CMEK key.
Everything is against one API surface: aiplatform v1beta1. See section 6
for why not v1.
2. Module map (one class or concern per file)
| File | Concern |
|---|---|
caps.h |
Static ceilings (SessionsCaps, MemoryCaps) |
calls.h |
The ONE table of every REST call (verb, path, discovery method, request fields, query params) |
names.h/.cpp |
EngineName, LocationName (validated resource names), Check (input validators), wire helpers |
operation_names.h/.cpp |
OperationName: validates an operation name against its root, picks the table row for each verb by owner (engine, session, memory, serving profile) |
operation_service.h/.cpp |
OperationService : Service: table-driven send, settle, loud capped list_items (list_over_limit), the operations surface |
serving_profile.h/.cpp |
ServingProfileSpec, ServingProfilePatch, ServingProfile, ServingScope, ServingProfiles : OperationService |
session_types.h/.cpp |
SessionSpec, Session, SessionPatch, CompactRequest, SessionEvent, list options |
memory_types.h/.cpp |
Memory, MemorySpec, MemoryPatch, Topic, MetadataValue, MetadataFilter, MemoryGenerateRequest, IngestRequest, RetrieveRequest, PurgeRequest, MemoryRevision, Profile |
engine_service.h/.cpp |
EngineService : OperationService: one validated engine and its v1beta1 endpoint |
sessions.h/.cpp |
Sessions : EngineService |
memory_bank.h/.cpp |
MemoryBank : EngineService |
tools/check_discovery.py |
Verifies calls.h and the typed bodies against Google's Discovery document |
Tests: tests/src/google/sessions/test_sessions.cpp and test_sessions_gaps.cpp. Example:
example/app/agent/SessionsDemo.cpp (routes under /agent/sessions), tests in
tests/example/agent/sessions/.
3. Static caps (see caps.h)
| Knob | Value |
|---|---|
| Session / memory id | 1..63 chars [a-z0-9-]; memory id starts with a letter, ends alphanumeric |
| Engine name | projects/{p}/locations/{l}/reasoningEngines/{e}, 512 chars max |
| Session TTL | Ns form, 24 h minimum (Google), 3650 days maximum (ours) |
| session_state / event | 64 KiB / 256 KiB serialized |
| Labels | 20, key and value 64 chars |
| List pages / items | 10 pages of 100, 1000 items; more items OR a further page after the last allowed one is RESULT_TOO_LARGE (502), never a silent cut, narrow the filter |
| Server-side operation wait | 1..60 s per call (kMaxServerWaitSeconds) |
| Serving profile | id 1..63 [a-z0-9-], display name required 128, description 4000, KMS key name 512 |
| Scope | 1..10 entries, 128 chars, no * |
| Fact / description / context | 4000 chars |
| Generate sources | 100 events, 64 KiB; direct memories max 5 (Google) |
| Retrieve | query 1000 chars, top_k 0..50 (default 5), page size 0..100 |
| Topics / metadata / filter groups | 10 / 20 entries / 10 groups of 10 filters |
| Operation wait | OperationCaps: 600 s, 2 s interval, 400 polls |
4. Contracts
- All input and every id is validated before any network traffic and throws
GoogleError::invalid(HTTP 400INVALID_ARGUMENT, empty service name). - No credential: every call throws
NotConfiguredError(503) before traffic. - Destructive calls are explicit methods:
delete_session,delete_memory,purge.purgeis a server-side dry run unlessforceis set, and a forced purge additionally needsconfirmequal to the engine id (local guard). Compaction rewrites history and is its own method. - Request bodies are built only from fields named in the
calls.hrow of the call (tested), and those fields are checked against the discovery schema. - Unknown response parts stay raw
Json(eventactions,eventMetadata,rawEvent,sessionState, memorymetadata,structuredContent, profile fields). - Example routes: GET pages answer 2xx without a credential; every route that
calls Google is POST or DELETE and answers 503
google_not_configuredwithout a credential and 422 on bad input.
5. Verified against discovery
python3 -I src/google/sessions/tools/check_discovery.py fetches
https://aiplatform.googleapis.com/$discovery/rest?version=v1beta1 (no
credential) and fails if a declared call, verb, path, request field, query
parameter, enum value, response key or nested request field is absent.
Result 2026-10-24: OK 2026-10-24: 46 calls, 8 enums, 34 response keys, 20 nested schemas match aiplatform v1beta1 discovery. The script also checks
coverage: every Discovery method under reasoningEngines.operations,
reasoningEngines.sessions, reasoningEngines.memories and servingProfiles
must be a table row or listed in EXCLUDED (empty: nothing is excluded), so a
method Google adds later fails the check. A deliberately misspelled field made
it exit 1 (checked). Rerun it after any change to calls.h or the typed
bodies.
From discovery (v1beta1, projects.locations.reasoningEngines):
sessions create (POST, sessionId query, returns Operation), get, list
(filter orderBy pageSize pageToken), patch (updateMask), delete (returns
Operation), appendEvent (POST :appendEvent, body SessionEvent), compact
(POST :compact, returns Operation), events.list (sessionEvents);
memories generate / retrieve / retrieveProfiles / create (memoryId) / get /
list / patch (updateMask) / delete / purge / rollback / ingestEvents,
memories.revisions list / get; operations get / cancel / list / delete / wait
under the engine, sessions.operations.* and memories.operations.* (same
five), locations.servingProfiles create (servingProfileId query, returns
Operation) / get / list / patch (updateMask) / delete (returns Empty) and
servingProfiles.operations.*. The Method column of a calls.h row is
relative to kDiscoveryPrefix unless it starts with aiplatform..
6. Verified live
Read-only, 2026-10-24, project read from GOOGLE_CLOUD_PROJECT, no resource
created, changed or deleted. Two credentials:
Express API key (AQ.):
| Call | Result |
|---|---|
GET v1/.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc} |
401 UNAUTHENTICATED: "API keys are not supported by this API" |
GET v1beta1/.../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc, memories/abc/revisions} |
404 NOT_FOUND "The ReasoningEngine does not exist." (key accepted, path routed) |
GET v1beta1/.../reasoningEngines/1/operations/1 |
404 NOT_FOUND "Operation ... not found." |
Service-account OAuth bearer token (token exchange, never stored):
| Call | Result |
|---|---|
GET v1 and v1beta1 .../reasoningEngines |
200 {} (no engine exists) |
GET v1 and v1beta1 .../reasoningEngines/1/{sessions, sessions/abc, sessions/abc/events, memories, memories/abc, memories/abc/revisions} |
404 NOT_FOUND "The ReasoningEngine does not exist." |
GET v1 and v1beta1 .../reasoningEngines/1/operations/1 |
404 NOT_FOUND "Operation ... not found." |
The module uses v1beta1 only because it is the one surface that accepts both
an express key and a token; v1 refuses keys. The opt-in test sessions_live
(MOLO_LIVE_NET=1, GOOGLE_API_KEY or GOOGLE_ACCESS_TOKEN,
GOOGLE_CLOUD_PROJECT; loud SKIP otherwise) repeats six of the reads through
the real client (sessions list / get / events, memories list / get /
revisions) and passed with the key and with the token on 2026-10-24.
Gap-closing round, same day, service-account token, read-only:
| Call | Result |
|---|---|
GET v1beta1/.../reasoningEngines/1/operations?pageSize=5, .../sessions/abc/operations, .../memories/abc/operations |
200 {} (empty list, even though engine 1 does not exist) |
GET v1beta1/.../locations/us-central1/servingProfiles?pageSize=5 (also global host and europe-west4) |
501 UNIMPLEMENTED "Operation is not implemented, or supported, or enabled." (not available to this project) |
GET v1beta1/.../servingProfiles/probe |
501 UNIMPLEMENTED |
GET v1beta1/.../servingProfiles/probe/operations |
400 INVALID_ARGUMENT: "the idType servingProfiles is not a documented LRO Parent ID, the associated value must be a Long, but was instead: probe" |
GET v1beta1/.../servingProfiles/123/operations?pageSize=1 |
200 {} |
The opt-in test sessions_live.operations_and_serving_profiles_reads repeats
the operations lists and the servingProfiles list through the real client; it
accepts 200 or 501/403/404 for servingProfiles and prints which one it saw.
No Agent Engine exists in the project, so no happy path was verified live: create, patch, delete, append, compact, generate, ingest, retrieve, retrieveProfiles, purge, rollback are verified by discovery only. Nothing that costs money was called.
7. Unverified
Neither discovery nor the docs pages read state these; they are inferred:
- Operation
responsebodies (discovery types them asAny): that generate answers{"generatedMemories":[{"memory":{...},"action":"..."}]}, that purge answers{"purgeCount":N}, that create and patch answer the resource (name, ...). Parsers are tolerant: missing keys give empty results, and create/patch fall back to a GET when the id is known. GeneratedMemory.actionvalues (not enumerated anywhere read).- That
deleteOperations are returneddoneor pollable atoperations/{id}under the engine (the path shape follows discovery'soperations.get). - Filter grammar (AIP-160) beyond the field names the docs list:
topics,scopeas a JSON string with equality,timestampranges for events,displayName/userId/labels.kfor sessions. - Similarity search needs the engine's Memory Bank configured with a similarity search model (docs); the error body when it is not is unread.
- Memory Profiles need schema configs on the engine (
MemoryBankConfigin the runtime module); the shape ofprofileis free-form and kept raw. - Serving profile id charset (
[a-z0-9-], 1..63 is our choice) and the real id rule: Google's LRO layer wants a numeric id for operations under a serving profile (400 above), so Google may assign or require numeric ids. The create/patch responses (OperationresponseisAny) are parsed tolerantly with a GET fallback.servingProfilesitself answers 501 on this project, so no body of it was ever seen. - Whether
operations.waitanswersdone: falseat the timeout or an error (the docs line says "at most the time permitted"): both are handled, a not-done answer is returned to the caller, not retried. - Managed topic names beyond the four in discovery, and
thought/audioparts inside eventcontent(typed bygemini_types.h, unknown parts dropped).
8. Gaps
- Engine-level Memory Bank configuration (
contextSpec.memoryBankConfig, customization, TTL config) is part of the Agent Engine resource: runtime module. servingProfilesanswers 501 for the test project in three locations, so the happy path is Discovery-verified only. Owner: a project that has the feature; testsessions_live.operations_and_serving_profiles_reads.- Session and memory
labels/metadatafilters beyond a passthrough string. - Token refresh is the caller's job (foundation gap).
Required APIs
Enable these on the project (placeholder project example-214512124; full list and a one-line gcloud command in src/google/APIS.md). A disabled API answers 403 SERVICE_DISABLED.
aiplatform.googleapis.com: https://console.developers.google.com/apis/api/aiplatform.googleapis.com/overview?project=example-214512124