Skip to content

The Python SDK ships a Google ADK memory service - #696

Open
zlareb1 wants to merge 21 commits into
mainfrom
feat/sdk-google-adk
Open

zlareb1 wants to merge 21 commits into
mainfrom
feat/sdk-google-adk

Conversation

@zlareb1

@zlareb1 zlareb1 commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Depends on: #701 (a write that names its user is judged against that user's rows only; without it, a namespace-wide token can fold one ADK user's memory into another user's row)
Related: #655 (the AutoGen memory, the same shape)
Related: #653 (the CrewAI memory, which also extracts through memory.set_from_messages)

Changelog category (leave one):

  • New Feature

Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes):

The Python SDK ships LoomMemoryService, a Google ADK memory service: ADK's preload_memory and load_memory tools read Loom, and a saved session or turn is extracted into Loom memories (pip install 'clickhouse-loom[google-adk]').

Why

ADK agents reach Loom today only through raw SDK calls or MCP. ADK's memory is a service a Runner takes as memory_service= (google.adk.memory.BaseMemoryService), which its own tools and callbacks call. This PR implements that service over the SDK. The data stays in the user's Loom deployment: no store, vector database or cache is added.

Design (interfaces read from google-adk 2.14.1):

  • Scope: one ADK app per service and per namespace. ADK scopes memory by (app_name, user_id); Loom's boundary is the namespace, and the agent is authorship, not a boundary. Narrowing by agent does not isolate two apps sharing a namespace. Checked against a running server: the same text saved under agent travel and then under agent billing comes back for the second write as conflict_verdict: "merge", merged_into_key = the first key, noop: true, so the second app's search, narrowed to its agent, never finds it. Extracted facts merge the same way. So LoomMemoryService(agent, app_name=...) serves one app, the namespace of its Loom agent, and every method refuses another app_name with a ValueError that says to give each app its own namespace and service. The rows carry the Loom agent's own identity. The ADK user is the Loom user_id. Extraction is sent under a Loom session derived from the pair: adk- and the first 20 hex of sha256 of the JSON [user_id, session_id], so no two (user, session) pairs share one: Loom files a turn's verbatim chunks by session alone (loom.memory_chunks is ordered by (org, namespace, session_id, …), no user), and ADK makes a session id unique per user only, so two users' sessions named alike would otherwise share chunk rows; add_events_to_memory without a session_id (ADK's interface allows None; ADK's callback context always passes one) raises ValueError. A search sends no session and reads all of the user's memories in the namespace.
  • add_session_to_memory / add_events_to_memory send the text of the events to memory.set_from_messages, each with its role and timestamp, in calls of at most 400 messages (the op's cap), where Loom extracts the facts and resolves duplicates and conflicts. Events a rewind took back are left out through ADK's public google.adk.events.get_active_events, for a saved session and for the events given to add_events_to_memory. A turn saved before a later rewind keeps its memories: the app deletes its facts by the ids a search returns, and its verbatim passages stay until erasure removes them. Text parts only: thoughts, tool calls and tool results are not sent. defer=True by default queues the extraction, the hot-path choice. A session added again is extracted again, and ADK runs after_agent_callback every turn, so the documented callback saves that turn's events (add_events_to_memory with the events of ctx.invocation_id) and a session of n turns is extracted once per turn, not 1+2+…+n times.
  • add_memory writes one memory.set per entry under <key_prefix>/<first 20 hex of sha256 of the JSON [user_id, text]> (the user is in the key because Loom files a long value's passages by key alone), its timestamp as valid_at when it is ISO 8601 (ADK allows any text there; other text leaves valid_at unset; one without a zone is read as local time, as ADK formats its own entries' timestamps).
  • search_memory pins namespace_scope="this", bodies="full", explain=False, drops below_threshold rows before the top_k cut and returns nothing on abstain (The LangChain and Strands memory adapters leave out memories below Loom's floor #643's rules).
  • delete_memory is memory.delete of the memory the entry's id names, under the ADK user. The id is the JSON pair [memory_key, session_id] of the search hit: extracted keys are concept names two users share (user_seat_preference), and a delete by key alone falls back to the key's newest row in the namespace, then refuses it when it is another user's. Checked against a running server: Alice's delete by key alone returned False and left her row active beside Bob's newer row of the key; with her session it deleted it. An id that is not such a pair of strings raises ValueError. With one app per namespace there is no other app's row to reach, and the review rounds' cross-app cases (a shared key, a long value's passages filed by key, a revision between a read and a versioned delete) do not arise. Found against a running server: a search also returns verbatim chunks (chunk:…) and session summaries (summary:…), which no key deletes. So a memory's id is its key and session, and a chunk or a summary has id None; erasure removes those. A chunk is not given the key in its parent_memory_key either: a conversation's chunk names the fact extracted from it, and a local run showed it still served after that fact's delete, so the id would not do what ADK's delete_memory promises. delete_memory with no id returns without a call, as ADK's own InMemoryMemoryService does. A delete removes the fact (Contract), it does not refuse it (Refuse): unlike ADK's in-memory service, which remembers deleted ids, adding the same session again extracts the fact again; the docs say so, point to the per-turn callback (each turn added once) and to blacklist.add.
  • custom_metadata, and an entry's author and id, are not kept. A SyncAgent is refused with a TypeError: ADK awaits its memory service. An ADK user_id that names no Loom user (empty or -) is refused with a ValueError by every method: the SDK's writes turn an empty user into - while its search sends it as given, so such a user's memories would be written where its searches cannot find them. An empty app_name, top_k outside 1–500 and an empty key_prefix are refused.
  • Failure behaviour, probed with ADK's Runner: preload_memory catches a failed search, logs a warning and goes on without memory; a failed load_memory search or save callback fails the run. The service does not catch: it is ADK's tool and callback code that decides, and the failure modes say so.
  • clickhouse-loom[google-adk] pins google-adk>=2.14,<3 (2.14 has get_active_events and the service's add_memory and delete_memory; ADK is semver past 1.0) and joins SDK_ADAPTER_EXTRAS.

Scope and risk

SDK-only: one module, an extra, docs. No server, wire or schema change, and uv.lock is unchanged.

Compatibility, rollout and rollback

  • Wire: none.
  • Operator steps: none.
  • Rollback: reverting removes the module and the extra.

Tests

  • sdk/python/tests/test_google_adk.py through make test-sdk-adapter-google-adk (24 tests; mypy --strict on the module): it is a BaseMemoryService; an ADK Runner with a scripted model and preload_memory sends the search in the user's scope and the matches reach the model's prompt; load_memory's result reaches the model's next call; an after_agent_callback that saves the session sends its turns with roles, UTC timestamps and the session id; the documented per-turn callback sends each turn once over two turns, with the session id; thoughts, tool calls and a rewound turn are left out, also among events given to add_events_to_memory; empty events send nothing; events without a session are refused; 401 events go out as calls of 400 and 1 under one Loom session; abstention, rows below the floor and the top_k cut; add_memory's keys (another user's key differs) and valid_at, and no valid_at for a non-ISO timestamp; ids for facts only, carrying the row's session ([key, session], which delete_memory sends back), None for chunks (with or without a parent key) and summaries; delete_memory's call with the key and session, no call without an id, and a ValueError for an id that is not a pair of strings; the Loom session differs per user and for a/b+c versus a+b/c; defer=False reaches set_from_messages; every method refuses another app's call and an empty or - user, and sends nothing; without google-adk the import error names the extra; a real Agent posts memory.search, memory.set_from_messages (with the user and session), memory.set and memory.delete (with the key, user and session) with the pinned fields; SyncAgent, an empty app_name, top_k 0 / 501 and an empty key_prefix refused.
  • The same tests pass with SDK_ADAPTERS_RESOLUTION=lowest-direct on Python 3.11 (google-adk 2.14.0).
  • tests/integration/test_sdk_google_adk_memory.py against a local server (fake LLM and embedder): a turn the documented callback saves is extracted (its fact polled through search_memory with the suite's eventually) and preload_memory puts it in a later session's prompt, another user finds nothing, and the extracted facts are deleted by the ids a search returns; an add_memory entry is found and its row carries the text, the Loom agent, the user, no session, type semantic, source class asserted, no tags, the valid_at and the token's subject as actor, another user's delete of its id reaches nothing, and the user's own delete removes it; and two users saving the same text each find their own memory (a contract test: on its own it does not reproduce the cross-user merge, which content-hashed keys and the fake extractor happen to avoid; A write that names its user is judged against that user's rows only #701's integration test does); two turns saved by the documented callback in one session each keep a findable verbatim passage (both turns' chunks share the key chunk:<session>:0 and each is served for its own words); a user's delete reaches their extracted fact while another user holds its key, leaving that user's (fails with a key-only delete; it runs only against the fake extractor, whose keys the two users share); a key the user holds in two sessions is served once per session, each under its own id, and deleting what the search returns leaves it unserved (checked against a running server first). 6 passed with google-adk installed, against a server with A write that names its user is judged against that user's rows only #701; without it the module skips, as in CI's integration jobs.
  • make format lint typecheck; the unit tests that name the integrations, the extras, the framework docs, doc links, public copy and agent instructions (1288 passed; test_extractor_service::test_a_child_cannot_gain_privileges_on_exec failed once in the 15-minute serial run and passes on its own, untouched by this diff); the full unit suite runs in CI.

AI assistance in the code (leave one; writing this description with AI is fine):

  • AI-generated (an agent wrote most of the diff): Claude Code. Checked: BaseMemoryService, MemoryEntry, get_active_events, preload_memory and load_memory against google-adk 2.14.1 source, runs through ADK's Runner, and the service against a running Loom.

  • I can explain every line of this diff and how it interacts with the rest of Loom.

Checklist

  • make format-check, make lint, make typecheck and make test-unit pass (locally the named unit tests; the full suite in CI's pytest unit parts); the integration suite passes if server behaviour changed.
  • Generated files are regenerated in this PR, not by hand: the SDK op tables, docs/reference/configuration.md and the docs/reference/ tables (python scripts/codegen/docs_reference.py), the reach manifest, schemas/schema.sql (make schema-dump) and the Codex plugin copies (python3 scripts/codegen/agent_plugin_sync.py).
  • A new migration is additive and numbered after the latest on main; no merged migration is edited.
  • A behaviour change to any file a plugin ships (hooks/, lib/, bin/, skills/, .mcp.json, the Codex plugin-defaults.json) bumps both plugin manifests' version, and no other open PR uses that version.
  • The frontend builds (npm --prefix frontend run build) and its tests pass, if frontend/ changed.
  • Docs under docs/ describe the system as it now is, and this description names any operator steps and wire changes.
  • Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (tests/unit/test_public_copy.py).
  • Commits are signed off (git commit -s), as CONTRIBUTING.md asks.

🤖 Generated with Claude Code

zlareb1 and others added 8 commits November 16, 2026 04:55
LoomMemoryService implements google.adk.memory.BaseMemoryService: a saved
session or turn goes to memory.set_from_messages, add_memory to memory.set,
search_memory to memory.search scoped to the ADK app (the Loom agent) and
user, and delete_memory to memory.delete. Installed as the google-adk extra.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
delete_memory reads the version under the exact app and user and deletes
that version, since memory.delete falls back to any agent's row of the key.
Rows carry no session, so the exact identity addresses them. The example
saves each turn's events instead of the whole session every turn. A non-ISO
timestamp leaves valid_at unset; an empty key_prefix is refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
Loom merges a write into a matching memory of the namespace whichever agent
wrote it, so narrowing by agent cannot isolate two ADK apps in one namespace:
the second app's write merges into the first's row and its search misses it.
The service now takes app_name and refuses another app's calls; rows carry the
Loom agent's identity, and delete_memory is memory.delete again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
… only memories a deletable id

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…carry an id

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…on and the stored row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…wo users' memories

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…cstring points at the docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
@zlareb1
zlareb1 force-pushed the feat/sdk-google-adk branch from 1a5005d to 1f6efc5 Compare November 16, 2026 04:57
…e actor and poll search, not turns

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
zlareb1 and others added 2 commits November 16, 2026 05:34
…ete without an id, and digests its Loom session

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…es it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
zlareb1 and others added 9 commits November 16, 2026 05:42
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…s each per-turn passage findable

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…ery key one way

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…es the user's own row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…d-key test needs the fake extractor

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…and wait for a shared key

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…ends

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
… text is skipped; the real-Agent test drives delete

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant