Agent frameworks and orchestrators
The SDKs ship adapters that present Loom through a framework’s own memory or retrieval
interface. An adapter needs its framework: in Python, the SDK extra its section names;
in TypeScript, the framework package, an optional peer dependency. The LangGraph and
Strands adapters import without their framework. Identity comes from the Loom Agent the adapter wraps, and isolation is
Loom’s namespace authorization. Every adapter calls your Loom server through the SDK: the
data is stored in your Loom deployment (ClickHouse, and Postgres for live memory under the
Postgres memory authority), and no adapter adds
or needs another database, vector store or cache.
| Framework | Adapter | SDK | Framework interface |
|---|---|---|---|
| LangChain | LoomKnowledgeRetriever, LoomMemoryRetriever |
Python, loom.integrations.langchain |
BaseRetriever |
| LangChain.js | LoomKnowledgeRetriever, LoomMemoryRetriever |
TypeScript, @clickhouse/loom/integrations/langchain |
BaseRetriever from @langchain/core |
| LlamaIndex | LoomRetriever, LoomMemoryBlock |
Python, loom.integrations.llamaindex |
BaseRetriever, BaseMemoryBlock |
| OpenAI Agents SDK | loom_tools, LoomSession |
Python, loom.integrations.openai_agents |
FunctionTool, the Session protocol |
| OpenAI Agents SDK (TypeScript) | loomTools, LoomSession |
TypeScript, @clickhouse/loom/integrations/openai-agents |
tool() from @openai/agents, Session |
| 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 |
| Claude API memory tool | LoomMemoryTool, AsyncLoomMemoryTool |
Python, loom.integrations.claude_memory |
BetaAbstractMemoryTool, BetaAsyncAbstractMemoryTool from anthropic |
| Claude API memory tool | loomMemoryTool |
TypeScript, @clickhouse/loom/integrations/claude-memory |
betaMemoryTool from @anthropic-ai/sdk |
| Microsoft Agent Framework | LoomContextProvider |
Python, loom.integrations.agent_framework |
agent_framework.ContextProvider |
| Google ADK | LoomMemoryService |
Python, loom.integrations.google_adk |
google.adk.memory.BaseMemoryService |
| Google ADK (TypeScript) | LoomMemoryService |
TypeScript, @clickhouse/loom/integrations/google-adk |
BaseMemoryService from @google/adk |
| Pydantic AI | loom_toolset |
Python, loom.integrations.pydantic_ai |
FunctionToolset |
| Mastra | loomTools, LoomMemoryStorage |
TypeScript, @clickhouse/loom/integrations/mastra |
createTool, MemoryStorage from @mastra/core |
| AI SDK | loomTools |
TypeScript, @clickhouse/loom/integrations/ai-sdk |
tool() from ai |
| n8n | Loom Chat Memory, Loom | @clickhouse/n8n-nodes-loom |
AI Memory sub-node and action/tool node |
| LangGraph | LoomStore |
Python, loom.integrations.langgraph |
BaseStore |
| Strands Agents | LoomMemoryStore |
Python, loom.integrations.strands |
the MemoryStore protocol |
| Strands Agents | LoomMemoryStore |
TypeScript, @clickhouse/loom/integrations/strands |
the same protocol, structurally |
| Pipecat | LoomMemoryService |
Python, loom.integrations.pipecat |
recall and capture FrameProcessors |
| Dify | Remember, Recall, Search knowledge | integrations/dify standalone plugin |
Native Dify tools |
| Haystack | LoomDocumentStore, LoomRetriever |
Python, loom.integrations.haystack |
DocumentStore protocol, retrieval component |
| Agno | LoomMemoryDb |
Python, loom.integrations.agno |
BaseDb user-memory methods |
| Langflow | Loom | integrations/langflow custom component |
Langflow Component |
| DSPy | LoomKnowledgeRetriever, LoomMemoryRetriever |
Python, loom.integrations.dspy |
a retriever callable returning dspy.Prediction, dspy.Tool |
Any other framework that can call an HTTP endpoint or an MCP server uses Loom directly: see agent integration and MCP clients.
LangChain
LoomKnowledgeRetriever searches the namespace’s documents (knowledge.search) and
LoomMemoryRetriever its memories (memory.search). Both are LangChain BaseRetrievers,
so they work with invoke, in a chain, and as an agent tool through
create_retriever_tool. Install with pip install 'clickhouse-loom[langchain]==1.3.0'
(langchain-core 1.x).
from loom import Agent, SyncAgent
from loom.integrations.langchain import LoomKnowledgeRetriever, LoomMemoryRetriever
with SyncAgent(org="acme", namespace="support") as agent:
docs = LoomKnowledgeRetriever(agent=agent, k=3).invoke("refund policy for annual plans")
async with Agent(org="acme", namespace="support") as agent:
memories = await LoomMemoryRetriever(agent=agent, user_id="alice").ainvoke("seat preference")
invoke needs a SyncAgent; ainvoke takes an Agent or a SyncAgent.
The Python retrievers retain their bound and ambient SessionProtection contributors at
construction and on each callback, including after client rebinding and across worker
threads. When the caller enters family.automatic(), retained protection also guards
automatic retrieval; without that context, direct retrieval and retriever tools stay
explicit and observe responses. A mirrored result marks all retained families before
documents return. A failed durable mark withholds the documents, and a marked family
blocks later automatic retrieval. Use separate retrievers for independent conversation
families.
| Retriever | page_content |
id |
metadata |
|---|---|---|---|
LoomKnowledgeRetriever |
the chunk | <namespace>/<source_uri>#<chunk_idx> |
source_uri, chunk_idx, similarity, section, namespace, tags |
LoomMemoryRetriever |
the memory text | none: a key is unique per agent, user and session, and a search reads every agent’s | namespace, memory_key, memory_type, similarity, source, valid_at when the row has one |
| Field | Retriever | Default | Effect |
|---|---|---|---|
k |
both | 4 | documents per query |
search_tags |
both | none | only rows carrying at least one of these Loom tags (tags is LangChain’s own field) |
uri_prefix |
knowledge | none | only documents whose source_uri starts with one of these |
namespace_scope |
knowledge | this |
all_mine adds the caller’s other namespaces, up to the server’s fan-out cap |
search_kwargs |
knowledge | none | further knowledge.search fields, such as search_mode or rerank |
memory_type |
memory | every searchable type except reflection |
only memories of this type |
user_id, session_id, run_id, agent_id |
memory | none | only that user’s, session’s, run’s or agent’s memories |
honour_abstain |
memory | True |
leave out memories below Loom’s floor; no documents when Loom abstains |
A LangChain agent built with create_agent runs on LangGraph: pass LoomStore (below)
as its store for long-term memory.
Install the TypeScript SDK and its framework peer with
npm install @clickhouse/loom@1.3.0 '@langchain/core@^1.0.0'.
The TypeScript retrievers extend BaseRetriever from @langchain/core and take the same
options in camelCase, with the memory retriever’s user, session, run and agent in one
scope:
import {
LoomKnowledgeRetriever,
LoomMemoryRetriever,
} from "@clickhouse/loom/integrations/langchain";
const docs = await new LoomKnowledgeRetriever(agent, { k: 3 }).invoke("refund policy");
const memories = await new LoomMemoryRetriever(agent, { scope: { userId: "alice" } }).invoke(
"seat preference",
);
LlamaIndex
LoomRetriever searches the namespace’s documents (knowledge.search) as a LlamaIndex
BaseRetriever, for a query engine, a chat engine or a retriever tool. LoomMemoryBlock
is a long-term memory block for LlamaIndex’s Memory. Install with
pip install 'clickhouse-loom[llamaindex]==1.3.0' (llama-index-core 0.14).
from llama_index.core.memory import Memory
from loom import SyncAgent
from loom.integrations.llamaindex import LoomMemoryBlock, LoomRetriever, flush
with SyncAgent(org="acme", namespace="support") as agent:
nodes = LoomRetriever(agent, similarity_top_k=3).retrieve("refund policy")
memory = Memory.from_defaults(
session_id="s-42", memory_blocks=[LoomMemoryBlock(agent=agent, user_id="alice")]
)
... # the session's turns go through memory.put / memory.get
flush(memory) # at the session's end: hand the rest of the window to the blocks
retrieve (and a sync query engine) needs a SyncAgent; aretrieve takes an Agent or
a SyncAgent. A node’s text is the chunk, its id <namespace>/<source_uri>#<chunk_idx>,
its score the similarity, and its metadata source_uri, chunk_idx, section (when
the chunk has one), namespace and tags, of which only source_uri and section reach
the text a synthesizer sends the model. A query engine takes the retriever with
RetrieverQueryEngine.from_args(LoomRetriever(agent), llm=...) and the LLM you use.
LoomRetriever argument |
Default | Effect |
|---|---|---|
similarity_top_k |
4 | nodes per query |
tags |
none | only chunks carrying any of these Loom tags |
uri_prefix |
none | only documents whose source_uri starts with one of these |
namespace_scope |
this |
all_mine adds the caller’s other namespaces, up to the server’s fan-out cap |
search_kwargs |
none | further knowledge.search fields, such as search_mode or rerank |
Memory keeps the recent messages itself and hands the block the ones that leave its
short-term window, which by default is 70% of a 30,000-token limit; a shorter session hands
it nothing. Call await aflush(memory) (flush(memory) from sync code), both from
loom.integrations.llamaindex, when a session ends: like Memory’s own hand-over, it gives
what is still in the window to every block of that Memory and then archives it, so the
window starts empty. If a block fails, nothing is archived and the next flush hands the same
messages over again. The block’s two calls:
aputsends the user and assistant turns tomemory.set_from_messagesunder theMemory’s session id; Loom extracts the facts worth keeping and resolves duplicates and conflicts with what it already holds. Withdefer(the default) the server queues the extraction, so a flush is one request and an extraction failure does not fail the turn.agetsearches the block’s namespace, across every agent writing to it, with the latest user message and returns the matching memories, one line each, whichMemoryplaces in the system message. It leaves out memories below Loom’s floor, and returns nothing when Loom abstains.
LoomMemoryBlock field |
Default | Effect |
|---|---|---|
agent |
required | the Agent or SyncAgent the block reads and writes through |
top_k |
5 | memories per read |
tags |
none | stamped on extracted memories; reads keep memories carrying any of them |
user_id |
none | the end user the memories belong to; unset, reads every user’s memories in the namespace |
honour_abstain |
True |
leave out memories below Loom’s floor; nothing when Loom abstains |
defer |
True |
queue the extraction on the server; False extracts inline whatever the operator’s defer list says |
name, priority |
LoomMemories, 0 |
LlamaIndex’s block name and truncation priority (0: never truncated) |
Give the block a SyncAgent when Memory is used through its sync methods (get, put)
or flush is called, which may run a call on another event loop than the one an Agent
was opened on; an Agent serves aget and aput on its own loop. Memory keeps its
short-term messages in its own chat store (in process by default); only what the block
receives reaches Loom.
Wrap automatic callbacks in the application’s SessionProtection.automatic() scope.
The retriever and memory block retain the families bound at construction and contributed
by earlier callbacks, including across client rebinding and sync worker threads. A
mirrored recall marks those families before returning. Later automatic calls refuse
protected work; explicit calls keep their response observers without becoming automatic.
aflush retains each Loom block’s contributors before reading the native buffer. A
refused flush raises and leaves that window active for retry, without archiving it or
acknowledging an unsent extraction. The native framework owns its overflow archival;
aflush does not roll it back.
Haystack
LoomDocumentStore implements Haystack 3.5’s DocumentStore protocol, and
LoomRetriever is a native retrieval component over Loom knowledge search. Install
pip install 'clickhouse-loom[haystack]==1.3.0' (haystack-ai>=3.5,<3.6).
from haystack import Document, Pipeline
from haystack.components.writers import DocumentWriter
from loom.integrations.haystack import LoomDocumentStore, LoomRetriever
store = LoomDocumentStore("acme", "support")
DocumentWriter(store).run(
documents=[Document(id="travel", content="Boarding starts 30 minutes before departure.")]
)
pipeline = Pipeline()
pipeline.add_component("recall", LoomRetriever(store, top_k=5))
result = pipeline.run({"recall": {"query": "When does boarding start?"}})
Set LOOM_BASE_URL and LOOM_API_KEY for the deployment. The token is a Haystack
Secret referencing the environment by default, so to_dict and pipeline exports
carry the variable name. A token supplied with Secret.from_token works at runtime
but Haystack refuses to serialize it. The store accepts base_url=, api_key=,
agent= (default haystack) and store= (default default). Explicit endpoint URLs
cannot contain credentials, query strings or fragments.
Each store maps a document id to a hashed URI under its own haystack:// prefix and
marks its rows with a store tag. Native document serialization preserves ids,
metadata, embeddings and binary fields in Loom’s original-file bytes; text is indexed
for search. A document without text indexes its id. Data stays in the user’s Loom
deployment, with no additional database, vector store or cache. Documents are shared
by the namespace; use separate namespaces and scoped tokens for untrusted apps.
The store implements count, full-document filtering, writes with Haystack duplicate
policies and deletion. DuplicatePolicy.NONE has the same behavior as FAIL.
Filters use Haystack’s native nested comparison and logic predicates over the full
stored documents. Counting and filtering list and hydrate the store, so large stores
incur a full read. Missing ids raise MissingDocumentError; writes and batched
deletions can partially finish when a request fails. Concurrent writes can return a
conflict from Loom; duplicate checks are not a transaction across writers.
The retriever accepts top_k from 1 to 100 and search_mode of hybrid (default),
semantic or lexical. It searches only this store in this namespace, then hydrates
full documents and removes repeated chunk hits. Results are ranked by their first
matching chunk among at most 100 candidates; repeated chunks or concurrent deletions
can leave fewer than top_k documents. Use Haystack’s native FilterRetriever over
the same store when filtering all documents instead of ranking a query.
Haystack’s trusted-module policy also applies to serialized pipelines. Loading a
pipeline containing this adapter requires the application to trust the installed
loom.integrations.haystack module according to Haystack’s configuration. The adapter
does not change that policy or register trust automatically. A pipeline constructed
directly from the imported component works as in the example.
DSPy
LoomKnowledgeRetriever searches the namespace’s documents (knowledge.search) and
LoomMemoryRetriever its memories (memory.search). Each is a retriever callable, the
shape of DSPy’s own dspy.retrievers.Embeddings: a program calls it in forward and gets
a dspy.Prediction whose passages are the texts, with sources, scores and
metadata in the same order, so the program can cite what it used. as_tool() hands the
same search to dspy.ReAct. From the root of the Loom checkout that supplies this
guide, install with pip install './sdk/python[dspy]' (dspy 3.5.x).
import dspy
from loom import SyncAgent
from loom.integrations.dspy import LoomKnowledgeRetriever, LoomMemoryRetriever
class Answer(dspy.Module):
def __init__(self, search: LoomKnowledgeRetriever) -> None:
super().__init__()
self.search = search
self.respond = dspy.ChainOfThought("context, question -> answer")
def forward(self, question: str) -> dspy.Prediction:
found = self.search(question)
return self.respond(context=found.passages, question=question)
with SyncAgent(org="acme", namespace="support") as agent:
answer = Answer(LoomKnowledgeRetriever(agent, k=3))(question="Do annual plans refund?")
react = dspy.ReAct(
"question -> answer",
tools=[LoomMemoryRetriever(agent, user_id="alice").as_tool()],
)
A call needs a SyncAgent; await retriever.acall(query) takes an Agent or a
SyncAgent. Pass k= to a call to override the retriever’s own for that search.
The adapter does not use dspy.configure(rm=...) and dspy.Retrieve: DSPy 3.5’s
Retrieve keeps only each passage’s long_text, so the sources would be lost, and its
own retrievers (dspy.retrievers.Embeddings) are plain callables that a program calls or
hands to dspy.ReAct as a tool.
| Retriever | passage | source | metadata |
|---|---|---|---|
LoomKnowledgeRetriever |
the chunk | <namespace>/<source_uri>#<chunk_idx> |
source_uri, chunk_idx, similarity, section, namespace, tags |
LoomMemoryRetriever |
the memory text | <namespace>/<memory_key> |
namespace, memory_key, memory_type, similarity, source, valid_at when the row has one |
scores is each hit’s similarity, rounded to four places. The retrievers take the same
search fields as the LangChain retrievers above (k, default 3, search_tags,
uri_prefix, namespace_scope, search_kwargs; memory_type, user_id, session_id,
run_id, agent_id, honour_abstain). When Loom abstains, LoomMemoryRetriever
returns no passages unless honour_abstain=False. A search error is raised, not turned
into an empty result. Session protection works as for the LangChain retrievers.
as_tool() returns a dspy.Tool named loom_search_documents or
loom_search_memories (pass name= to rename it) that returns one [source] passage
line per hit. With a SyncAgent the tool is sync; with an Agent it is async, for
dspy.ReAct’s acall.
OpenAI Agents SDK
loom_tools returns Loom’s agent verbs as the OpenAI Agents SDK’s FunctionTools, so the
model keeps and reads long-term memory in Loom during a run. Install with
pip install 'clickhouse-loom[openai-agents]' (openai-agents 0.24).
from agents import Agent as OpenAIAgent, Runner
from loom import Agent
from loom.integrations.openai_agents import loom_tools
async with Agent(org="acme", namespace="support") as loom_agent:
assistant = OpenAIAgent(
name="assistant",
instructions="Recall what you know about the user before answering.",
tools=loom_tools(loom_agent, user_id="alice"),
)
result = await Runner.run(assistant, "Book my usual seat to Lisbon")
The tools are Loom’s AgentTools
(sessions and tools): loom_remember
(memory.set), loom_recall (memory.search), loom_ask (memory.ask), loom_offload
and loom_fetch (context.offload, context.fetch) and loom_note
(working_memory.append), with the same schemas and results in both SDKs. user_id,
session_id and run_id bind every call to one scope; only=[...] keeps a subset and
max_result_chars (8,000 by default) caps what a call returns (loom_recall leaves out
its lowest-ranked memories whole to fit, counted in omitted). The schemas have optional
parameters, so the tools are not strict. A call Loom refuses (a missing argument, a
rejected value, a server error) returns <tool> failed: <message> to the model, which can
correct the call; the run goes on.
LoomSession is the OpenAI Agents SDK’s Session over Loom: a run given it reads and
extends the conversation history of one session there. Every process whose Loom agent has
the same name reads the same Python history for the same session id and user, and a
handoff between agents of one run keeps it. Python and TypeScript histories are separate
because the frameworks use different item formats.
Bind the application’s existing protection family before constructing either native session. The instance retains constructor and callback client families, including after rebinding. Python also retains contributors active in the callback’s context. Use one instance per logical conversation family; restore it with the same application-owned protection capsule. The native user and session ids select history, without establishing protection authority. History reads and additions are automatic work: a marked reply protects every contributor before returning and suppresses later automatic calls. An initial complete history reply may return; follow-up pages, hydration and batch writes stop. Explicit pop, clear and model-selected tools remain available, with reply observation retained for the session’s manual deletions.
from loom.integrations.openai_agents import LoomSession
session = LoomSession(loom_agent, "trip-42", user_id="alice")
result = await Runner.run(assistant, "Book my usual seat to Lisbon", session=session)
Session |
Loom |
|---|---|
get_items |
memory.list of the session’s items, sorted by writer-generated key; limit (or session_settings.limit) keeps the latest after scanning the history; an item the list cuts at 2,048 characters, or sends without a value, is read whole with memory.get |
add_items |
one memory.set per item, an episodic memory under <key_prefix>/<nanoseconds>-<random>, the item’s JSON its value |
pop_item |
the latest item, read as get_items(limit=1) reads it, deleted with memory.delete and returned |
clear_session |
memory.delete of every item of the session |
An episodic memory is not embedded, so an item is never merged with or judged against
another row, and a repeated item stays two items (one memory.set per item, bypassing SDK
coalescing: a batch would fold a value identical to a live row). A read fails if an item
disappears before its full value can be fetched. Items are stored under a Loom session derived from
the user and the session id (oai-py- and a digest of the pair in Python, oai-ts-
in TypeScript). Keys follow writer clocks; independent writers do not share a server
sequence. Reads, pop_item and clear_session scan the whole history: server arrival
times cannot bound keys from different writer clocks. The history is the user’s:
unset, user_id writes the namespace’s shared
rows; an empty or - user raises ValueError. To keep what a conversation
established beyond its history, give the model loom_remember, or send the turns to
memory.set_from_messages.
LoomSession argument |
Default | Effect |
|---|---|---|
agent |
required | the loom.Agent the session calls |
session_id |
required | the session’s id |
user_id |
none | the end user the history belongs to |
key_prefix |
openai-agents |
the items’ key prefix |
session_settings |
the SDK’s | limit: the default number of latest items get_items returns |
In TypeScript, loomTools(agent, scope) from @clickhouse/loom/integrations/openai-agents
returns the same tools built with tool() from @openai/agents, an optional peer
dependency:
import { Agent as OpenAIAgent, run } from "@openai/agents";
import { loomTools } from "@clickhouse/loom/integrations/openai-agents";
const assistant = new OpenAIAgent({
name: "assistant",
tools: loomTools(agent, { userId: "alice" }),
});
const result = await run(assistant, "Book my usual seat to Lisbon");
new LoomSession(agent, sessionId, { userId, keyPrefix }) is the TypeScript Session, over
its native item format and separate session rows. The user is fixed when the session is
constructed. Binary image and file tool results keep their bytes and media information
when stored and read back:
import { LoomSession } from "@clickhouse/loom/integrations/openai-agents";
const session = new LoomSession(agent, "trip-42", { userId: "alice" });
const result = await run(assistant, "Book my usual seat to Lisbon", { session });
CrewAI
LoomCrewMemory is a crewai.memory.Memory, so a crew takes it as memory= and its
agents share the namespace’s memory. Set it on the Crew, not on an Agent: when CrewAI
copies a crew (kickoff_for_each, train, test) it rebuilds each agent’s memory as its
own Memory, with a local store, and keeps only the crew’s. Install with
pip install 'clickhouse-loom[crewai]==1.3.0' (crewai 1.15, Python 3.11 to 3.13).
from crewai import Crew
from loom import SyncAgent
from loom.integrations.crewai import LoomCrewMemory
with SyncAgent(org="acme", namespace="research") as agent:
crew = Crew(agents=[...], tasks=[...], memory=LoomCrewMemory(agent=agent))
crew.kickoff()
Use one LoomCrewMemory per conversation, bound to that conversation’s logical session
family. Constructor and callback contributors remain bound after client rebinding,
including contributors seen by extract_memories. Inside an application-owned automatic
scope, protected contributors refuse recall and capture before HTTP. Recalled protection
is observed before matches return to the crew. Native memory tools called outside an
automatic scope remain explicit. user_id and the native private flag do not select
session protection.
| A crew run asks memory to | Loom |
|---|---|
recall what bears on a task (recall) |
memory.search of the namespace the crew writes to; nothing when Loom abstains, score is the similarity |
extract facts from a task’s output (extract_memories) |
the output, unchanged: Loom extracts on write |
save them (remember_many) |
memory.set_from_messages, deferred by default; Loom resolves duplicates and conflicts |
save one fact, from the memory tools (remember) |
one memory.set under crewai/<first 20 hex of sha256(text)>; a save of several items goes through remember_many |
CrewAI’s own Memory analyses every save with an LLM, embeds it with its embedder and
keeps it in a local store; LoomCrewMemory needs none of them, since Loom embeds and
extracts on the server. tags and the categories of a save become Loom tags; a recall
keeps memories carrying any of tags and any of its categories; when both are given,
the categories narrow the best 5 × limit matches (at least 50, at most 500), and only
fact hits carrying one of them are kept. The scope tree, slices, record listing, update
and private records (private=True) are not offered and raise, and so do reset and
forget: Loom deletes a memory when its key is named (memory.delete) or through
erasure. scope, root_scope, metadata,
importance and source are not kept or used, and a read_only memory saves nothing.
Crews call their memory synchronously, so the adapter takes a SyncAgent. Do not
checkpoint a crew that holds this memory: CrewAI saves the memory as its own Memory and
restores that, with a local store.
| Field | Default | Effect |
|---|---|---|
agent |
required | the SyncAgent the memory calls |
user_id |
none | the end user the memories belong to; unset, recalls read every user’s memories in the namespace |
tags |
none | stamped on every save; recalls keep memories carrying any of them |
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 |
key_prefix |
crewai |
key prefix of remember’s saves |
AutoGen
LoomMemory implements AutoGen’s Memory protocol (autogen_core.memory), which an
AssistantAgent takes as memory=[...]. Install with
pip install 'clickhouse-loom[autogen]==1.3.0' autogen-agentchat (autogen-core 0.7;
AssistantAgent comes from autogen-agentchat, which the extra does not install).
from autogen_agentchat.agents import AssistantAgent
from autogen_core.memory import MemoryContent, MemoryMimeType
from loom import Agent
from loom.integrations.autogen import LoomMemory
async with Agent(org="acme", namespace="support") as loom_agent:
memory = LoomMemory(loom_agent, user_id="alice")
await memory.add(
MemoryContent(content="Alice prefers aisle seats", mime_type=MemoryMimeType.TEXT)
)
assistant = AssistantAgent("assistant", model_client=model_client, memory=[memory])
| AutoGen | Loom |
|---|---|
add |
one memory.set under autogen/<first 20 hex of sha256(text)> of the stripped text; text and JSON content, not bytes or images; metadata and mime_type are not kept |
query |
memory.search of the namespace it writes to; with honour_abstain, leaves out memories below Loom’s floor and returns nothing when Loom abstains; each result’s metadata carries memory_key, memory_type, similarity, source and valid_at when the row has one |
update_context |
once per turn, before the agent’s first model call: query with the latest user message (its text parts when multimodal), the matches added as one system message |
clear |
raises: Loom deletes a memory when its key is named (memory.delete) or through erasure |
LoomMemory argument |
Default | Effect |
|---|---|---|
agent |
required | the loom.Agent the memory calls; AutoGen awaits its memory, so a SyncAgent is refused |
user_id |
none | the end user the memories belong to; unset, a query reads every user’s memories |
tags |
none | stamped on every add; a query keeps memories carrying any of them |
top_k |
5 | memories per query, at least 1 and capped at 500 |
honour_abstain |
True |
leave out memories below Loom’s floor; nothing when Loom abstains |
key_prefix |
autogen |
the prefix of add’s keys |
An AssistantAgent holding a LoomMemory cannot be dumped with dump_component: the Loom
agent and its credential are not component config.
Bind one memory instance per conversation to its application-owned SessionProtection
family. Constructor and callback contributors remain bound across context exit and
client rebinding. update_context snapshots them before awaiting native messages and
runs as automatic work. A marked recall is durably observed before system-message
injection; later automatic work stops. Direct query and add remain explicit unless
their caller owns automatic work, while their responses still observe known families.
Native user and session ids do not select protection.
AG2
An AG2 1.3 agent gets context through assembly policies, which run before each model call,
and acts through tools. LoomRecallPolicy is a policy that adds the Loom memories matching
the latest user message to the prompt, and loom_tools returns Loom’s agent verbs as AG2
tools, the same AgentTools as the OpenAI Agents SDK adapter, so the
model writes memories with loom_remember. Install with
pip install --upgrade --pre 'clickhouse-loom[ag2]' (ag2 1.3).
from ag2 import Agent as AG2Agent, Middleware
from ag2.assembly import AssemblerMiddleware
from loom import Agent
from loom.integrations.ag2 import LoomRecallPolicy, loom_tools
async with Agent(org="acme", namespace="support") as loom_agent:
recall = LoomRecallPolicy(loom_agent, user_id="alice")
assistant = AG2Agent(
"assistant",
config=config,
tools=loom_tools(loom_agent, user_id="alice"),
middleware=[Middleware(AssemblerMiddleware, policies=[recall])],
)
reply = await assistant.ask("Book my usual seat to Lisbon")
LoomRecallPolicy argument |
Default | Effect |
|---|---|---|
agent |
required | the loom.Agent the policy searches with; the policy awaits its search, so a SyncAgent is refused |
user_id |
none | the end user whose memories to read; unset, every user’s memories in the namespace |
tags |
none | keep memories carrying any of them |
top_k |
5 | memories per model call, at least 1 and capped at 500 |
honour_abstain |
True |
leave out memories below Loom’s floor; nothing when Loom abstains |
The policy runs memory.search of the namespace it is bound to before each model call of
a turn, with the text of the latest request a user sent (a framework inbox message is not
one), and adds the matches as one prompt block, or nothing. It only reads; the model
writes through loom_remember. loom_tools binds user_id, session_id and run_id to
every call and takes only=[...] and max_result_chars (8,000 by default; loom_recall
leaves out its lowest-ranked memories whole to fit, counted in omitted). A call Loom
refuses is a tool error whose text is <tool> failed: <message>, in place of the
traceback AG2 sends for an exception, and the run goes on. Put the policy before a
trimming policy (SlidingWindowPolicy, TokenBudgetPolicy), which can cut the user’s
request out of the events the policy reads. Those policies trim events, not the prompt, so
top_k is what bounds the memory block.
Use one recall policy per conversation, with its Loom client bound to the
application-owned SessionProtection family. The policy retains constructor and
callback contributors across context exit and client rebinding. Native user and session
ids do not select protection. A protected contributor stops automatic recall with
AutomaticCaptureSuppressed before dispatch. A marked recall is durably observed before
its content reaches the current prompt; later automatic recalls stop. Model-selected
loom_tools calls remain explicit operations.
Find more projects using AG2 in Build with AG2.
Microsoft Agent Framework
LoomContextProvider implements Agent Framework’s ContextProvider, which an Agent
takes in context_providers=[...]: before each run it adds the Loom memories that match
the user’s input to the run’s instructions, and after the run it sends the turn’s text to
Loom, which extracts the facts. Install with
pip install 'clickhouse-loom[agent-framework]==1.3.0'
(agent-framework-core 1.26.x). Agent Framework succeeds AutoGen; a new project
uses this provider, and the AutoGen memory stays for AutoGen projects.
from agent_framework import Agent
from loom import Agent as LoomAgent
from loom.integrations.agent_framework import LoomContextProvider
async with LoomAgent(org="acme", namespace="support") as loom_agent:
agent = Agent(
client=chat_client,
instructions="You are a helpful assistant.",
context_providers=[LoomContextProvider(loom_agent, user_id="alice")],
)
session = agent.create_session()
await agent.run("I prefer aisle seats", session=session)
The agent keeps its own conversation history: for a run given a session, with no history
provider configured and a client that does not store the conversation itself, it adds its
in-memory one beside Loom’s provider. Loom holds the memories across sessions. A caller
that passes the whole conversation to each run sends Loom only the turn after its last
assistant message. Inside an AgentLoopMiddleware loop, the turn is sent once, when the loop
ends, without the loop’s own prompts: the user’s input and every reply, or only the last reply
when the loop streams or returns its final response only. Each iteration recalls for its own
input, so after the first the memories match the loop’s prompt, not the user’s request.
| Agent Framework | Loom |
|---|---|
before_run |
memory.search with the run’s latest user message; with honour_abstain, leaves out memories below Loom’s floor and adds nothing when Loom abstains; the matches are added as one block of instructions |
after_run |
the user text of the run’s new turn and the assistant text of its response, sent to memory.set_from_messages (400 messages a call, the op’s cap), where Loom extracts the facts and resolves duplicates and conflicts; tool calls and results are not sent |
Extraction runs under a Loom session derived from the user and the Agent Framework session
(maf- and a digest of the pair): Loom files a turn’s verbatim chunks by session alone, and
a caller may choose its session ids.
With an application-owned SessionProtection bound to the Loom agent, use one
provider per logical conversation family. The provider retains constructor and callback
contributors, including ambient automatic contributors, across callbacks and client
rebinding. Native user and session ids provide routing, not protection authority. The
application reopens the same durable capsule when restoring a family.
A first marked recall can reach the model after durable protection. Later automatic
recall and extraction raise AutomaticCaptureSuppressed; a marked extraction response
stops later batches. Suppression after the model answers fails the run without undoing
that answer or any tool effects.
LoomContextProvider argument |
Default | Effect |
|---|---|---|
agent |
required | the loom.Agent the provider calls; Agent Framework awaits its providers, so a SyncAgent is refused |
user_id |
none | the end user the memories belong to; unset, recall reads all namespace memories the token permits and extraction writes shared rows; empty, - or whitespace-padded ids raise ValueError |
source_id |
loom |
the provider’s id in Agent Framework’s attribution |
top_k |
5 | memories per run, 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 |
Claude API memory tool
The Claude API memory tool (memory_20250818) lets Claude keep files under /memories
across conversations, and the application runs its commands. AsyncLoomMemoryTool (over a
loom.Agent) and LoomMemoryTool (over a loom.SyncAgent) subclass the anthropic SDK’s
memory tool bases and run those commands against Loom: each file is a Loom document, so
every agent of the namespace reads the same files, knowledge.search finds what they say,
and the files stay in the Loom deployment. Install with
pip install 'clickhouse-loom[claude-memory]==1.3.0' (anthropic 2.11.x).
import anthropic
from loom import Agent
from loom.integrations.claude_memory import AsyncLoomMemoryTool
client = anthropic.AsyncAnthropic()
async with Agent(org="acme", namespace="support") as loom_agent:
memory = AsyncLoomMemoryTool(loom_agent, store="alice")
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=16000,
tools=[memory],
messages=[{"role": "user", "content": "Remember that I prefer aisle seats"}],
)
async for message in runner:
...
In TypeScript, loomMemoryTool(agent, { store }, extras) returns the SDK’s betaMemoryTool
(with extras such as cache_control) over the same documents (@anthropic-ai/sdk is an
optional peer dependency, 1.8.x or 1.11.x). Install the SDK and native peer with
npm install @clickhouse/loom@1.3.0 '@anthropic-ai/sdk@>=1.11.0 <1.12.0':
import { loomMemoryTool } from "@clickhouse/loom/integrations/claude-memory";
const memory = loomMemoryTool(agent, { store: "alice" });
// client.beta.messages.toolRunner({ model, max_tokens, tools: [memory], messages })
loomMemoryHandlers(agent, { store }) returns the six command handlers alone, for a loop that
dispatches the tool’s calls itself.
A file /memories/<path> is the document loom-memory://<store>/memories/<path>, tagged
claude-memory:<store>; directories are the paths’ prefixes. Both SDKs read and write the
same documents and answer each command with the same text: the text the Python SDK’s local
memory tool answers, except that a directory view lists paths without sizes and that two
refusals are Loom’s own (an empty old_str, and a path under a file).
| Command | Loom |
|---|---|
view |
a file: knowledge.get, its lines numbered, view_range honoured; a directory: knowledge.list of the store’s tag, its files and directories two levels deep |
create |
knowledge.upsert of the text; refused when the file or a directory of that path exists |
str_replace |
knowledge.get, then knowledge.upsert with the one occurrence replaced; refused when old_str is empty, does not appear, or appears more than once |
insert |
knowledge.get, then knowledge.upsert with the line inserted at insert_line |
delete |
knowledge.bulk_delete of the file, or of every file under the directory, 500 a call |
rename |
each file under the old path copied to the new one, then knowledge.bulk_delete of the old; refused when the destination exists; a failure partway leaves the copies made so far |
Every path must be /memories or under it, after . and .. are resolved; any other path
is refused before Loom is called. A refusal is a ToolError, which the tool runner returns
to Claude as an error result. An edit reads the file and writes it back, so two agents that
edit one file at once keep the later write, as with the SDK’s local memory tool; a
directory view, delete or rename that pages while another agent rewrites a file under it
can miss that file.
| Argument | Default | Effect |
|---|---|---|
agent |
required | a loom.Agent for AsyncLoomMemoryTool and loomMemoryTool, a loom.SyncAgent for LoomMemoryTool |
store |
default |
the file tree, one path segment: one per application, or per user |
A store is not a boundary: every reader of the namespace can read every store’s documents. Give each user their own namespace when users must not read each other’s files.
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]==1.3.0' (google-adk 2.14.x).
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 authorization boundary is the namespace:
a write can merge with another agent’s row for the same user, so apps sharing a
namespace also share that user’s memory context. 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; empty, -, * and whitespace-padded ids raise 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. Remaining result slots hold up to 100 knowledge documents shared by
the app namespace; documents carry no fact-deletion id.
The Python service retains the application-owned SessionProtection families present
at construction and method entry. Use one service per logical session family; native
app, user and session ids do not select protection. Inside family.automatic(), a
protected contributor suppresses further content requests, including later extraction
batches and the optional knowledge search. If that second search is suppressed after
a marked memory result, the callback raises AutomaticCaptureSuppressed and returns
no memory response. Calls outside automatic context remain explicit and observe
responses through the retained families. Exact deletion remains a reference operation.
| 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 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, followed by knowledge.search for remaining slots; with honour_abstain, leaves out memories below Loom’s floor and abstaining memory results; each entry’s custom_metadata carries similarity and source, and its timestamp is valid_at when the row has one |
delete_memory |
the entry id carries its key, session, writer and searched version. memory.delete_version deletes that exact row only; a rewritten or missing version is a no-op. Passages, summaries, knowledge hits and facts without writer/version metadata have no deletion id. Use erasure for their content. A call without an id does nothing. Adding the session again can extract the fact again; blacklist.add refuses future writes |
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 |
filter the memory leg below Loom’s floor or on abstention; knowledge remains available |
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 |
The TypeScript service implements @google/adk 2.5’s BaseMemoryService interface
(npm install @clickhouse/loom@1.3.0 @google/adk@~2.5). It exposes
addSessionToMemory and searchMemory;
that interface has no individual-memory deletion or event-append method. Both SDKs
use the same derived Loom session for the same user and ADK session id. TypeScript
options are appName, topK, honourAbstain and defer, with the Python defaults.
import { InMemorySessionService, LlmAgent, PRELOAD_MEMORY, Runner } from "@google/adk";
import { LoomMemoryService } from "@clickhouse/loom/integrations/google-adk";
const sessions = new InMemorySessionService();
const memory = new LoomMemoryService(loomAgent, { appName: "support" });
const runner = new Runner({
appName: "support",
agent: new LlmAgent({ name: "assistant", model: "gemini-flash-latest", tools: [PRELOAD_MEMORY] }),
sessionService: sessions,
memoryService: memory,
autoCreateSession: true,
});
for await (const event of runner.runAsync({
userId: "alice",
sessionId: "travel",
newMessage: { role: "user", parts: [{ text: "I prefer aisle seats" }] },
})) {
/* consume the turn */
}
const session = await sessions.getSession({
appName: "support",
userId: "alice",
sessionId: "travel",
});
if (session) await memory.addSessionToMemory(session);
Save a completed TypeScript session once. Saving it again extracts it again; the TypeScript interface has no per-turn append operation. ADK’s in-memory session service in these examples holds the running conversation only; Loom stores the extracted memories and searchable documents in the user’s deployment.
Agno
LoomMemoryDb implements Agno 3.2’s BaseDb user-memory methods for one user and
store. Install pip install 'clickhouse-loom[agno]==1.3.0' (agno>=3.2,<3.3). Pass it to a
MemoryManager; configure the agent’s session database separately if needed.
from agno.db.schemas.memory import UserMemory
from agno.memory import MemoryManager
from loom import SyncAgent
from loom.integrations.agno import LoomMemoryDb
with SyncAgent(org="acme", namespace="support", agent="assistant") as loom_agent:
manager = MemoryManager(db=LoomMemoryDb(loom_agent, user_id="alice"))
manager.add_user_memory(UserMemory(memory="Prefers aisle seats"), user_id="alice")
memories = manager.get_user_memories(user_id="alice")
The database stores each native memory, including its id, topics, agent/team attribution, input, feedback and timestamps, as an episodic Loom row. This keeps native identifiers and updates intact without fact extraction or semantic duplicate merging. The native JSON payload follows Loom’s sensitivity classification; epoch timestamps can receive a contact-detail label. Rows stay in the user’s Loom deployment; the adapter adds no database, cache or vector store.
Use one LoomMemoryDb per end user. An omitted user in a database method means its
bound user; a different user is refused. Agno’s manager defaults an omitted user to
default, so pass the user to manager calls as in the example. Optional store=
(default default) separates applications sharing that user. Keys and the derived
Loom session include both user and store digests. Separate namespaces and restricted
tokens remain the boundary for mutually untrusted applications.
Bind one database per conversation to its application-owned SessionProtection
family. Constructor and callback contributors remain bound across context exit and
client rebinding. Automatic invocations join those retained contributors, so a protected
family stops later automatic reads and writes before dispatch. Explicit database calls
remain explicit after the automatic invocation ends, and every response still observes
the known families. Native user and store ids do not select protection.
The database implements single/bulk upsert, get, list, content/topic/agent/team filters,
sorting, pagination, topic listing, statistics and deletion. Reads hydrate full values
and page through the bound store. Filters and sorting run over those rows locally;
large stores therefore incur a full read. clear_memories clears only this bound store
and user. Concurrent writes of one native id keep the later write; a bulk write or
clear can partially finish when a request fails. Other BaseDb capabilities, including
sessions, tracing and evaluation storage, raise NotImplementedError.
Agno’s memory manager can make model calls when it extracts or edits memories. This adapter makes no model call itself; its tests supply native memory objects directly.
Pydantic AI
Pydantic AI extends an agent through tools and toolsets. loom_toolset returns Loom’s
agent verbs as a FunctionToolset, the same AgentTools as the
OpenAI Agents SDK adapter. Install with
pip install 'clickhouse-loom[pydantic-ai]==1.3.0' 'pydantic-ai-slim[anthropic]' (pydantic-ai-slim
2.68 or a later 2.x, plus the extra for your model’s provider).
from loom import Agent
from loom.integrations.pydantic_ai import loom_toolset
from pydantic_ai import Agent as PydanticAgent
async with Agent(org="acme", namespace="support") as loom_agent:
assistant = PydanticAgent(
"anthropic:claude-sonnet-5-5",
instructions="Recall what you know about the user before answering.",
toolsets=[loom_toolset(loom_agent, user_id="alice")],
)
result = await assistant.run("Book my usual seat to Lisbon")
user_id, session_id and run_id bind every call to one scope; only=[...] keeps a
subset and max_result_chars (8,000 by default) caps what a call returns (loom_recall
leaves out its lowest-ranked memories whole to fit, counted in omitted). A call Loom
refuses raises Pydantic AI’s ToolFailed with <tool> failed: <message>: the model reads
it as a failed tool result and the run goes on, where any other exception would fail the
run. The toolset’s tools await the Loom agent’s calls, so it takes a loom.Agent and
refuses a SyncAgent. Message history stays with the caller, who passes it to each run as
message_history.
Mastra
loomTools(agent, scope) returns Loom’s agent verbs as Mastra tools built with
createTool, keyed by name as a Mastra Agent takes them: the same AgentTools as the
OpenAI Agents SDK adapter. @mastra/core 1.83.x is an
optional peer dependency, and needs Node 22.13 or later. Install with
npm install @clickhouse/loom@1.3.0 '@mastra/core@>=1.83.0 <1.84.0'.
import { Agent as MastraAgent } from "@mastra/core/agent";
import { loomTools } from "@clickhouse/loom/integrations/mastra";
const assistant = new MastraAgent({
id: "assistant",
name: "assistant",
instructions: "Recall what you know about the user before answering.",
model,
tools: loomTools(agent, { userId: "alice" }),
});
LoomMemoryStorage implements the native MemoryStorage domain. It keeps mutable
threads, complete message payloads and resource working memory in Loom through the SDK.
For native storage, also run npm install @mastra/memory@1.41.1.
For automatic native memory, the app supplies conversationCapture, a SessionCapture
restored for the complete logical conversation family:
import { MastraCompositeStore } from "@mastra/core/storage";
import { Memory } from "@mastra/memory";
import { LoomMemoryStorage } from "@clickhouse/loom/integrations/mastra";
const memory = new Memory({
storage: new MastraCompositeStore({
id: "loom",
domains: {
memory: new LoomMemoryStorage(agent, {
resourceId: "alice",
storeId: "assistant",
capture: conversationCapture,
}),
},
}),
options: {
semanticRecall: false,
observationalMemory: false,
workingMemory: { enabled: true, scope: "resource" },
},
});
Construct one storage and Memory instance per authenticated end-user. The canonical
resourceId is the actual Loom user_id on every thread, message and resource row, so
user erasure covers them together. Reads without a
resource argument remain scoped to that bound user. Cross-resource writes are refused;
cross-resource reads return missing or empty results. Keep the same Loom agent and
storeId across processes to resume the same data. A store must not be shared across
users, and resource reassignment is unsupported.
With capture, construct a separate storage and Memory instance for each complete
conversation family. Keep its durable protection state across reconnects and restarts;
resource, store and thread IDs identify rows and do not restore protection authority.
The adapter retains the supplied capture and the client’s contributing families before
asynchronous work. A marked recall returns only after every contributing family commits
protection. Later automatic callbacks raise AutomaticCaptureSuppressed, including
batch continuation, conditional-update retries and pending thread timestamp updates.
A marked write also refuses the callback, so a failed batch can leave earlier writes
stored. The refusal propagates through native Memory methods.
Omit capture only for explicitly owned CRUD. Those calls retain response observers
without becoming automatic. Model-selected loomTools calls remain explicit. The
adapter does not supply durable protection storage or create a conversation family.
Native listing supports thread/resource filters, date and metadata filters, ordering,
pagination and included message context across that user’s threads. Lists scan the
store’s scoped rows and retrieve full values by key before filtering; large histories
cost multiple HTTP calls. Partial updates use Loom’s hash precondition and retry a
conflict up to three times. A missing resource is created with
memory.set.if_match_sha256="absent"; this requires a server that supports the absence
precondition. Older servers return PRECONDITION_FAILED instead of creating it, and the
adapter never retries unconditionally. Concurrent partial resource patches preserve
omitted working memory and merge metadata; whole-resource saves remain replacements.
Writes clear the default expiry. Server retention policies, explicit deletion, user
erasure and server policy refusals still apply.
Deletes use memory.delete_version with the exact identity and lossless version from
the validated read. A missing row is a no-op; a concurrent rewrite is preserved and
returns an error. Thread deletion captures the parent before deleting its observed
messages and still removes own orphan messages when that parent is missing. Deletes are
logical Loom tombstones; later explicit saves can recreate an entity. Batches, thread
timestamp updates and cascading deletes are separate operations: a failure can leave
partial work and is returned to the caller. A cascade cannot prevent a new message
after enumeration. The adapter provides no transaction, local fallback or additional
storage.
Semantic recall, observational memory, run fencing, atomic working-memory merges and
thread cloning are unsupported. Other storage domains are absent. The existing tools
remain available alongside native history and working memory. Mastra checks
each call against Loom’s schema first and answers one outside it (a missing argument, an
extra key, a top_k above 20, a quoted number) with its own validation message; a call
within the schema that Loom refuses, or a server error, reaches the model as Mastra’s
failed tool result with Loom’s message. Either way the model reads the message and the run
goes on.
make test-sdk-mastra-memory runs the native tests with a fake Loom SDK transport.
make test-sdk-mastra-memory-live uses LOOM_BASE_URL and LOOM_API_KEY, with optional
LOOM_ORG and LOOM_NAMESPACE, to run the native memory lifecycle on a test deployment.
AI SDK
loomTools(agent, scope) returns Loom’s agent verbs as an AI SDK ToolSet, the record
generateText, streamText and the SDK’s agents take as tools: the same AgentTools as
the OpenAI Agents SDK adapter. ai 7.x is an optional peer
dependency, and needs Node 22.12 or later (the package is ESM-only). Install with
npm install @clickhouse/loom@1.3.0 'ai@>=7.0.0 <8.0.0'.
import { generateText, stepCountIs } from "ai";
import { loomTools } from "@clickhouse/loom/integrations/ai-sdk";
const { text } = await generateText({
model,
tools: loomTools(agent, { userId: "alice" }),
stopWhen: stepCountIs(5),
prompt: "Book my usual seat to Lisbon",
});
The AI SDK has no memory store of its own: the messages of a conversation are the caller’s, and the tools give the model Loom’s long-term memory. The AI SDK passes the model’s arguments through unchecked, and Loom checks them: it reads a quoted number as a number and ignores an extra key. A call Loom refuses reaches the model as the AI SDK’s tool-error result with Loom’s message, and the run goes on.
n8n
The @clickhouse/n8n-nodes-loom community package gives self-hosted n8n a Loom Chat
Memory sub-node for its AI Agent and a Loom action node for Remember, Recall and Search
Knowledge. The action node can also connect as an agent tool. Both call your Loom
server through the SDK; data stays in your Loom deployment.
Install the package through n8n’s Community Nodes settings after it is published, or
build a tarball from integrations/n8n
and install it into the community nodes directory. Its README gives the checked build
and installation commands. The package bundles its SDK and framework libraries and is
not verified for n8n Cloud.
Create a Loom API credential with the server URL and a namespace-scoped writer token. Set Organization, Namespace, Agent Name and User ID on each node. Connect Loom Chat Memory to the AI Agent’s Memory input and set Session ID to the conversation identifier (such as the Chat Trigger’s session ID). The workflow, user and session identify the history. Context Window Length limits the interactions sent to the agent; older messages stay in Loom until cleared. Remember stores durable facts separately from conversation history. Use separate namespaces and restricted tokens for mutually untrusted users.
Without a community package, n8n’s MCP Client Tool node can connect to Loom’s MCP URL
with ?toolset=core and a bearer token, and expose loom_memory_set and loom_search
to its AI Agent.
The MCP client setup describes that route.
Dify
The Loom tools plugin runs Remember, Recall and
Search knowledge as native Dify tools. Install its .difypkg from a local package
file and configure a reachable Loom URL, a scoped writer token and the deployment’s
organization, namespace and agent. Bind the User ID form field to your app’s user;
it is separate from model-generated arguments.
Remember stores a fact, Recall searches that user’s memories across agents, and Search knowledge searches shared app documents. Both searches stay in the configured namespace. The plugin calls the Python SDK, adds no store and keeps data in your Loom deployment. Privacy describes credentials, network access, provider processing and retention. The package is tested through the native plugin SDK against Loom; a Dify application and Dify Cloud have not been tested.
The MCP/OpenAPI setup also works without the package.
LangGraph
A store retains application-owned constructor and callback conversation contributors across client rebinding. Bind complete contributor authority before construction and use one store per logical conversation family; restore that family’s existing capsule. An existing automatic SDK context makes only that invocation automatic, with every retained family checked before dispatch. Direct calls and model-selected tools remain explicit, including after an automatic invocation ends. All calls retain response observation, so a marked or malformed reply protects earlier contributors before returning or refusing. Namespace, thread and user ids supply no protection authority.
LoomStore (sdk/python/loom/integrations/langgraph.py) is a LangGraph BaseStore, so
every graph node reaches it through get_store().
from loom import Agent
from loom.integrations.langgraph import LoomStore
store = LoomStore(Agent(org="acme", namespace="support", agent="assistant"))
graph = builder.compile(store=store) # nodes: store = get_store()
# inside a node
store.put(("users", user_id), "prefs", {"seat": "aisle"})
store.search(("users", user_id), query="seating preference", limit=3)
store.close() # after the sync API: closes the agent and the loop the sync methods ran on
Use one store either through the sync methods or through the a* ones; the sync methods
run the agent on an event loop the store owns.
| LangGraph | Loom |
|---|---|
namespace ("users", "alice") + key prefs |
memory key lg/users/alice/prefs, tags lg:users and lg:users/alice (one per prefix, so a prefix search is one tag filter) |
put(value) |
memory.set; the JSON object is the memory’s value |
put(..., index=False) |
memory_type="episodic": kept, not ranked |
put(..., ttl=minutes) |
ttl_seconds |
search(query=…) |
memory.search, then one memory.bulk_get for the values; SearchItem.score is the similarity |
search() without a query |
memory.list, by recency |
filter |
applied to the stored value with LangGraph’s operators ($eq $ne $gt $gte $lt $lte) |
list_namespaces |
derived from the keys under lg/ |
LoomStore(agent, tags=[...], search_top_k_cap=50) also stamps extra tags on every
write and caps the rows one ranked search asks for.
Limits. A ranked search asks for at most search_top_k_cap (50) rows, so
offset + limit past 50 returns fewer items. A search without a query and
list_namespaces page through memory.list; filter applies to each page. Without
langgraph installed, the module still imports (structural twins of Item,
SearchItem and the op types).
Strands Agents
LoomMemoryStore implements the MemoryStore protocol (add / search) that the
Strands Memory Manager folds into the model input before each call.
from loom import Agent
from loom.integrations.strands import LoomMemoryStore
from strands import Agent as StrandsAgent
from strands.memory import MemoryManager
async with Agent(org="acme", namespace="support", agent="assistant") as loom_agent:
store = LoomMemoryStore(loom_agent, tags=["customer"])
agent = StrandsAgent(memory_manager=MemoryManager(stores=[store], add_tool_config=True))
agent("Which seat should I pick for my December trip?")
The TypeScript version behaves the same and does not depend on the Strands SDK:
import { Datapack } from "@clickhouse/loom";
import { LoomMemoryStore } from "@clickhouse/loom/integrations/strands";
const agent = new Datapack("acme", "support", { baseUrl, apiKey }).agent("assistant");
const store = new LoomMemoryStore(agent, { tags: ["customer"] });
// new MemoryManager({ stores: [store] })
addwritesmemory.setunder a content-addressed key,<key_prefix>/<first 20 hex of sha256(content)>, so the same fact added twice is one row and the server’s supersession handles near-duplicates. Metadata values underkind,source,topicandcategory(strings up to 64 characters) becomekey:valuetags.searchrunsmemory.searchlimited to the store’s tags and memory type. When Loom abstains (no hit above its calibrated floor), the store returns nothing rather than a weak match, so the Memory Manager injects no context at all; a hit below the floor in a response that does not abstain is left out too. Each entry’s metadata carriesmemory_key,memory_type,similarity,sourceandvalid_at.
| Option (Python / TypeScript) | Default | Effect |
|---|---|---|
memory_type / memoryType |
semantic |
the type every write carries and every search is limited to |
tags |
none | stamped on every write; searches require them |
max_search_results / maxSearchResults |
3 | results per search when the caller does not say |
honour_abstain / honourAbstain |
true |
leave out hits below Loom’s floor; nothing when Loom abstains |
key_prefix / keyPrefix |
strands |
key prefix |
— / scope |
none | TypeScript only: a per-store user, session or run scope |
Pipecat
LoomMemoryService owns two Pipecat FrameProcessors that share one Loom Agent and
user. The recall processor sits after the user context aggregator and before the LLM; the
capture processor sits after the assistant aggregator. On each LLMContextFrame the recall
processor runs memory.search with the turn’s latest user text and inserts the matches into
the shared LLMContext. Audio frames, and a second context frame for the same user text,
pass through with no further Loom call. After the turn, the capture processor sends the
turn’s user and assistant text to memory.set_from_messages when it sees the assistant
aggregator’s LLMContextAssistantTurnFrame.
from pipecat.pipeline.pipeline import Pipeline
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from loom import Agent
from loom.integrations.pipecat import LoomMemoryService
async with Agent(org="acme", namespace="support") as loom_agent:
memory = LoomMemoryService(loom_agent, user_id="alice")
context = LLMContext([{"role": "system", "content": "Be helpful."}])
user, assistant = LLMContextAggregatorPair(context)
pipeline = Pipeline(
[
transport.input(),
stt,
user,
memory.recall_processor(),
llm,
tts,
transport.output(),
assistant,
memory.capture_processor(),
]
)
Install with pip install 'clickhouse-loom[pipecat]==1.3.0' (pipecat-ai 1.16.x).
The text-only example uses a canned reply and requires the application’s existing trusted session pointer.
| Pipecat | Loom |
|---|---|
LLMContextFrame (recall) |
memory.search with the turn’s latest user text; with honour_abstain, leaves out memories below Loom’s floor and adds nothing when Loom abstains; the matches replace one developer block |
LLMContextAssistantTurnFrame |
the user text of the new turn and the assistant text of its response, sent to memory.set_from_messages (400 messages a call, the op’s cap); memory blocks and empty text are not sent |
Extraction runs under a Loom session derived from the user and the service’s session_id
(pipecat- and a digest of the pair): Loom files a turn’s verbatim chunks by session alone,
and a caller may choose its session ids. When session_id is omitted, the service mints one
for its lifetime, so the turns of one call share a session.
Bind the application’s existing SessionProtection before creating the service, and
use one service per logical conversation family. The service retains constructor and
callback contributors before native processing awaits, including committed context
frames whose capture happens later. Client rebinding cannot drop an earlier contributor.
Native user and session ids provide routing, not protection authority.
A first marked recall can enter the native context after durable protection. Later automatic recall and capture are suppressed while native frames keep flowing. Protection discards only the service’s retry references and write tracking; it does not clear application-owned history or acknowledge unsent extraction. These controls do not declare fleet support or initialize a capsule during restore.
LoomMemoryService argument |
Default | Effect |
|---|---|---|
agent |
required | the loom.Agent the processors call; Pipecat awaits its processors, so a SyncAgent is refused |
user_id |
none | the end user the memories belong to; unset, recall reads all namespace memories the token permits and extraction writes shared rows; empty, - or whitespace-padded ids raise ValueError |
session_id |
minted | the caller’s conversation id, folded into the Loom session; unset, a fresh id is used for this service instance |
top_k |
5 | memories per turn, 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 |
Langflow
The Loom Langflow component saves a memory,
searches memories, and searches knowledge documents from a Langflow flow. It is a
Langflow Component with typed inputs for the namespace, the user, and the query, plus
an action dropdown (save, search memory, search documents). Install
clickhouse-loom in Langflow’s Python environment and load
integrations/langflow/loom_component.py as a custom component. The component
constructs a SyncAgent and calls memory.set, memory.search, or knowledge.search;
the user input is user_id on the memory write and search. Knowledge search is
namespace-scoped. Data stays in your Loom deployment; the component adds no store.
Agent orchestrators
A harness that runs several agents gives them shared, durable memory by mounting Loom’s MCP endpoint in each:
mcp_servers:
loom:
type: streamable-http # some clients call it `http`
url: ${LOOM_BASE_URL}/mcp
headers:
Authorization: Bearer ${LOOM_API_KEY}
- Agents in one namespace share everything. A sub-agent that should read a team
namespace but write only its own gets a
viewergrant on the team namespace (tokens and grants). - Checkpoint task state with
working_memory.*under arun_id; the next agent reloads it throughcontext.pack(trace and resume). - Hand work between agents with the task inbox.
With the TypeScript SDK, agentId in a call’s Scope overrides the agent name, so one
client can speak for several agents.
Failure modes
- Abstain is not an error. An empty search means nothing cleared Loom’s floor.
- CrewAI carries on without memory when a memory call fails. A crew runs the task
anyway: a failed save prints only for a
verboseagent, and a failed recall shows only as aMemoryRetrievalFailedEventon CrewAI’s event bus, so an unreachable Loom is otherwise silent. - An AG2 turn fails when Loom is unreachable.
LoomRecallPolicyruns before each model call of the turn, andAssemblerMiddlewaredoes not catch a policy’s error. - An Agent Framework run fails when Loom is unreachable. The
Agentdoes not catch a provider’s error, before the run or after it. A failure after the run comes once the model has answered: the run raises, a history provider that runs after Loom’s (the agent’s in-memory one) does not record the turn, any tool’s effect stays, and a streamed reply has already been shown. - ADK carries on without memory when
preload_memory’s search fails. It logs a warning and the model call goes on; a failedload_memorysearch or save callback fails the run. - An AutoGen turn fails when Loom is unreachable.
AssistantAgentcallsupdate_contextonce per turn, before its first model call, and does not catch its errors. - A refused tool call reaches the model, and the run goes on. The OpenAI Agents SDK tools return Loom’s error to the model as the call’s result; the Pydantic AI, Mastra and AI SDK tools return it as a failed tool result (Mastra answers a call outside Loom’s schema with its own validation message first), and the AG2 tools as a tool error.
- Write verdicts are hidden by the framework interface. A
putoraddthat lands asconflictedorduplicatereturns normally; read the namespace’s conflicts in the dashboard or withconflicts.list(conflicts and refusal). - One store per event loop for LangGraph’s sync API: mixing sync and async calls on one store runs the agent on two loops.
- A Pipecat turn continues when Loom is unreachable. The recall and capture processors still push the frame they were given: the context frame reaches the model, and audio frames stay on their path. A failed capture leaves the turn in the conversation but not in Loom.