KnowledgeHost

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-11 Retrieval & Indexes
Platform / plane	Knowledge Platform / Knowledge & Memory
Deployment granularity	standalone host
Status	target · ConnectSoft.Factory.Knowledge
Built from	connectsoft-microservice · libraries: connectsoft-extensions-data-ingestion, connectsoft-extensions-data-storage-abstractions, connectsoft-extensions-ai, connectsoft-extensions-saas-abstractions, connectsoft-extensions-saas-asp-net-core, connectsoft-extensions-messaging-model, connectsoft-extensions-messaging-model-orleans, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-compliance, connectsoft-extensions-observability
Decisions	ADR-0005, ADR-0013, ADR-0016, ADR-0017, ADR-0019
Traceability	FR-07 FR-08 FUX-06 FUX-09 NFR-03 NFR-10 NFR-16 XL-07 XL-14

Purpose and responsibilities

KnowledgeHost is the physical host of the Knowledge Platform: six modules over three stores. It owns composition, the vector-store profile selection (ADR-0013: Qdrant as the self-hosted reference, Azure AI Search as the managed alternative, PgVector and SQL Server as options), the embedding and reranking client to the model gateway, the source connectors reached through the Integration platform, and the transactional infrastructure (NHibernate unit of work plus outbox per module). It holds no domain state.

Context and boundaries

flowchart LR
    S["KnowledgeHost"]
    AgentRuntimeWorker["AgentRuntimeWorker"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    ToolExecutorHost["ToolExecutorHost"] -->|grpc| S
    S -->|grpc| ModelGatewayHost["ModelGatewayHost"]
    S -->|grpc| ControlPlaneApi["ControlPlaneApi"]
    S -->|grpc| GovernanceHost["GovernanceHost"]
    S -->|grpc| IntegrationHost["IntegrationHost"]
    S -->|sync-http| ext_identity_platform["ext-identity-platform"]

Hold "Alt" / "Option" to enable pan & zoom

flowchart LR
    subgraph Host["KnowledgeHost (2 to 10 replicas)"]
        direction TB
        Ing["KnowledgeIngestionService"]
        Ret["VectorMemoryService (retrieval and indexes)"]
        Ctx["ContextBuilderService"]
        Art["ArtifactService"]
        Mem["MemoryPromotionService"]
        Repo["RepositoryIntelligenceService"]
    end
    RT["AgentRuntimeWorker"] -- "Assemble, Store, tools" --> Host
    TE["ToolExecutorHost"] -- "knowledge and repository tools" --> Host
    SB["StudioBff"] --> Host
    Host --> SQL["('knowledge-sql')"]
    Host --> VEC["('vector-index')"]
    Host --> BLOB["('artifact-blob')"]
    Host -- "Embed, Rerank" --> MG["ModelGatewayHost"]
    Host -- "connections" --> IH["IntegrationHost"]
    Host -- "decisions, credentials" --> GOV["GovernanceHost"]

Hold "Alt" / "Option" to enable pan & zoom

Domain model

None modelled

No aggregates are modelled for this item yet.

No entities modelled.

Entities and value objects

None modelled

No entities or value objects are modelled for this item yet.

Data model and storage

Store	Role	Engine / profile	Tables
Knowledge metadata store	primary	azure-sql / nhibernate-sqlserver	—
Vector index	index	qdrant / vector-qdrant	—
Artifact content store	blob	blob / azure-blob	—
Cache and coordination	cache	redis / azure-cache	—

None modelled

No tables are modelled for this item yet.

Schemas per module (ingestion, retrieval, context, artifacts, memory, repositories) in knowledge-sql; vectors in vector-index behind the scope filter contract; content in artifact-blob by hash. Indexes are derived and rebuildable; they are restored last (D30).

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/knowledge/health	KnowledgeHealth	factory.health.read	read	natural	GW-01	Liveness, readiness and dependency health (knowledge store, vector index, blob store, model gateway for embeddings, source connectors).
GET	/knowledge/meta/modules	KnowledgeModules	factory.meta.read	read	natural	GW-03	Modules, vector profile in use (ADR-0013) and embedding profile versions of the indexes.

None modelled

No gRPC methods are modelled for this item yet.

Messages

None modelled

No events are modelled for this item yet.

None modelled

No commands are modelled for this item yet.

None modelled

No consumed events are modelled for this item yet.

Workers and jobs

None modelled

No workers are modelled for this item yet.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Knowledge:Host	EnabledModules	string[]	[ingestion, retrieval, context, artifacts, memory, repository-intelligence]	no	no	Modules composed into this host.
Knowledge:VectorProfile	Kind	enum	qdrant	no	no	Vector store profile per ADR-0013 (qdrant self-hosted reference, azure-ai-search managed alternative, pgvector, sqlserver).
OrleansMessaging	ServiceName	string	knowledge	no	no	Messaging profile service name.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.knowledge.host.requests	counter	{request}	module, route, status	Requests per module.
connectsoft.factory.knowledge.host.index_lag	gauge	s	tenant, index	Age of the newest published snapshot not yet indexed.

Security

Authentication	client-credentials
Scopes	factory.health.read (Health probes.); factory.meta.read (Module metadata.)
Roles	Operator, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	shared-write
Secrets	knowledge-sql (key-vault, rotate 90 d); vector-index (key-vault, rotate 90 d); artifact-blob (key-vault, rotate 90 d); messaging-transport (key-vault, rotate 90 d)

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
ModelGatewayHost	grpc	Embeddings and reranking through embedding and reranker profiles.	degrade	yes
ControlPlaneApi	grpc	Scope resolution and project source scope.	fail-fast	yes
GovernanceHost	grpc	Policy decisions for retrieval and memory promotion; secret brokering for source connections.	fail-fast	yes
IntegrationHost	grpc	Source connections and connectors (Git, Azure DevOps, SharePoint, Confluence…).	degrade	yes
ext-identity-platform	sync-http	Workload identity and caller validation.	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
AgentRuntimeWorker	grpc	Context assembly, retrieval tools, artifact writes, repository tools.	—	yes
StudioBff	sync-http	Sources, collections, search, artifacts and memory views.	—	yes
ToolExecutorHost	grpc	Knowledge and repository tools exposed as MCP tools.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Vector index unavailable	retrieval errors and health	retrieval degrades to full-text and metadata; indexes are derived and rebuilt from approved sources after restore (restore order last)	none	240
Model gateway unavailable for embeddings	embed call failures	ingestion pauses at the embedding stage; chunks stay queued; retrieval serves existing vectors	index lag	60
Host crash	readiness probe	replicas restart; ingestion jobs resume from their journal	none	5

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	standalone host
Topologies	saas-default, hybrid, on-prem, hybrid-compute
Runtime	aks; replicas 2–10
Ports	https 7700, grpc 7702, silo 11700, gateway 30700

In the hybrid profile the host runs inside the customer's network next to the repositories and documents it ingests; only receipts, snapshots metadata and promoted memory proposals cross to the Control plane.

Current implementation

The agent host sample does chunking, embeddings, upsert and top-k search with tenant filtering applied after search and only the in-memory connector wired; ConnectSoft.Extensions.DataIngestion provides ingestion primitives without a source, ACL, version or deletion lifecycle; no graph, artifact, context or memory service exists.

Later capabilities

Knowledge graph service as a separate module when graph domains outgrow projections (KnowledgeGraphService, later); knowledge replay; pattern catalog; prompt memory.

Decisions and traceability

Family	Ids
FR	FR-07, FR-08
FUX	FUX-06, FUX-09
NFR	NFR-03, NFR-10, NFR-16
XL	XL-07, XL-14

Related

• Knowledge overview · Deployment · Security

• Modules: KnowledgeIngestionService · VectorMemoryService · ContextBuilderService · ArtifactService · MemoryPromotionService · RepositoryIntelligenceService

• Knowledge Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map