Upload metadata
Requests carry module, thread, message, user, and organization metadata so retrieval can be scoped later.
Knowledge
Document context is ingested asynchronously and retrieved with scoped metadata.
Uploads are extracted into full markdown, chunks, embeddings, and optional graph context. Chat and agent tools can inspect ingestion status, wait for documents, and retrieve content when it is ready.
Ingestion path
Knowledge starts as queued work, not inline chat work.
This keeps upload processing, extraction, embedding, and graph updates away from the request that renders the message.
Extraction output
Extractors return full markdown plus chunks and metadata. Knowledge can still expose full extracted content when vector services are not active.
Background processing
Ingestion runs through queued services so the UI and chat action do not block on extraction or embedding.
Retrieval path
Retrieval chooses the available source for the current context.
The agent should not assume every uploaded document is immediately embedded or graph-indexed.
Hybrid recall
Vector (semantic) and lexical search run together and their scores are fused. Metadata-aware weighting lets summaries and segments outrank raw chunks when both match.
Graph expansion & rerank
Bounded knowledge-graph traversal promotes connected items from the top results; a cross-encoder reranker sets the final ordering when one is configured.
Markdown fallback
When vector services are not active, tools still retrieve full extracted markdown for documents that completed extraction.
Scoped by contract
Queries carry user, organization, and module scope, and visibility is re-checked per item — including across graph traversal, so expansion never crosses a scope boundary.
Safety of retrieval
Scope is part of the retrieval contract.
Knowledge data can be shared infrastructure, so filters cannot be optional decoration.
User and organization
Stored metadata should preserve user and organization context so retrieval can apply tenancy boundaries.
Module and thread
Conversation tools should filter by module and conversation/thread identifiers when searching chat content.
Request identity
Extraction request ids keep background work correlated with the uploaded source and later retrieval.
Configuration
Knowledge depends on extractor and provider configuration.
A document-aware module should not hardcode accepted files or retrieval behavior. It should read configured extractors, MIME types, and knowledge providers from the runtime.
Extractor catalog
Extractors declare the MIME types they can ingest. Composer upload controls should use that list instead of local UI constants.
Embedding provider
Vector retrieval requires an embedding model/provider. If it is not configured, the extracted markdown can still be read directly.
Graph and vector stores
Knowledge can write chunks, embeddings, and graph context to the configured stores while preserving request and scope metadata.
Ingestion and retrieve flow
Extraction, ingestion, and retrieval are separate stages.
This separation lets uploads finish quickly, extraction run asynchronously, and agents query whichever source is ready for the current conversation.
UploadFile is attached with module, thread, message, user, and organization context.
MIME matchThe runtime selects an extractor from configured ingestible MIME types.
ExtractorThe extractor returns full markdown, chunks, metadata, and request identity.
QueueIngestion work runs in the background instead of blocking the message action.
EmbeddingChunks are embedded when an embedding provider is configured.
GraphGraph context is added when a knowledge graph provider is configured.
Query serviceRetrieve tools apply metadata filters before searching knowledge sources.
Agent toolsThe agent can inspect status, wait, search embeddings, or read full markdown.
Next
Related pages
Use these pages to move from the concept to adjacent parts of the runtime.