Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/features/integrations/frameworks.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ or needs another database, vector store or cache.
| 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` |

Any other framework that can call an HTTP endpoint or an MCP server uses Loom directly:
see [agent integration](../../guides/agent-integration.md) and
Expand Down Expand Up @@ -1071,6 +1072,18 @@ for its lifetime, so the turns of one call share a session.
| `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](../../../integrations/langflow/README.md) 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
Expand Down
1 change: 1 addition & 0 deletions integrations/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ adapters).
| Aider, Continue, OpenCode, any chat export | [`generic/`](generic/README.md) | none: run after the session on an exported `.json` / `.md` transcript | run `generic/ingest.sh` | bash, the `loom` CLI | `LOOM_API_KEY` or `~/.loom/token`, never on argv | `integrations/generic/test.sh` |
| Agents that only use shell grep | [`grep-shim/`](grep-shim/README.md) | none: `grep` / `rg` on `PATH` | put `grep-shim/bin` first on `PATH` | Node 18+ | viewer token in `LOOM_API_KEY` | `node --test integrations/grep-shim/tests/*.test.mjs` |
| LibreChat v0.8.8 (chat client) | [`librechat/`](librechat/README.md) | none: a person chats; the model calls the `assistant` toolset over MCP | `docker compose up -d` in `librechat/` ([guide](../docs/features/integrations/librechat.md)) | Docker | each person's own viewer token, stored per user in LibreChat (`customUserVars`) | `tests/unit/test_librechat_integration.py` |
| Langflow 1.13.3 | [`langflow/`](langflow/README.md) | none: a flow calls save, search memory, or search documents | load `langflow/loom_component.py` as a custom component; `pip install clickhouse-loom` in Langflow's env | Langflow, the Python SDK | writer token: `LOOM_API_KEY` or the component's API key input | `tests/unit/test_langflow_component.py` |
| AX sandboxed tasks | [`ax/`](ax/README.md) | none: the agent calls Loom over MCP or the SDK | steps 1–4 of [`ax/README.md`](ax/README.md) | the task's image | writer token in a Kubernetes Secret, injected by Substrate's egress gateway; never in the Task | |
| Git repositories holding OKF bundles | [`okf-ci/`](okf-ci/README.md) | push, pull request | copy `okf-lint.yml` to `.github/workflows/`, pin `LOOM_REF` | GitHub Actions, uv | none: the lint is offline; `contents: read` | actionlint; `loom okf-lint` is covered by `tests/unit/test_okf_lint.py` |

Expand Down
72 changes: 72 additions & 0 deletions integrations/langflow/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Langflow

A Langflow custom component that saves and searches Loom memory and searches
knowledge documents through the Python SDK.

The component is a Langflow \`Component\` with typed inputs for the namespace, the
user, and the query, and an action dropdown: \`save\`, \`search memory\`, or
\`search documents\`. It constructs a \`SyncAgent\` and calls \`memory.set\`,
\`memory.search\`, or \`knowledge.search\`. The user input is sent as \`user_id\` on
the memory write and search. Knowledge search is namespace-scoped. Data stays in
your Loom deployment; the component adds no store.

## Install

These steps were checked against Langflow 1.13.3.

Install the Python SDK into the same environment as Langflow, from this checkout:

```bash
pip install /path/to/loom/sdk/python
```

Or install the published package with `pip install clickhouse-loom`.

Load [`loom_component.py`](loom_component.py) as a Langflow custom component:
paste the file into a new custom component, or point Langflow's custom
components path at this directory, then start Langflow:

```bash
export LANGFLOW_COMPONENTS_PATH=/path/to/loom/integrations/langflow
langflow run
```

The component appears as **Loom**. It needs a reachable Loom server (a
[quickstart](../../docs/getting-started/quickstart.md) listens on
`http://localhost:7777`) and a namespace-scoped writer token.

## Inputs

| Input | Role |
| ---------- | ------------------------------------------------------------------------ |
| Action | `save`, `search memory`, or `search documents` |
| Org | Organization; may be empty when the token fills it |
| Namespace | Namespace the component reads and writes |
| User | End user for `memory.set` and `memory.search`; empty reads the namespace |
| Query | Value to save, or the search query |
| Memory key | Required when the action is `save` |
| Top K | Number of search hits (default 5) |
| Loom URL | Server URL (default `http://localhost:7777`) |
| API key | Writer token; may also come from `LOOM_API_KEY` or the Loom profile |
| Agent | Agent name stamped on writes (default `langflow`) |

## A flow

1. Start a Loom quickstart at `http://localhost:7777` and create a writer token.
2. In Langflow 1.13.3, add a Chat Input, a Loom component, and a Chat Output.
Connect Chat Input to the Loom Query input, and the Loom Result to Chat Output.
3. On the Loom component, set Action to `save`, Namespace to your namespace, User
to the end-user id, Memory key to a stable key such as `pref.seat`, and Org,
API key, and Loom URL from the quickstart.
4. Run the flow with a message such as "aisle seat". The Result is a JSON object
with `action`, `memory_id`, `version`, and `content_sha256`.
5. Add a second Loom component with the same Org, Namespace, User, API key, and
URL, Action `search memory`, and Query from Chat Input. Run with "which
seat". The Result is a JSON object with `action`, `abstain`, and `hits`
(`memory_key`, `value`, `similarity`). A `search documents` run returns
`action` and `hits` (`source_uri`, `content`, `similarity`).

Unit tests under `tests/unit/test_langflow_component.py` drive each action with
the SDK pointed at an `httpx.MockTransport`, so they do not need Langflow or a
live Loom server. A recorded transcript from a live Langflow session against a
quickstart is not included here.
201 changes: 201 additions & 0 deletions integrations/langflow/loom_component.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,201 @@
"""Langflow custom component: save and search Loom memory, and search knowledge documents."""

from __future__ import annotations

from typing import Any

from lfx.custom.custom_component.component import Component
from lfx.io import (
DropdownInput,
IntInput,
MessageTextInput,
Output,
SecretStrInput,
StrInput,
)
from lfx.schema.data import Data
from loom import SyncAgent

SAVE = "save"
SEARCH_MEMORY = "search memory"
SEARCH_DOCUMENTS = "search documents"
_ACTIONS = (SAVE, SEARCH_MEMORY, SEARCH_DOCUMENTS)


def _open_agent(**kwargs: Any) -> SyncAgent:
return SyncAgent(**kwargs)


def _text(value: Any) -> str:
return str(value or "").strip()


def _secret(value: Any) -> str | None:
if value is None:
return None
raw = value.get_secret_value() if hasattr(value, "get_secret_value") else value
text = _text(raw)
return text or None


def _query_text(value: Any) -> str:
if value is None:
return ""
if isinstance(value, str):
return value
inner = getattr(value, "text", None)
if isinstance(inner, str):
return inner
return str(value)


class LoomComponent(Component):
display_name = "Loom"
description = "Save and search Loom memory, and search knowledge documents."
documentation: str = (
"https://github.com/ClickHouse/loom/blob/main/integrations/langflow/README.md"
)
icon = "database"
name = "Loom"

inputs = [
DropdownInput(
name="action",
display_name="Action",
options=list(_ACTIONS),
value=SEARCH_MEMORY,
info="Save a memory, search memories, or search knowledge documents.",
),
StrInput(name="org", display_name="Org", value="", required=False),
StrInput(
name="namespace",
display_name="Namespace",
value="",
required=True,
info="Loom namespace the component reads and writes.",
),
StrInput(
name="user_id",
display_name="User",
value="",
required=False,
info="End user for memory.set and memory.search. Empty reads the namespace.",
),
MessageTextInput(
name="query",
display_name="Query",
value="",
required=True,
info="The memory value to save, or the search query.",
),
StrInput(
name="memory_key",
display_name="Memory key",
value="",
required=False,
info="Required when the action is save.",
),
IntInput(name="top_k", display_name="Top K", value=5, required=False),
StrInput(
name="base_url",
display_name="Loom URL",
value="http://localhost:7777",
required=False,
),
SecretStrInput(name="api_key", display_name="API key", value="", required=False),
StrInput(
name="agent_name",
display_name="Agent",
value="langflow",
required=False,
info="Agent name stamped on writes.",
),
]
outputs = [
Output(display_name="Result", name="result", method="produce_result"),
]

def produce_result(self) -> Data:
action = _text(getattr(self, "action", ""))
if action not in _ACTIONS:
raise ValueError(f"unknown action: {action or '(empty)'}")
namespace = _text(getattr(self, "namespace", ""))
if not namespace:
raise ValueError("namespace is required")
memory_key = _text(getattr(self, "memory_key", ""))
if action == SAVE and not memory_key:
raise ValueError("memory_key is required when saving a memory")
return Data(data=self._call_loom(action, namespace, memory_key))

def _call_loom(self, action: str, namespace: str, memory_key: str) -> dict[str, Any]:
with _open_agent(**self._agent_kwargs(namespace)) as agent:
user_id = _text(getattr(self, "user_id", "")) or None
query = _query_text(getattr(self, "query", ""))
top_k = int(getattr(self, "top_k", 5) or 5)
if action == SAVE:
written = agent.memory.set(memory_key, query, user_id=user_id)
return _save_payload(written)
if action == SEARCH_MEMORY:
found = agent.memory.search(query, user_id=user_id, top_k=top_k)
return _memory_hits_payload(found)
found = agent.knowledge.search(query, top_k=top_k)
return _document_hits_payload(found)

def _agent_kwargs(self, namespace: str) -> dict[str, Any]:
kwargs: dict[str, Any] = {
"org": _text(getattr(self, "org", "")),
"namespace": namespace,
"agent": _text(getattr(self, "agent_name", "")) or "langflow",
"retry": {"max_attempts": 1},
}
base_url = _text(getattr(self, "base_url", ""))
if base_url:
kwargs["base_url"] = base_url
api_key = _secret(getattr(self, "api_key", None))
if api_key:
kwargs["api_key"] = api_key
return kwargs


def _save_payload(written: dict[str, Any]) -> dict[str, Any]:
return {
"action": SAVE,
"memory_id": written.get("memory_id"),
"version": written.get("version"),
"content_sha256": written.get("content_sha256"),
"conflict_verdict": written.get("conflict_verdict"),
"noop": written.get("noop"),
}


def _memory_hits_payload(found: Any) -> dict[str, Any]:
hits = [
{
"memory_key": hit.memory_key,
"value": hit.content_excerpt,
"similarity": hit.similarity,
"memory_type": hit.memory_type,
"namespace": hit.namespace,
}
for hit in found
]
return {
"action": SEARCH_MEMORY,
"abstain": bool(getattr(found, "abstain", False)),
"abstain_code": getattr(found, "abstain_code", "") or "",
"hits": hits,
}


def _document_hits_payload(found: list[Any]) -> dict[str, Any]:
hits = [
{
"source_uri": hit.source_uri,
"content": hit.content,
"similarity": hit.similarity,
"chunk_idx": hit.chunk_idx,
"namespace": hit.namespace,
}
for hit in found
]
return {"action": SEARCH_DOCUMENTS, "hits": hits}
Loading