2026-10-24 04:36:42 +02:00
# 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
2026-10-24 05:43:13 +02:00
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.
2026-10-24 04:36:42 +02:00
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) |
2026-10-24 05:43:13 +02:00
| `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` |
2026-10-24 04:36:42 +02:00
| `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` |
2026-10-24 05:43:13 +02:00
| `engine_service.h/.cpp` | `EngineService : OperationService` : one validated engine and its v1beta1 endpoint |
2026-10-24 04:36:42 +02:00
| `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 |
2026-10-24 05:43:13 +02:00
Tests: `tests/src/google/sessions/test_sessions.cpp` and `test_sessions_gaps.cpp` . Example:
2026-10-24 04:36:42 +02:00
`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 |
2026-10-24 05:43:13 +02:00
| 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 |
2026-10-24 04:36:42 +02:00
| 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.
2026-10-24 05:43:13 +02:00
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.
2026-10-24 04:36:42 +02:00
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,
2026-10-24 05:43:13 +02:00
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.` .
2026-10-24 04:36:42 +02:00
## 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.
2026-10-24 05:43:13 +02:00
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.
2026-10-24 04:36:42 +02:00
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.
2026-10-24 05:43:13 +02:00
- 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.
2026-10-24 04:36:42 +02:00
- 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.
2026-10-24 05:43:13 +02:00
- `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` .
2026-10-24 04:36:42 +02:00
- Session and memory `labels` / `metadata` filters beyond a passthrough string.
- Token refresh is the caller's job (foundation gap).