Saltar al contenido
ClickHouse Loom
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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 TypeScript, @clickhouse/loom/integrations/n8n 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:

  • aput sends the user and assistant turns to memory.set_from_messages under the Memory’s session id; Loom extracts the facts worth keeping and resolves duplicates and conflicts with what it already holds. With defer (the default) the server queues the extraction, so a flush is one request and an extraction failure does not fail the turn.
  • aget searches the block’s namespace, across every agent writing to it, with the latest user message and returns the matching memories, one line each, which Memory places 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. For the Python examples, install the SDK from the root of the Loom checkout that supplies this guide:

pip install './sdk/python[openai-agents]'

The extra installs openai-agents 0.24. Native sessions also require a server built from that same checkout with the Postgres memory authority; see running the server from source.

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.append_batch per call, each item an episodic row under <key_prefix>/<nanoseconds>-<random> with the item’s JSON as 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

Python and TypeScript additions require a server advertising memory.append_batch and using the Postgres memory authority. A nonempty call encodes every item before sending one request of at most 1,000 items. Equal values remain distinct occurrences. A refused entry or an existing key refuses the whole batch before any history is appended. An empty call sends nothing. Discovery failures, an older replica’s missing operation and storage refusals propagate without a point-write or bulk-write fallback. Existing history remains readable on older servers. This changes the server requirement for additions in both SDKs; their supported OpenAI Agents SDK dependency ranges are unchanged.

A committed batch whose publication is pending reports PUBLICATION_PENDING with committed=true; it is not a rollback. Preserve the original request’s idempotency key when resolving an uncertain outcome. Do not retry as a fresh addition or delete earlier items to compensate. These append guarantees do not make concurrent history paging, pop_item or clear_session atomic.

An episodic memory is not embedded, so an item is never merged with or judged against another row. Repeated values remain separate occurrences in both SDKs’ batches. 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

Build and install the TypeScript SDK from that same checkout using the SDK source instructions. In your application, install its supported native peer:

npm install '@openai/agents@>=0.22.0 <0.23.0'

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/loom npm 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 SDK in the npm project that runs n8n, where the host’s n8n-workflow package is available. The adapter is tested with n8n-workflow 2.47.2. Point n8n’s custom-node loader at the SDK’s bundled node directory, then restart n8n:

npm install @clickhouse/loom
export N8N_CUSTOM_EXTENSIONS="$(node -p 'require("node:path").join(require("node:path").dirname(require.resolve("@clickhouse/loom/package.json")), "dist/integrations/n8n")')"
npx --no-install n8n start

Set the same environment variable on each n8n worker that loads the nodes. The custom-node loader supports this package directory. The Community Nodes settings installer requires an n8n-nodes- package name, so use the custom-node loader for @clickhouse/loom. The native node files bundle their framework libraries and licenses. The adapter targets self-hosted n8n and does not claim n8n Cloud verification.

The classes are also available from @clickhouse/loom/integrations/n8n: Loom, LoomMemory, LoomApi and LoomChatHistory. The SDK’s main import does not load these classes or their host dependency. To check a private Loom deployment, run LOOM_BASE_URL=http://localhost:7790 npm --prefix sdk/typescript run test:n8n:live from the repository root after building the SDK.

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.

n8n’s MCP Client Tool node can also 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] })
  • add writes memory.set under 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 under kind, source, topic and category (strings up to 64 characters) become key:value tags.
  • search runs memory.search limited 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 carries memory_key, memory_type, similarity, source and valid_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 viewer grant on the team namespace (tokens and grants).
  • Checkpoint task state with working_memory.* under a run_id; the next agent reloads it through context.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 verbose agent, and a failed recall shows only as a MemoryRetrievalFailedEvent on CrewAI’s event bus, so an unreachable Loom is otherwise 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.
  • An Agent Framework run fails when Loom is unreachable. The Agent does 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 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.
  • 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 put or add that lands as conflicted or duplicate returns normally; read the namespace’s conflicts in the dashboard or with conflicts.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.

¿Te ha resultado útil esta página?