Flow AgentsEvidence-gated workflows for coding agents, carried into the agent tools you already use

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. It uses Node.js built-ins and an included YAML parser, with no external runtime installation. The failsafe YAML schema preserves text scalars and resolves bounded, acyclic anchors in nested evidence; see the store contract for limits.
  • 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.

Opt-in Flow ingest pilot#

The Knowledge Kit also ships ingest/cli.js and the knowledge.ingest-flow-pilot adapter. This pilot delegates ingest gate evaluation and advancement to the installed public Flow CLI, while the kit produces capture, classification and routing operation claims. Missing capture evidence holds the run before any store write. The pilot requires POSIX Python 3 for descriptor-relative artifact publication and refuses if that prerequisite is unavailable. Source text and provenance stay in the raw record; these operation claims do not independently verify source content.

See the kit pilot instructions for prerequisites, commands, retained traces and failure recovery limits. KnowledgeFlowRunner, the other flows and existing live integrations remain available. Compile/promote migration and host acceptance are separate work.

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#

Source: docs/knowledge-kit.md