AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
icon: 📚
Knowledge Base
A project-scoped document store: users upload PDF/DOCX/TXT/CSV files, which are split into text chunks, optionally embedded with a 768-dim vector model, and stored for semantic similarity search. Agents search one or more KB files to retrieve context. All editions; requires READ_KNOWLEDGE_BASE/WRITE_KNOWLEDGE_BASE permissions, and an AI provider for embedding generation.
Entities & services
- knowledge_base_file — links a project, a stored
filerecord, and adisplayName(uniquefileId). - knowledge_base_chunk —
content,chunkIndex(0-based),embeddingvector(768)(nullable),metadataJSONB; indexed on(projectId, knowledgeBaseFileId). knowledgeBaseService:createFile,extractChunks,storeChunks,ingestFile(extract → embed in batches of 50 → store),search(raw SQL cosine<=>),listChunks,deleteFile.- Files under
packages/server/api/src/app/knowledge-base/.
How it works
- REST under
/v1/knowledge-base/files: register existing file,upload(upload + synchronously extract+store chunks), list, delete,.../chunks/count,.../extract-chunks,.../store-chunks,.../chunks, and.../search(cosine similarity, scored, optionalsimilarityThreshold). - Chunking: plain text/DOCX/PDF use a 2000-char sliding window with 200-char overlap; CSV repeats the header row in each chunk to preserve column context.
- Extractors:
unpdf(PDF),mammoth(DOCX), plain text.
Gotchas
- pgvector is not created by a migration — the
AddPgVectorExtensionmigration is a no-op becauseCREATE EXTENSIONcrash-loops managed Postgres where the app user lacks privileges. - Instead
knowledgeBaseSeedrunsknowledgeBaseSchema.ensure()on every boot (under the migration lock, wrapped intryCatch): creates the extension + table + indexes when available, else skips silently. Installing pgvector later activates KB on the next restart, no redeploy. PGLite bundles pgvector so CE works out of the box. - Gating: backend
preHandlerthrowsFEATURE_DISABLEDwhen the extension is absent (cached once observed); frontend hides the UI via thePGVECTOR_AVAILABLEflag. - No Knowledge Base section in local agent settings?
docker-compose.dev.ymlruns plainpostgres:14.4(no pgvector), unlikedocker-compose.yml'spgvector/pgvector:0.8.0-pg14. Swap the image, recreate the db container, restart the API. Check withGET /api/v1/flags→PGVECTOR_AVAILABLE. - Allowed MIME types (
KB_ALLOWED_MIME_TYPES): PDF, plain text, CSV, DOCX only. chunkIndexis a place in the file, and one place holds one row.storeChunksresolves every submitted chunk to an index before it writes anything. An id moves that row to the index and displaces whoever was sitting there. No id takes over the row already at that index, which is what keeps a chunk id stable when a file is indexed again. A repeated index keeps the last copy. A repeated id, or one naming no chunk of this file, is refused rather than guessed at. All of it runs in one transaction behind apessimistic_writelock on the file row. Thirteen review rounds on this endpoint were the same bug in different payloads, so add a case toknowledge-base-storage.test.tsinstead of a branch to the service.- Nothing in the database enforces one row per place. There is no unique index on
(knowledgeBaseFileId, chunkIndex), so two writes arriving at once are held apart by that row lock alone, and the lock is a no-op on PGLite because it runs a single connection. The index ships with the indexing work. - Uploads are embedded when they arrive; older files are embedded on the agent's first search.
uploadFileembeds before writing and refuses a file it cannot index. Files from before that change get their missing embeddings fromembedMissingChunks, which only the agent's knowledge-base tool calls, because the/searchroute is open to read-only members and indexing is a paid write.isSearchablestill guards the search, so an agent says a file could not be indexed instead of reporting that it does not mention what was asked.
Key files
Entry point: knowledgeBaseModule, registered in packages/server/api/src/app/app.ts.
packages/server/api/src/app/knowledge-base/— the whole backend slice: module, controller, service, both entities, and the pgvector schema checkpackages/server/api/src/app/database/seeds/knowledge-base-seed.ts— the boot-timeensure()that creates the extension and tablepackages/core/shared/src/lib/automation/knowledge-base/— shared zod schemaspackages/web/src/features/agents/agent-tools/— frontend API client, hooks, and theKnowledgeBaseSectioncomponentpackages/server/api/src/app/flags/flag.service.ts— computes thePGVECTOR_AVAILABLEflag the UI gates onpackages/server/api/test/unit/app/knowledge-base/andpackages/server/api/test/integration/ce/knowledge-base/— service, validation, and upload tests
Paths verified 2026-07-17.