Files
moloapp/src/google/sessions/SPEC.md
T
retoorandClaude Sonnet 5.5 438e737ffb docs(clients): document the activation page of every Google API and each vendor key page
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>
2026-10-25 08:02:50 +01:00

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 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).

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.