Knowledge Pack

The Knowledge Pack (@hellmai/lumenflow-packs-knowledge) provides building blocks for permission-aware retrieval. Callers supply a source reader; ACLs travel with ingested documents and are enforced again during retrieval, deletions can be represented as verifiable tombstones, and retrieved content is returned as citation-tagged data separated from instructions.

Caution

The knowledge manifest sets trust_tier: declarative and tools: [], so it declares no kernel-callable tools. The package includes no built-in filesystem, network, or embedding-vendor client, but its optional caller-injected KnowledgeEmbeddingProvider receives each document’s content. Processing location depends on that provider; this pack does not promise local processing or a customer-hosted service.

What it provides

• ingestLocalKnowledgeSource — ingests a source through a caller-injected LocalKnowledgeSourceReader and an optional, caller-injected KnowledgeEmbeddingProvider. The package imports no filesystem or network client and no embedding-vendor SDK directly. When an embedding provider is configured, it receives each document.content; processing location and data handling depend on that provider.
• detectDeletedDocuments / verifyDeletionPropagated — diff two ingestion snapshots into verifiable deletion tombstones (golden journey 12).
• enforceRetrievalAcl / assertRetrievable — 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 — 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 '@hellmai/lumenflow-packs-knowledge';
import { enforceRetrievalAcl } from '@hellmai/lumenflow-packs-knowledge/acl/retrieval-enforcement';
import { assembleRetrievalContext } from '@hellmai/lumenflow-packs-knowledge/citations';

Wiring a source

The adapter takes source access and embedding generation as injected collaborators rather than owning them. An operator can plug 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 a service they select and configure. Nothing in this pack ships a default filesystem reader or a default embedding vendor.

Manifest declaration

The manifest declares the pack as declarative with no registered tools:

id: knowledge
trust_tier: declarative
tools: []

These are the relevant manifest fields; private: true appears in the npm package.json metadata, not in manifest.yaml. The empty tools list means this pack does not register kernel-callable tools. An integrator can compose its library primitives behind a separate tool surface.

Related

• Kernel: Policy Engine — the permission model enforceRetrievalAcl layers on top of.
• Protocol Adapters Pack — another July-wave pack that ships a library surface ahead of its kernel tool wiring.