Cortadel × n8n

Cortadel is self-hosted long-term memory for AI agents — a bi-temporal graph store with hybrid BM25 + vector retrieval. This package makes it a first-class part of n8n: a Cortadel Memory sub-node that plugs straight into the AI Agent's memory port, and a Cortadel action node that works both as a normal workflow step and as a tool the agent can call itself.

The memory sub-node is the interesting half. n8n's built-in memories are chat buffers — the last N turns of the current session, gone when the session is. Cortadel Memory instead runs a fresh hybrid search across everything Cortadel knows about that user on every turn, injects the facts that are relevant now, and hands the finished turn back to Cortadel's extraction pipeline to be distilled into durable facts. Memories outlive the conversation.

Install

In n8n: Settings → Community nodes → Install, then enter:

n8n-nodes-cortadel

Or, for a self-hosted instance, from the command line in your n8n custom-nodes directory:

npm install n8n-nodes-cortadel

Quickstart

1. Create the credential. Add a Cortadel API credential. Set Base URL to https://app.cortadel.ai (hosted) or http://localhost:3001 (self-hosted). Set API Key if your server has auth enabled; leave it blank if it does not. Hit Test — it calls GET /api/health.

2. Build the workflow. Add a Chat Trigger and an AI Agent. On the agent:

   • drag Cortadel Memory onto the Memory port;
   • drag Cortadel onto the Tool port (optional, but it lets the agent search and write memories on purpose, not just implicitly).

3. Configure the memory node. The only two fields that matter:

   | Field | Value | |---|---| | User ID | {{ $json.userId ?? $json.sessionId }} | | Session ID | {{ $json.sessionId }} |

   These are different axes and both are load-bearing — see User ID vs Session ID.

4. Chat. Tell the agent something about yourself, start a brand-new session, and ask about it. A chat buffer has forgotten. Cortadel has not.

examples/agent-with-cortadel-memory.json is that workflow, ready to import.

What you get

Cortadel Memory — the automatic memory (an ai_memory sub-node)

Outputs n8n's ai_memory connection type, so it drops into the AI Agent's Memory port exactly like Simple Memory or Postgres Chat Memory. On every turn it:

• before the model call — searches Cortadel with the user's current message and injects the hits as context (one user-role block by default, or one message per fact);
• after the turn — posts the exchange to POST /api/v1/memories/from-conversation, where Cortadel's pipeline distils it into facts, deduplicates against what it already knows, and supersedes anything the turn contradicts.

Three behaviours worth knowing about, because they are deliberate:

• It degrades, it does not break. Every Cortadel call is wrapped. If the server is down, recall yields empty context and a warning in the execution log (n8n's own node logger); a failed persist is swallowed the same way. A memory outage must never take the agent down with it — there is deliberately no "fail hard" switch, and the default Context Role is chosen by the same rule (see below). Writes are awaited inside the turn rather than fired and forgotten: n8n treats the execution as over the moment the workflow ends, so a write still in flight has no execution left to report into — and in queue mode the worker that owns it can be reaped first.
• It does not re-search or re-store the same thing. Identical recall queries inside one turn are served from a short-lived local cache (default 15 s), so an agent's tool loop cannot hammer the server; an identical (input, output) pair is never written twice by the same node instance (the last 64 pairs are remembered, so an A → B → A tool loop is suppressed too, not just consecutive repeats — but n8n builds a fresh instance per execution, so this is a within-execution guard); and duplicate hits are collapsed by memory id and by text before injection. Cortadel's own server-side deduplication is the backstop across executions.
• clear() deletes nothing. Clearing an n8n chat window drops the local recall cache only. Long-term memory is not something a UI button should be able to wipe — use the Cortadel node's Delete operation, explicitly.

Context Role: user by default

Recalled memories are injected as a user message, and the default context header tells the model to read the block as background knowledge rather than as something the user just said.

That is the safe half of a real trade-off. A system message reads marginally better to OpenAI-style models — but on Anthropic it is a hard failure of the whole agent run. Anthropic's API takes a single system field, so @langchain/anthropic lifts messages[0] into it and throws System messages are only permitted as the first passed message. for any later one (_convertMessagesToAnthropicPayload in dist/utils/message_inputs.js). n8n's agent prompt is [system?, ...chat_history, human] (ToolsAgent → prepareMessages), so anything a memory node puts in chat_history sits at index ≥ 1 as soon as the agent's own System Message option is set — and Context Format: One Message Per Fact produces several regardless. Both cases throw. A memory node whose default can break the agent on a provider swap is not a memory node that "never takes the agent down", so the default is the role no provider can reject.

Opting into system: set Options → Context Role → System. The one condition that has to hold is the model: OpenAI-style (OpenAI, Azure OpenAI, Groq, Ollama, most OpenAI-compatible gateways), not the Anthropic Chat Model, which throws. The reason to bother is that a system message carries instruction-level weight instead of sitting in the dialogue — worth it if the agent keeps treating recalled facts as something the user just said.

test/message-compat.test.ts pins both roles against the real @langchain/anthropic and @langchain/openai converters, including the fact that the opt-in system role still throws on Anthropic — the caveat is tested, not just documented.

Known limitation: the AI Agent's streaming path

n8n's agent has two execution branches, and they call memory differently.

| Branch | What n8n does | What you get | |---|---|---| | Non-streaming (AgentExecutor.invoke) | LangChain's BaseChain._formatValues passes the real turn inputs to loadMemoryVariables(values) | The per-turn hybrid search this node is built for | | Streaming (chat trigger with response streaming on, node type version ≥ 2.1) | loadMemory() calls memory.loadMemoryVariables({}) — an empty object — and AgentExecutor's stream iterator never re-runs _formatValues | No query text reaches us, so recall degrades to the most recent Top K memories (GET /api/v1/memories) instead of a search |

Source: packages/@n8n/nodes-langchain/utils/agent-execution/memoryManagement.ts in n8n (loadMemory, and its call site in the Tools Agent's streaming branch).

Nothing in a memory sub-node can recover the input — it is simply not passed. So if per-turn relevance matters more to you than token-by-token streaming, turn streaming off on the AI Agent node. Persisting the turn is unaffected: saveContext still receives the real input and output on both branches.

The same code path also hardcodes the string 'chat_history' when reading the returned variables, so the Memory Key option only takes effect on the non-streaming branch. Leave it at its default unless you know you are on the non-streaming path.

Cortadel — the action node (and AI tool)

A normal main-in/main-out node with usableAsTool: true, so n8n also offers it in the agent's tool list. One resource, Memory, with six operations that map one-to-one onto the public REST contract:

| Operation | Route | What it does | |---|---|---| | Add | POST /api/v1/memories | Store one piece of text | | Add Conversation | POST /api/v1/memories/from-conversation | Distil facts out of a transcript | | Search | POST /api/v1/memories/search | Hybrid BM25 + vector retrieval | | List | GET /api/v1/memories | Page through stored memories | | Get | GET /api/v1/memories/{id} | One memory with its validity window | | Delete | DELETE /api/v1/memories | Delete by id |

One deliberate divergence from the Cortadel SDKs: client.get() returns null/None for an unknown id, whereas the Get operation surfaces the server's 404 as a node error. That is the n8n convention — a failed lookup should colour the node red — and Settings → On Error → Continue turns it back into a data row if you prefer the SDK behaviour.

User ID vs Session ID

Cortadel namespaces every memory to exactly one user; that is the isolation boundary, and it is what memories accumulate against across days and sessions. n8n's chat trigger only gives you a session id, which is per-conversation.

So the memory node asks for both. User ID is the long-term identity. Session ID groups the facts this conversation produces and can optionally narrow recall, via Scope Recall to Session:

• off (default) — recall spans everything Cortadel knows about this user. This is the point.
• on — recall is restricted to facts stored under this session id, which makes the node behave more like a conversation buffer. Writes still carry the session id either way.

If you have no real user identity, {{ $json.userId ?? $json.sessionId }} degrades gracefully to per-session memory.

Configuration

Credential — Cortadel API

| Option | Type | Default | Meaning | |---|---|---|---| | baseUrl | string | http://localhost:3001 | Cortadel server. Hosted: https://app.cortadel.ai | | apiKey | string (password) | — | Sent as Authorization: Bearer <key>. Optional: a self-hosted server with an empty auth secret leaves every endpoint open |

Credential test: GET /api/health. Note that Cortadel answers 503 when a dependency is degraded, so the test reports failure against a reachable-but-degraded server — that is a server-health signal, not necessarily a bad key.

Cortadel Memory sub-node

The first four are top-level fields on the node; everything from mode down lives inside the Options collection (click Add Option).

| Option | Type | Default | Meaning | |---|---|---|---| | userId | string | {{ $json.userId ?? $json.sessionId }} | Cortadel user that owns these memories | | sessionId | string | {{ $json.sessionId }} | Groups the facts this conversation produces | | scopeRecallToSession | boolean | false | Restrict recall to this session instead of the whole user graph | | topK | number (1–50) | 5 | Max memories injected per turn | | mode | hybrid | text | vector | hybrid | Which retrieval arms to fuse | | rerank | boolean | false | Rerank with the cross-encoder (also enables the graph and session arms) | | memoryType | episodic | semantic | procedural | any | Restrict recall to one cognitive type | | contextFormat | block | messages | block | One message listing the facts, or one message each | | contextRole | system | user | user | Role the recalled context is injected under. system is opt-in and throws on the Anthropic Chat Model — see above | | contextHeader | string | built-in sentence | Overrides the line above the facts in block format | | memoryKey | string | chat_history | Prompt variable the context is written to. Ignored on the agent's streaming branch — see Known limitation | | inputKey / outputKey | string | input / output | Where the turn text lives in LangChain's values | | returnMessages | boolean | true | Message objects vs one rendered string | | persistTurns | boolean | true | Turn off for read-only memory | | project | string | — | Project scope recorded on extracted facts | | tags | string (CSV) | — | Tags applied to every fact stored from this chat | | recallCacheTtlMs | number | 15000 | How long an identical recall is cached. 0 disables |

Cortadel action node

userId is required on every operation. Per-operation options mirror the REST contract: app, infer, memoryType, metadata (Add); sessionId, project, tags, isAgentMemory (Add Conversation); topK (default 10), mode, sessionId, rerank, memoryType (Search); page, appId, categories, searchQuery, includeSuperseded, memoryType, plus Return All (List).

What Cortadel records as the app

Both nodes label themselves n8n-nodes-cortadel — this package's published npm name, the same convention every Cortadel integration follows. It is sent as app_name on searches (access logging) and as app on writes (the app that created the memory); the Add operation's app field overrides the write label if you want a finer one. There is no option for it on the memory sub-node: a workflow author has no reason to misreport which node wrote a memory.

Design note: why not bundle @cortadel/sdk?

Cortadel publishes a TypeScript SDK, and for any other TypeScript integration it would be the right dependency. n8n is the exception: verified community nodes are not allowed run-time dependencies, and n8n's own this.helpers.httpRequestWithAuthentication is what applies the credential's authenticate block along with the instance's proxy and TLS configuration — things a bundled HTTP client would bypass. So this package ships zero run-time dependencies and talks to the same REST contract (spec/openapi.json) the SDK is generated from, with the wire DTOs transcribed into shared/types.ts.

The same rule shapes the message objects. n8n's built-in memory nodes import LangChain's HumanMessage/AIMessage/SystemMessage directly; this package cannot. Instead it tries to resolve the host's own @langchain/core/messages at run time — present in any n8n instance that has the AI nodes — and falls back to a dependency-free shim when it is not (sandboxed or non-hoisted community-node hosts, mostly). dist/ is CommonJS, as n8n requires, but it is emitted with module: node16 (TypeScript 7 removed the old node10 resolution mode), which also leaves the one dynamic import() as a real dynamic import rather than downleveling it to require() — so the host's @langchain/core loads through whichever build its exports map offers, ESM included.

That fallback has to be more than content + _getType(), and the reason is easy to miss: coerceMessageLikeToMessage() treats anything with a _getType function as already-a-message and returns it uncoerced, so a shim is handed to the model provider verbatim — and provider converters read message.response_metadata and message.additional_kwargs without a guard. The shim therefore carries the full field set, and test/message-compat.test.ts proves it by running real @langchain/core coercion and the real @langchain/openai message converter over shim-rendered memories.

Running the tests

cd integrations/n8n-nodes-cortadel
pnpm install
pnpm exec vitest run     # or: pnpm test

The suite is fully offline: no live Cortadel server, no network, no CORTADEL_* env vars, no keys. Every HTTP call is stubbed at n8n's httpRequestWithAuthentication boundary. All test data uses e2e-* user ids.

@langchain/core, @langchain/openai and @langchain/anthropic are installed as devDependencies only, purely so test/message-compat.test.ts can assert against the real classes and the real provider message converters instead of restating a comment. The published package still has no dependencies at all, and files ships dist/ alone. If they are absent that one suite skips itself; the rest still runs.

Also useful:

pnpm typecheck           # tsc --noEmit over the shipped surface, then tsconfig.test.json over test/
pnpm run build           # tsc + copy icons into dist/

pnpm typecheck is two passes on purpose. The build config keeps test/ out of dist/, which also kept it out of tsc --noEmit; tsconfig.test.json adds it back as a check-only pass — with module: esnext, because vitest loads the tests as ES modules and one of them uses top-level await import().

Requirements

• n8n with the AI nodes available (the ai_memory port only exists on the AI Agent node). Verified against n8n-workflow 2.16.0 — the node uses NodeConnectionTypes.AiMemory and usableAsTool, both long-standing in current n8n.
• Node.js ≥ 20.
• A running Cortadel server — hosted at https://app.cortadel.ai, or self-hosted with docker compose up (→ http://localhost:3001). See docs/self-hosting.md.

Links

• Source and issues: https://github.com/cortadel/cortadel
• Cortadel: https://cortadel.ai

Licensed under Apache-2.0.