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
1 change: 1 addition & 0 deletions .claude/skills/loom-release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Every step others see is the owner's to start, as AGENTS.md has it: opening or m
## 1. The version

- One version for the server, both images, the web app, both SDKs, the root skills and the chart's `appVersion`; `prepare.py` moves all of them and the chart's own `version`.
- One public npm package, `@clickhouse/loom`, contains the SDK and every JavaScript adapter, including n8n. Include adapter artifacts and tests in the SDK build; `release.yml` is its sole npm publisher. Do not create an adapter package, version tag or trusted publisher.
- The coding-agent plugins keep their own version, bumped in the pull request that changes them. Raise their `MIN_SERVER_VERSION` as the [release process](../../../docs/development/release-process.md#cutting-the-release) step 2 says.
- A minor for features, a patch for fixes only (on a release branch, §7), a major for a break beyond the N−1 rule. A field or op to be removed is announced one minor ahead, by hand under the notes' "What changed for clients" (the generated wire diff lists only what has changed), and served until the removal; after it, a removed field is named in `ignored_args` and a removed op answers `NotFound` ([unknown and removed fields](../../../docs/reference/http-api.md#unknown-and-removed-fields)).

Expand Down
5 changes: 3 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -1312,7 +1312,8 @@ jobs:
cache-dependency-path: sdk/typescript/package-lock.json
- name: npm ci
working-directory: sdk/typescript
run: npm ci --no-audit --no-fund
# Host expression engines are not needed to build or test adapters.
run: npm ci --ignore-scripts --no-audit --no-fund
# biome lint + format, tsc --noEmit, version consistency, the README's
# ts examples type-checked against src, vitest.
- name: lint + type-check + version + README examples + unit tests
Expand All @@ -1329,7 +1330,7 @@ jobs:
- name: Claude memory tool with Anthropic 1.11
working-directory: sdk/typescript
run: |
npm install --no-save --package-lock=false --no-audit --no-fund @anthropic-ai/sdk@1.11.0
npm install --no-save --package-lock=false --ignore-scripts --no-audit --no-fund @anthropic-ai/sdk@1.11.0
npm run type-check
npx vitest run src/integrations/claude-memory.test.ts src/integrations/claude-memory-runner.test.ts
npx vitest run --config vitest.dist.config.ts test/package/exports.test.ts
Expand Down
90 changes: 0 additions & 90 deletions .github/workflows/n8n-publish.yml

This file was deleted.

3 changes: 2 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,8 @@ jobs:
python -m build sdk/python --outdir release/python
- name: npm ci
working-directory: sdk/typescript
run: npm ci --no-audit --no-fund
# Host expression engines are not needed to build or test adapters.
run: npm ci --ignore-scripts --no-audit --no-fund
# Lint, types, version across sources, README examples and unit tests
# gate a registry publish.
- name: npm run check (before a registry publish)
Expand Down
42 changes: 28 additions & 14 deletions docs/architecture/n8n-adapter.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# n8n adapter

The n8n community package stores conversation history and durable facts in a Loom
deployment through the TypeScript SDK. The nodes add no storage service or local cache.
The n8n adapter in the TypeScript SDK stores conversation history and durable facts in a Loom
deployment. The nodes add no storage service or local cache.

## Interfaces and storage

Expand All @@ -24,15 +24,28 @@ server derives provenance from the token and operation and enforces namespace gr

## Packaging

The package bundles the SDK and framework libraries to avoid runtime dependency
conflicts with other community nodes. Its build includes their license files.
`n8n-workflow` is the host-provided peer. Development dependencies pin the interfaces
used by tests; they are not added to Loom's server or SDK dependencies.
All JavaScript adapters ship in the `@clickhouse/loom` npm artifact. The n8n adapter
has the same version and publication workflow as the SDK. Its public subpath exports
the node, credential and history classes in ESM and CommonJS formats.

The package targets self-hosted n8n, with the official node CLI's configuration for
that target. It does not claim Cloud verification. The release-tag workflow builds
and checks the package before publishing with an npm trusted publisher and provenance;
no registry token is stored in the repository.
The SDK build also produces native `.node.js` and `.credentials.js` files under
`dist/integrations/n8n`. A nested package manifest marks these files as CommonJS,
while the SDK root remains ESM. The native files bundle the SDK source and framework
libraries, with their license files, to avoid runtime conflicts with other nodes.
`n8n-workflow` is an optional, host-provided peer. The SDK's browser-compatible entry
points do not import the adapter or its Node.js dependencies.

Self-hosted n8n loads the native files through `N8N_CUSTOM_EXTENSIONS`. This bypasses
the Community Nodes installer's package naming constraint using n8n's supported
custom-directory loader. The package manifest also lists the nodes and credential
for loaders that consume it. The adapter does not claim Cloud verification.

The SDK's distribution tests install its tarball without peers and in a separate,
locked n8n host. The hosts keep n8n's Zod 3 requirement apart from other frameworks'
Zod 4 requirement. They load the node files and exercise the adapter against its
pinned framework interfaces. The main release workflow publishes the
verified SDK tarball through its existing npm trusted publisher. There is no
integration-specific npm publisher, version or tag.

## Invariants

Expand All @@ -44,9 +57,10 @@ no registry token is stored in the repository.

## Source entry points

- `integrations/n8n/nodes/LoomMemory/LoomChatHistory.ts`: message persistence.
- `integrations/n8n/nodes/LoomMemory/LoomMemory.node.ts`: framework memory adapter.
- `integrations/n8n/nodes/Loom/Loom.node.ts`: durable memory and document actions.
- `.github/workflows/n8n-publish.yml`: checks and trusted publishing.
- `sdk/typescript/src/integrations/n8n/nodes/LoomMemory/LoomChatHistory.ts`: message persistence.
- `sdk/typescript/src/integrations/n8n/nodes/LoomMemory/LoomMemory.node.ts`: framework memory adapter.
- `sdk/typescript/src/integrations/n8n/nodes/Loom/Loom.node.ts`: durable memory and document actions.
- `sdk/typescript/scripts/build-n8n.mjs`: native node bundles and licenses.
- `.github/workflows/release.yml`: shared SDK trusted publishing.

[Framework setup](../features/integrations/frameworks.md#n8n)
2 changes: 2 additions & 0 deletions docs/development/release-process.md
Original file line number Diff line number Diff line change
Expand Up @@ -328,6 +328,8 @@ signature](#a-failed-tag-or-signature) recovers.

**Why publish the verified files.** A job that rebuilt its own artifact could ship unchecked bytes. Publishing what `verify` passed means the GitHub Release and the registries carry the same bytes.

All JavaScript adapters, including n8n, ship inside `@clickhouse/loom` at the SDK version. Its build checks the adapter artifacts before packing the tarball. `release.yml` is the sole npm publisher; adapters have no separate package, release tag or trusted publisher.

**Why the server is not on PyPI.** The server is deployed against ClickHouse, not imported as a library; it ships as the image. The root `pyproject.toml` is marked `Private :: Do Not Upload`, and PyPI carries only the SDK. The `pypi` and `npm` jobs need trusted publishers registered for this repository (their GitHub environments).

**Why SDK publishing is manual.** A registry publish cannot be undone: PyPI never accepts
Expand Down
33 changes: 25 additions & 8 deletions docs/features/integrations/frameworks.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ or needs another database, vector store or cache.
| 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 |
| 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 |
Expand Down Expand Up @@ -1086,16 +1086,33 @@ 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
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 package through n8n's Community Nodes settings after it is published, or
build a tarball from [`integrations/n8n`](https://github.com/ClickHouse/loom/tree/main/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.
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:

```sh
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](https://docs.n8n.io/hosting/configuration/configuration-examples/custom-nodes-location/)
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
Expand All @@ -1106,7 +1123,7 @@ messages stay in Loom until cleared. Remember stores durable facts separately fr
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
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](./mcp-clients.md#other-editors-and-agents) describes that route.
Expand Down
Loading
Loading