# 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 in `OperationCaps`). 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) and `wait_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 scope `GEMINI_LIVE`, `INTERACTIONS_API` or `RESPONSE_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 400 `INVALID_ARGUMENT`, empty service name). - No credential: every call throws `NotConfiguredError` (503) before traffic. - Destructive calls are explicit methods: `delete_session`, `delete_memory`, `purge`. `purge` is a server-side dry run unless `force` is set, and a forced purge additionally needs `confirm` equal 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.h` row of the call (tested), and those fields are checked against the discovery schema. - Unknown response parts stay raw `Json` (event `actions`, `eventMetadata`, `rawEvent`, `sessionState`, memory `metadata`, `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_configured` without 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 `response` bodies (discovery types them as `Any`): 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.action` values (not enumerated anywhere read). - That `delete` Operations are returned `done` or pollable at `operations/{id}` under the engine (the path shape follows discovery's `operations.get`). - Filter grammar (AIP-160) beyond the field names the docs list: `topics`, `scope` as a JSON string with equality, `timestamp` ranges for events, `displayName` / `userId` / `labels.k` for 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 (`MemoryBankConfig` in the runtime module); the shape of `profile` is 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 (Operation `response` is `Any`) are parsed tolerantly with a GET fallback. `servingProfiles` itself answers 501 on this project, so no body of it was ever seen. - Whether `operations.wait` answers `done: false` at 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`/`audio` parts inside event `content` (typed by `gemini_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. - `servingProfiles` answers 501 for the test project in three locations, so the happy path is Discovery-verified only. Owner: a project that has the feature; test `sessions_live.operations_and_serving_profiles_reads`. - Session and memory `labels` / `metadata` filters beyond a passthrough string. - Token refresh is the caller's job (foundation gap).