Role OS subsystem

Knowledge Core.

Role-aware retrieval where overlay law governs what gets retrieved, ranked, and cited. Not generic RAG — governed input with hard role boundaries.

Get started Read the Handbook

Install

npm install @roleos/knowledge-core

Retrieve

const bundle = await retrieve({ store, roleId, taskText, overlay })

Result

// bundle.selected, bundle.rejected, bundle.provenance, bundle.warnings

Governed Retrieval

Same corpus, different roles, materially different evidence.

Role Overlays

Declarative per-role configs control vocabulary, source policy, reranking weights, and synthesis rules.

Evidence Bundles

Structured output with selected chunks, rejected candidates, provenance posture, and retrieval warnings.

Fallback Governance

Explicit handling for weak, stale, conflicted, and missing evidence — no silent garbage.

Source Diversity

Metadata filter enforces forbidden sources, trust tiers, freshness penalties, and per-source caps.

BM25 + Semantic

Dual-lane retrieval with SQLite FTS5 lexical search and optional Ollama embeddings.

86 Tests

Contract validation, pipeline correctness, role distinctiveness, and governance checks all proven.

Usage

Install

npm install @roleos/knowledge-core

Ingest & Retrieve

import { CorpusStore, ingestFixtureCorpus, retrieve } from '@roleos/knowledge-core';

const store = new CorpusStore(':memory:');
ingestFixtureCorpus(store, './corpus.json');

const bundle = await retrieve({
  store,
  roleId: 'security-reviewer',
  taskText: 'Review auth middleware',
  overlay: securityOverlay,
  lexicalOnly: true,
});

// bundle.selected — scored evidence
// bundle.rejected — why candidates failed
// bundle.provenance — trust posture