feat(core): Cache agent knowledge sandboxes with lazy file materialization

[bjorger]

Summary

• Reuse stable per-agent knowledge sandbox workspaces instead of rebuilding a full-corpus sandbox for each operation.
• Materialize only missing or stale files on demand, using manifest entries with per-file binary-data hashes for freshness.
• Route CSV operations through backend file streaming so they do not require sandbox materialization.
• Keep sandbox invalidation focused on delete paths, and add focused coverage for cache lifecycle, materialization, stream writes, and UI/tool behavior.

How to test

To enable the Knowledgebase / Sandboxing add those variables to your .env

N8N_AGENTS_AI_SANDBOX_ENABLED=true
N8N_AGENTS_AI_SANDBOX_PROVIDER=daytona
N8N_AGENTS_AI_SANDBOX_IMAGE=daytonaio/sandbox:0.5.0
N8N_AGENTS_AI_SANDBOX_TIMEOUT=300000
N8N_AGENTS_AI_SANDBOX_NAME_PREFIX=
DAYTONA_API_URL=https://app.daytona.io/api
DAYTONA_API_KEY=dtn_XYZ

Related Linear tickets, Github issues, and Community forum posts

https://linear.app/n8n/issue/AGENT-240/feature-agents-kb-sandbox-integration

Review / Merge checklist

• I have seen this code, I have run this code, and I take responsibility for this code.
• PR title and summary are descriptive. (conventions)
• Docs updated or follow-up ticket created.
• Tests included.
• PR Labeled with Backport to Beta, Backport to Stable, or Backport to v1 (if the PR is an urgent fix that needs to be backported)

[codecov]

Codecov Report

❌ Patch coverage is 59.68109% with 354 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../src/modules/agents/agent-knowledge-csv.service.ts	4.05%	142 Missing ⚠️
...gents/agent-knowledge-sandbox-workspace.service.ts	75.11%	53 Missing ⚠️
...lities/src/sandbox/write-stream-to-sandbox-file.ts	62.24%	20 Missing and 17 partials ⚠️
.../cli/src/modules/agents/agent-knowledge.service.ts	74.26%	35 Missing ⚠️
.../features/agents/components/AgentChatToolSteps.vue	46.34%	22 Missing ⚠️
.../agents/agent-knowledge-sandbox-command.service.ts	76.54%	19 Missing ⚠️
...s/agents/agent-knowledge-sandbox-config.service.ts	59.37%	13 Missing ⚠️
...-ui/src/features/agents/views/AgentBuilderView.vue	37.50%	10 Missing ⚠️
...modules/agents/tools/knowledge/search.operation.ts	50.00%	9 Missing ⚠️
.../modules/agents/tools/knowledge/file-references.ts	22.22%	7 Missing ⚠️
... and 5 more

📢 Thoughts on this report? Let us know!

[github-actions]

Performance Comparison

Comparing current → latest master → 14-day baseline

loads S-tier workflow @tier:S

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
canvas-cold-load-S-ms	4333.00 ms	4333.00 ms	4175.60 ms (σ 388.55)	+0.0%	+3.8%	✅

docker-stats

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
docker-image-size-runners	395.00 MB	395.00 MB	401.20 MB (σ 2.06)	+0.0%	-1.5%	🔴
docker-image-size-n8n	1423.36 MB	1536.00 MB	1450.22 MB (σ 66.31)	-7.3%	-1.9%	✅

Idle baseline · instance-ai

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
instance-ai-heap-used-baseline	140.59 MB	140.59 MB	137.73 MB (σ 2.84)	+0.0%	+2.1%	⚠️
instance-ai-rss-baseline	271.50 MB	271.50 MB	330.60 MB (σ 58.91)	+0.0%	-17.9%	⚠️

Idle baseline · agents

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
agents-rss-baseline	399.19 MB	399.19 MB	350.32 MB (σ 46.78)	+0.0%	+14.0%	⚠️
agents-heap-used-baseline	141.75 MB	141.75 MB	137.39 MB (σ 3.53)	+0.0%	+3.2%	⚠️

Idle baseline · memory

Metric	Current	Latest Master	Baseline (avg)	vs Master	vs Baseline	Status
memory-rss-baseline	262.11 MB	262.11 MB	324.25 MB (σ 46.38)	+0.0%	-19.2%	⚠️
memory-heap-used-baseline	137.20 MB	137.20 MB	131.67 MB (σ 3.52)	+0.0%	+4.2%	⚠️

How to read this table

• Current: This PR's value (or latest master if PR perf tests haven't run)
• Latest Master: Most recent nightly master measurement
• Baseline: Rolling 14-day average from master
• vs Master: PR impact (current vs latest master)
• vs Baseline: Drift from baseline (current vs rolling avg)
• Status: ✅ within 1σ | ⚠️ 1-2σ | 🔴 >2σ regression

[github-actions]

Grind results — pre-merge flake detection (N=50)

File	Passes
packages/frontend/editor-ui/src/app/stores/settings.store.test.ts	50/50 ✅
packages/frontend/editor-ui/src/features/agents/__tests__/AgentBuilder.readonly.test.ts	50/50 ✅
packages/frontend/editor-ui/src/features/agents/__tests__/AgentBuilderView.test.ts	50/50 ✅

Spawn-per-iteration mode. Catches post-teardown async flakes that vitest --repeat misses. See DEVP-198 for design notes.