Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
f6fbf00
The Python SDK ships a Google ADK memory service
zlareb1 Nov 15, 2026
5a3ca95
ADK delete_memory deletes only its own app's row; save each turn once
zlareb1 Nov 15, 2026
2d0d314
One LoomMemoryService serves one ADK app in its namespace
zlareb1 Nov 15, 2026
594be30
The ADK service sends the session, keys add_memory by user, and gives…
zlareb1 Nov 16, 2026
bb7662f
The ADK docs say extraction runs under the session and only memories …
zlareb1 Nov 16, 2026
ffb4458
The ADK service refuses events without a session; tests pin the sessi…
zlareb1 Nov 16, 2026
b5319ee
The ADK tests check the import error, the real Agent's requests and t…
zlareb1 Nov 16, 2026
1f6efc5
The ADK service refuses a user_id that names no Loom user, and its do…
zlareb1 Nov 16, 2026
b5a96a0
The ADK service extracts under a per-user Loom session; tests read th…
zlareb1 Nov 16, 2026
01dd5df
The ADK service ids a long value's passage by its memory, skips a del…
zlareb1 Nov 16, 2026
6ba72f1
A conversation's passage keeps no id: deleting the fact it names leav…
zlareb1 Nov 16, 2026
f3cb198
The ADK docs say a rewound turn's passages stay until erasure
zlareb1 Nov 16, 2026
6685e09
The ADK service reads a zoneless timestamp as local time; a test keep…
zlareb1 Nov 16, 2026
7c26884
The ADK service sends a long session in batches of 400 and digests ev…
zlareb1 Nov 16, 2026
b4dd422
The SDK reference names add_memory for the ADK service
zlareb1 Nov 16, 2026
b26a45e
An ADK entry id names the memory's key and session, so a delete reach…
zlareb1 Nov 16, 2026
5cdd072
The ADK service accepts only the two-string ids it returns; the share…
zlareb1 Nov 16, 2026
ea226b9
The ADK example runs a turn; tests delete a key held in two sessions …
zlareb1 Nov 16, 2026
47c9909
A unit test pins the session in a fact's entry id and the delete it s…
zlareb1 Nov 16, 2026
b8c097e
Two ADK comments say what they mean
zlareb1 Nov 16, 2026
ef3d82b
The ADK docs say a delete does not refuse a fact and an entry without…
zlareb1 Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ test-integration:
# may pin one package incompatibly. SDK_ADAPTERS_RESOLUTION=lowest-direct installs
# every direct requirement (the SDK's own, the extra's, pytest) at its lower bound.
# mypy is the [dev] pin. `make test-sdk-adapter-crewai` runs one.
SDK_ADAPTER_EXTRAS := langchain llamaindex openai-agents crewai autogen pydantic-ai ag2
SDK_ADAPTER_EXTRAS := langchain llamaindex openai-agents crewai autogen pydantic-ai ag2 google-adk
SDK_ADAPTERS_VENV ?= .venv-sdk-adapters
SDK_ADAPTERS_PYTHON ?= 3.12
SDK_ADAPTERS_RESOLUTION ?= highest
Expand Down
79 changes: 79 additions & 0 deletions docs/features/integrations/frameworks.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ or needs another database, vector store or cache.
| CrewAI | `LoomCrewMemory` | Python, `loom.integrations.crewai` | `crewai.memory.Memory` |
| AutoGen | `LoomMemory` | Python, `loom.integrations.autogen` | `autogen_core.memory.Memory` |
| AG2 | `LoomRecallPolicy`, `loom_tools` | Python, `loom.integrations.ag2` | `ag2.assembly.AssemblyPolicy`, `tool()` from `ag2.tools` |
| Google ADK | `LoomMemoryService` | Python, `loom.integrations.google_adk` | `google.adk.memory.BaseMemoryService` |
| Pydantic AI | `loom_toolset` | Python, `loom.integrations.pydantic_ai` | `FunctionToolset` |
| Mastra | `loomTools` | TypeScript, `@clickhouse/loom/integrations/mastra` | `createTool` from `@mastra/core` |
| AI SDK | `loomTools` | TypeScript, `@clickhouse/loom/integrations/ai-sdk` | `tool()` from `ai` |
Expand Down Expand Up @@ -342,6 +343,81 @@ trimming policy (`SlidingWindowPolicy`, `TokenBudgetPolicy`), which can cut the
request out of the events the policy reads. Those policies trim events, not the prompt, so
`top_k` is what bounds the memory block.

## Google ADK

`LoomMemoryService` implements ADK's `BaseMemoryService`, which a `Runner` takes as
`memory_service=`. ADK's own memory tools read it: `preload_memory` searches with the
user's message before each model call and adds the matches to the prompt, and
`load_memory` lets the model search. A callback saves each turn. Install with
`pip install 'clickhouse-loom[google-adk]'` (`google-adk` 2.14 or later 2.x).

```python
from google.adk.agents import LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools import preload_memory
from google.genai import types
from loom import Agent
from loom.integrations.google_adk import LoomMemoryService


async def save_turn(ctx):
turn = [e for e in ctx.session.events if e.invocation_id == ctx.invocation_id]
await ctx.add_events_to_memory(events=turn)


async with Agent(org="acme", namespace="support") as loom_agent:
sessions = InMemorySessionService()
runner = Runner(
app_name="support",
agent=LlmAgent(
name="assistant",
model="gemini-flash-latest",
tools=[preload_memory],
after_agent_callback=save_turn,
),
session_service=sessions,
memory_service=LoomMemoryService(loom_agent, app_name="support"),
)
session = await sessions.create_session(app_name="support", user_id="alice")
message = types.Content(role="user", parts=[types.Part(text="I prefer aisle seats")])
async for event in runner.run_async(
user_id="alice", session_id=session.id, new_message=message
):
...
```

ADK scopes memory by app and user. Loom's boundary is the namespace: a Loom write that
matches a memory of the namespace merges into it, whichever agent wrote that memory, so two
apps sharing a namespace would share and lose memories. A service therefore serves one ADK
app, named by `app_name`, in the namespace of its Loom agent, and refuses a call for
another app; give each app its own namespace and service. The ADK user is the Loom
`user_id`; an empty or `-` user, which names no user in Loom, raises `ValueError`.
Extraction runs under a Loom session derived from the user and the ADK session (`adk-`
and a digest of the pair): Loom files a turn's verbatim chunks by session alone, and ADK
makes a session id unique per user only. A search reads all of the user's memories in the
namespace, from every session.

| ADK | Loom |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add_session_to_memory` | the text of the session's events, without the ones a rewind took back, sent to `memory.set_from_messages` (400 messages a call, the op's cap); Loom extracts the facts and resolves duplicates and conflicts. A session added again is extracted again, so a callback that runs every turn, as `after_agent_callback` does, saves that turn's events, as in the example |
| `add_events_to_memory` | the same for the events given, such as the latest turn; a call without a `session_id` raises `ValueError`, since Loom files a turn's verbatim chunks by session. 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](../memory/retention-and-erasure.md) removes them |
| `add_memory` | one `memory.set` per entry with text (an entry without text is skipped) under `<key_prefix>/<first 20 hex of sha256(user and text)>`, its `timestamp` as the memory's `valid_at` when it is ISO 8601 (one without a zone is read as local time, as ADK writes its own) |
| `search_memory` | `memory.search` of the user's memories; with `honour_abstain`, leaves out memories below Loom's floor and returns nothing when Loom abstains; each entry's `custom_metadata` carries `similarity` and `source`, and its `timestamp` is `valid_at` when the row has one |
| `delete_memory` | `memory.delete` of the memory the entry's `id` names: the JSON pair of its key and its session, since users share extracted keys and a key alone finds the key's newest row, which can be another user's, and then deletes nothing. A verbatim passage or a session summary has no `id`: a conversation's passage outlives the facts extracted from it, and [erasure](../memory/retention-and-erasure.md) removes it; a call without an id does nothing, as in ADK's own memory service. A delete removes the fact, it does not refuse it: adding its session again extracts it again (the per-turn callback adds each turn once), and [`blacklist.add`](../memory/conflicts-and-refusal.md#refusal-the-blacklist) refuses it |

Events keep their text parts only: the model's thoughts and tool calls and results are not
sent, and neither is `custom_metadata` or an entry's `author` and `id`.

| `LoomMemoryService` argument | Default | Effect |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `agent` | required | the `loom.Agent` the service calls; ADK awaits its memory service, so a `SyncAgent` is refused |
| `app_name` | required | the ADK app the service serves; a call for another app raises `ValueError` |
| `top_k` | 10 | memories per search, from 1 to 500 |
| `honour_abstain` | `True` | leave out memories below Loom's floor; nothing when Loom abstains |
| `defer` | `True` | queue the extraction on the server instead of waiting for it |
| `key_prefix` | `adk` | the prefix of `add_memory`'s keys; an empty one is refused |

## Pydantic AI

Pydantic AI extends an agent through tools and toolsets. `loom_toolset` returns Loom's
Expand Down Expand Up @@ -550,6 +626,9 @@ client can speak for several agents.
silent.
- **An AG2 turn fails when Loom is unreachable.** `LoomRecallPolicy` runs before each
model call of the turn, and `AssemblerMiddleware` does not catch a policy's error.
- **ADK carries on without memory when `preload_memory`'s search fails.** It logs a
warning and the model call goes on; a failed `load_memory` search or save callback fails
the run.
- **An AutoGen turn fails when Loom is unreachable.** `AssistantAgent` calls
`update_context` once per turn, before its first model call, and does not catch its
errors.
Expand Down
Loading