Kontour Flow Agents

Knowledge Kit

The Knowledge Kit is a Flow Kit for durable, gated knowledge storage. It packages a store contract, five pipeline flows, pluggable store adapters, and a parameterized contract test suite — all validated and installed through the flow-agents kit path.

What it ships

Store contract — four record types (raw, compiled, concept, snapshot) with a defined mutation policy: every write goes through propose→evidence-gate→apply/reject. Required evidence fields are enforced at runtime; a missing field throws MISSING_EVIDENCE rather than silently passing. Supersede-not-delete: records that are superseded move to an archive state with full provenance intact, not removed.

Pipeline flows — five flows cover the full lifecycle:

Flow What it does
knowledge.ingest Capture → classify → route raw source material
knowledge.compile Normalize classified raws into durable notes with provenance links
knowledge.synthesize Detect similar clusters → propose a concept summary → evidence-gate → apply/reject
knowledge.consolidate Related-event trigger → decision snapshot → supersede prior snapshots (not delete)
knowledge.retire Gated status lifecycle: active → implemented → retired, with working-set exclusion

Store adapters — two adapters ship:

  • Default adapter — flat markdown files with YAML frontmatter, [[wikilink]] inline links, and a JSON graph index. Zero runtime dependencies; uses Node.js built-ins only.
  • Obsidian adapter — the same store contract rendered into one human-canonical Obsidian note per record. Category dots map to folder hierarchy; configurable frontmatter dimensions (e.g. territory/customer/initiative as filterable fields); living overview notes at the category root with sources nested below; superseded records moved to archive/ rather than deleted. The file is the record — no separate database, no sync step.

The output-shape story is why the adapter model matters: the same five flows and the same mutation gates produce a different rendering layer depending on which adapter is active. Authors choose the output shape that fits how they already think. (The Obsidian adapter is shipped; layout/dimensions refinements and person/entity card support are in development.)

Similarity detectors — the synthesize and consolidate flows accept a pluggable similarityDetector. Synthesis may search the broader related-record set. Consolidation first limits candidates to the snapshot’s exact category, so a topic such as decision.grounded-extraction cannot silently absorb records from decision or a descendant category:

Detector Approach Requires
defaultSimilarityDetector Category prefix overlap + Jaccard link-overlap (≥ 0.10) Nothing — built-in
createVectorSimilarityDetector Dense embeddings + cosine similarity ollama (nomic-embed-text, default threshold 0.60)

The vector detector is fail-closed: infrastructure failures throw EMBED_FAILURE rather than silently returning an empty cluster (which would be indistinguishable from “no similar records found”).

Exact consolidation sources — callers that already know the reviewed source set can pass sourceRecordIds. It is an ordered, non-empty allowlist and is mutually exclusive with append mode and a similarity detector. Missing, duplicate, non-compiled, or retired records fail before snapshot/proposal mutation:

await runner.consolidate(
  { topic: "decision.grounded-extraction", category: "decision.grounded-extraction" },
  {
    sourceRecordIds: ["compiled-record-id"],
    proposedBody: "The reviewed current decision.",
    rationale: "Consolidated from the displayed exact source set.",
    decision: "apply",
  }
);

If an invalid snapshot was applied, retire it through knowledge.retire with a rationale and superseding reference. Do not edit or delete store records by hand; retirement preserves the invalid snapshot and its provenance while removing it from the active working set.

Tests — an extensive automated test suite covering contract conformance, ingest/compile, synthesis, consolidation, similarity-vector matching, and retirement. The contract suite is parameterized — any adapter can run it by pointing KNOWLEDGE_ADAPTER at the adapter module.

Live-proven — keyless operation validated via a Strands agent + local ollama acceptance harness. The vector similarity detector is validated against nomic-embed-text with documented threshold guidance.

Quick reference

# Install the kit into the default Codex/global kit destination:
# CODEX_HOME, or ~/.codex when CODEX_HOME is unset
npx @kontourai/flow-agents kit install kits/knowledge

# Override the destination for a workspace, isolated home, or test
npx @kontourai/flow-agents kit install kits/knowledge --dest /path/to/workspace

# Run the contract suite against the default adapter
node --test kits/knowledge/evals/contract-suite/suite.test.js

# Run against an alternative adapter
KNOWLEDGE_ADAPTER=/path/to/my-adapter.js \
  node --test kits/knowledge/evals/contract-suite/suite.test.js

Source