Repository navigation
Conversation
9 tasks done
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
force-pushed
the
feat/sdk-google-adk
branch
from
November 16, 2026 04:57
1a5005d to
1f6efc5
Compare
…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>
…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>
This was referenced Nov 16, 2026
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 was referenced Nov 16, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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):
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'spreload_memoryandload_memorytools 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
Runnertakes asmemory_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):
(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 agenttraveland then under agentbillingcomes back for the second write asconflict_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. SoLoomMemoryService(agent, app_name=...)serves one app, the namespace of its Loom agent, and every method refuses anotherapp_namewith aValueErrorthat says to give each app its own namespace and service. The rows carry the Loom agent's own identity. The ADK user is the Loomuser_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_chunksis 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_memorywithout asession_id(ADK's interface allowsNone; ADK's callback context always passes one) raisesValueError. A search sends no session and reads all of the user's memories in the namespace.add_session_to_memory/add_events_to_memorysend the text of the events tomemory.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 publicgoogle.adk.events.get_active_events, for a saved session and for the events given toadd_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=Trueby default queues the extraction, the hot-path choice. A session added again is extracted again, and ADK runsafter_agent_callbackevery turn, so the documented callback saves that turn's events (add_events_to_memorywith the events ofctx.invocation_id) and a session of n turns is extracted once per turn, not 1+2+…+n times.add_memorywrites onememory.setper 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), itstimestampasvalid_atwhen it is ISO 8601 (ADK allows any text there; other text leavesvalid_atunset; one without a zone is read as local time, as ADK formats its own entries' timestamps).search_memorypinsnamespace_scope="this",bodies="full",explain=False, dropsbelow_thresholdrows before thetop_kcut and returns nothing on abstain (The LangChain and Strands memory adapters leave out memories below Loom's floor #643's rules).delete_memoryismemory.deleteof the memory the entry'sidnames, 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 returnedFalseand 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 raisesValueError. 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'sidis its key and session, and a chunk or a summary hasidNone; erasure removes those. A chunk is not given the key in itsparent_memory_keyeither: 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'sdelete_memorypromises.delete_memorywith no id returns without a call, as ADK's ownInMemoryMemoryServicedoes. 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 toblacklist.add.custom_metadata, and an entry'sauthorandid, are not kept. ASyncAgentis refused with aTypeError: ADK awaits its memory service. An ADKuser_idthat names no Loom user (empty or-) is refused with aValueErrorby 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 emptyapp_name,top_koutside 1–500 and an emptykey_prefixare refused.Runner:preload_memorycatches a failed search, logs a warning and goes on without memory; a failedload_memorysearch 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]pinsgoogle-adk>=2.14,<3(2.14 hasget_active_eventsand the service'sadd_memoryanddelete_memory; ADK is semver past 1.0) and joinsSDK_ADAPTER_EXTRAS.Scope and risk
SDK-only: one module, an extra, docs. No server, wire or schema change, and
uv.lockis unchanged.Compatibility, rollout and rollback
Tests
sdk/python/tests/test_google_adk.pythroughmake test-sdk-adapter-google-adk(24 tests;mypy --stricton the module): it is aBaseMemoryService; an ADKRunnerwith a scripted model andpreload_memorysends 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; anafter_agent_callbackthat 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 toadd_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 thetop_kcut;add_memory's keys (another user's key differs) andvalid_at, and novalid_atfor a non-ISO timestamp; ids for facts only, carrying the row's session ([key, session], whichdelete_memorysends back),Nonefor chunks (with or without a parent key) and summaries;delete_memory's call with the key and session, no call without an id, and aValueErrorfor an id that is not a pair of strings; the Loom session differs per user and fora/b+cversusa+b/c;defer=Falsereachesset_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 realAgentpostsmemory.search,memory.set_from_messages(with the user and session),memory.setandmemory.delete(with the key, user and session) with the pinned fields;SyncAgent, an emptyapp_name,top_k0 / 501 and an emptykey_prefixrefused.SDK_ADAPTERS_RESOLUTION=lowest-directon Python 3.11 (google-adk 2.14.0).tests/integration/test_sdk_google_adk_memory.pyagainst a local server (fake LLM and embedder): a turn the documented callback saves is extracted (its fact polled throughsearch_memorywith the suite'seventually) andpreload_memoryputs it in a later session's prompt, another user finds nothing, and the extracted facts are deleted by the ids a search returns; anadd_memoryentry is found and its row carries the text, the Loom agent, the user, no session, typesemantic, source classasserted, no tags, thevalid_atand the token's subject asactor, 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 keychunk:<session>:0and 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_execfailed 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_memoryandload_memoryagainst google-adk 2.14.1 source, runs through ADK'sRunner, 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 typecheckandmake test-unitpass (locally the named unit tests; the full suite in CI'spytest unitparts); the integration suite passes if server behaviour changed.docs/reference/configuration.mdand thedocs/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).main; no merged migration is edited.hooks/,lib/,bin/,skills/,.mcp.json, the Codexplugin-defaults.json) bumps both plugin manifests' version, and no other open PR uses that version.npm --prefix frontend run build) and its tests pass, iffrontend/changed.docs/describe the system as it now is, and this description names any operator steps and wire changes.tests/unit/test_public_copy.py).git commit -s), as CONTRIBUTING.md asks.🤖 Generated with Claude Code