Skip to content
LumenFlow

Knowledge Pack

The Knowledge Pack (@lumenflow/packs-knowledge, WU-3526, INIT-091 phase 4) is the dev-side half of permission-aware retrieval: a local knowledge source is ingested entirely on the local machine, its ACLs travel with every document and are enforced again at retrieval time, deletions propagate as verifiable tombstones, and everything retrieved comes back as citation-tagged data — never as instructions.

What it provides

Section titled “What it provides”
  • ingestLocalKnowledgeSource (adapters/local-source.ts) — ingests a source through a caller-injected LocalKnowledgeSourceReader and an optional, caller-injected KnowledgeEmbeddingProvider. No filesystem, network client, or embedding-vendor SDK is imported directly, so document content and any source credentials never transit to Cloud, and no embedding provider is hardcoded — embeddings are customer-selected or customer-hosted.
  • detectDeletedDocuments / verifyDeletionPropagated — diff two ingestion snapshots into verifiable deletion tombstones (golden journey 12).
  • enforceRetrievalAcl / assertRetrievable (acl/retrieval-enforcement.ts) — the single retrieval-time enforcement point: an unauthorised principal can never retrieve restricted content, and a deleted document is excluded regardless of ACL.
  • buildCitation / toRetrievedChunk (citations.ts) — attach source/document/revision lineage to every retrieved chunk. assembleRetrievalContext keeps caller instructions and retrieved content in separate fields; retrieved text only ever lands inside a fenced <untrusted-knowledge-data> block, so an injection-bearing document cannot alter agent instructions.
import { ingestLocalKnowledgeSource, detectDeletedDocuments } from '@lumenflow/packs-knowledge';
import { enforceRetrievalAcl } from '@lumenflow/packs-knowledge/acl/retrieval-enforcement';
import { assembleRetrievalContext } from '@lumenflow/packs-knowledge/citations';

Wiring a real local source

Section titled “Wiring a real local source”

The adapter takes filesystem access and embedding generation as injected collaborators rather than owning them: an operator plugs in a concrete LocalKnowledgeSourceReader (for example, one backed by node:fs/promises walking a local directory and resolving ACLs from a local policy file) and, optionally, a KnowledgeEmbeddingProvider backed by whichever embedding service the customer selects or hosts. Nothing in this pack ships a default filesystem reader or a default embedding vendor.

Manifest declaration

Section titled “Manifest declaration”
id: knowledge
private: true
tools: []
evidence_types:
  - knowledge-citation
  - knowledge-deletion-record

private: true and tools: [] are both deliberate: this pack is a set of composable library primitives for instruction/data separation and ACL-preserving retrieval, not a pack that registers its own kernel-callable tools. An integrator composes these primitives behind their own tool surface.

Section titled “Related”