KnowFlow

English | 简体中文 | Website & docs

An agent-native Markdown knowledge workspace: capture sources, let any coding agent synthesize them into linked wiki pages, review with one word, and explore what you know.

KnowFlow keeps the workflow inspectable: URLs and notes land in raw/ through deterministic capture, any coding agent — ZCode, Codex CLI, Claude Code, OpenCode — synthesizes them into structured Markdown pages by following a written contract, and you approve each page by flipping one frontmatter word. Local tools build a knowledge graph, check wiki health, and keep unreviewed pages out of the graph and the search index. Optional semantic search is available when you configure an embedding API key.

• Own the knowledge layer — plain Markdown, editable templates, and [[wikilinks]] instead of a closed database.
• Work with any agent — KnowFlow is the host, not the AI: capture stays deterministic, and synthesis follows one written contract (docs/agents/synthesize.md) that ZCode, Codex CLI, Claude Code, and OpenCode each execute into the same result.
• Review is one word — synthesized pages arrive as status: pending; flip them to reviewed, or delete to reject. Unreviewed pages stay out of the graph and the search index.
• See structure, not just search results — generate an interactive graph and catch broken or isolated pages.

Demo: Run the text-to-graph walkthrough, then explore the generated graph in your browser.

Quick start

Requires Node.js 18+, Python 3.10+, Bash, and curl.

Install from npm — or install from source if you prefer:

npm install -g @jerryjiao/knowflow
knowflow init my-wiki
cd my-wiki
knowflow ingest "Karpathy's LLM Wiki essay: an agent curates saved links into durable, linked wiki pages." --source text
knowflow compose --list          # raw material with no wiki page yet
# hand the list to any coding agent: "synthesize raw/ per docs/agents/synthesize.md"
knowflow status                  # shows the pending pages your agent drafted
knowflow graph --no-open         # pending pages stay out until you review them

This creates a standalone project, captures one note in raw/, and builds a graph from the starter Wiki. ingest does not synthesize wiki pages — your coding agent does. Point any agent at the synthesis contract and it drafts status: pending pages straight into their final directories; your review flips them to reviewed, and only then do they enter the graph and the search index.

One-off usage without a global install also works: npx @jerryjiao/knowflow@latest <command>.

The workflow

URL or note
    │
    ▼
raw/ Markdown ── deterministic capture, no AI
    │
    ▼
any coding agent synthesizes ── one shared contract
    │                           docs/agents/synthesize.md
    │                           (ZCode / Codex CLI / Claude Code / OpenCode)
    ▼
wiki/ pages arrive as status: pending
    │
    ▼
you review ── flip pending → reviewed, or delete to reject
    │
    ▼
knowledge graph + optional semantic search
   (pending pages stay out of both)

1. Capture. knowflow ingest fetches a URL or a note into raw/ as Markdown. Deterministic, no AI, nothing else written.
2. Synthesize. Any coding agent reads raw/ and follows docs/agents/synthesize.md: one source page per raw file plus minimal entity pages, YAML frontmatter with created_from provenance and status: pending, (EXTRACTED)/(INFERRED) confidence markers on every key point, strict root-relative [[wikilinks]], slug-based file names. knowflow compose --list derives what is still unsynthesized.
3. Review. Approving a page means changing one word — pending to reviewed. Rejecting means deleting the file. knowflow check runs the eight-condition conformance gate; knowflow health reports broken links.
4. Build. knowflow graph and knowflow index build strip frontmatter and skip pending pages, so unreviewed content never reaches the graph or the search index. knowflow fix never touches pending pages.

KnowFlow is inspired by Andrej Karpathy's LLM Wiki: knowledge becomes more useful when it is curated into durable, connected pages instead of being left in a pile of saved links.

What is included

• Capture plain text and supported URLs as raw Markdown.
• Initialize portable projects with JSON configuration and editable page templates.
• Ship a written synthesis contract any coding agent can follow — YAML frontmatter with created_from provenance and status: pending, (EXTRACTED)/(INFERRED) confidence markers, strict [[wikilinks]], and slug file names.
• Derive the to-synthesize list with knowflow compose --list — raw files minus pages already carrying a created_from pointer, zero state files.
• Gate unreviewed content: graph and index build skip pending pages, health exempts them from the orphan rule, and fix never touches them.
• Enforce page anatomy with knowflow check, an eight-condition conformance gate over the four page types.
• Generate graph.html and graph.json without an API key.
• Check broken links, undersized files, and isolated pages.
• Repair empty links, create missing pages, pad small files, and link orphans.
• Query a previously built vector index with optional Zhipu AI embeddings.

Commands

Command	What it does
knowflow init [directory]	Create a standalone project; defaults to the current directory
knowflow ingest <url-or-text>	Capture a URL or text in raw/
knowflow compose --list	List raw material not yet synthesized into wiki pages (derived from created_from pointers; no state files)
knowflow check	Run the eight-condition conformance gate over source/entity/concept/comparison pages; exits 1 on any violation
knowflow graph [--no-open]	Generate graph.html and graph.json from Wiki pages (pending pages are skipped)
knowflow fix [--dry-run]	Repair empty links, missing pages, small files, and orphans (never touches pending pages)
knowflow health	Check broken links, small files, and isolated pages (pending pages are exempt from the orphan rule)
knowflow tags	Build tag/<name>.md hub pages from [[tag/<name>]] links
knowflow status	Show raw, Wiki, graph, vector-index, and API-key status, plus the pending-review page list
knowflow index build [--incremental]	Build the vector index for semantic search (incremental skips unchanged pages; pending pages are skipped)
knowflow index stats [--verbose] [--json]	Report index coverage, cache, and token estimates
knowflow query <text>	Query an existing vector index (hybrid vector + keyword ranking)
knowflow ask <question>	Answer a question from retrieved Wiki context, with citations

KnowFlow searches upward from the current directory for the nearest .knowflowrc, so commands also work inside project subdirectories.

Install from source

git clone https://github.com/jerryjiao/knowflow.git
cd knowflow
npm install
npm link
knowflow init ../my-wiki

Running init again preserves existing configuration, the starter index, and customized templates.

Project layout

my-wiki/
├── .knowflowrc
├── raw/                 # captured source material
├── wiki/
│   ├── index.md
│   ├── sources/
│   ├── entities/
│   ├── concepts/
│   └── comparisons/
├── graph/               # generated graph.html and graph.json
└── templates/           # editable Markdown templates

Configuration

knowflow init writes a JSON .knowflowrc. Relative paths resolve from the directory containing that file.

{
  "wiki": {
    "root": "./wiki",
    "rawDir": "./raw"
  },
  "graph": {
    "output": "./graph/graph.html"
  },
  "health": {
    "minFileSize": 100,
    "excludeOrphanDirs": ["sources/"]
  }
}

health.excludeOrphanDirs lists directories whose pages are expected to be unreferenced (daily-sync feeds, inboxes) and should not count as isolated pages. knowflow tags regenerates every hub page under wiki/tag/, so re-running it after new tagged pages arrive is safe and idempotent.

Graph generation, health checks, capture, and status do not require an API key. Semantic search (index build, query, ask) needs an embedding-provider key in the project environment or a project-root .env file. The default provider is Zhipu:

ZHIPUAI_API_KEY=your-key-here

The embedding provider is pluggable via the optional embedding section of .knowflowrc. Switch to OpenAI, or point at any OpenAI-compatible endpoint:

{
  "embedding": { "provider": "openai" }
}

{
  "embedding": {
    "provider": "custom",
    "baseUrl": "https://your-relay.example.com/v1",
    "model": "your-embedding-model",
    "apiKeyEnv": "RELAY_API_KEY",
    "chatModel": "your-chat-model"
  }
}

Presets (zhipu, openai) fill in endpoint, model, and key-env defaults; every field can be overridden individually. chatModel backs knowflow ask. Malformed embedding sections fail fast with the offending field named.

Current limitations

• KnowFlow embeds no LLM. Synthesis is delegated to your external coding agent following docs/agents/synthesize.md — an embedded synthesis API was a deliberate no.
• URL capture uses Jina Reader. YouTube and some logged-in platforms may also require yt-dlp or an authenticated browser workflow.
• query / ask need a vector index built with knowflow index build and a Zhipu AI (default) or other embedding-provider API key.
• bookmark_sync.sh depends on the optional third-party ft command.
• Generated graph HTML loads vis-network from a CDN when opened.

Roadmap

• Standalone project initialization and portable paths
• Raw URL/text capture, Wiki health checks, and interactive graphs
• CLI tests and CI across supported Node.js versions
• knowflow index and pluggable embedding providers
• A first-class agent workflow from raw capture to reviewed Wiki pages (shared synthesis contract + review gates)
• Incremental ingestion and duplicate-source detection
• Extractor/plugin system and a local Web UI

Ideas and focused pull requests are welcome. Start with the contribution guide, run the text-to-graph example, or propose a use case in GitHub Issues.

Development

npm install
npm run check
npm test
npm pack --dry-run

See the changelog for release notes and the security policy for responsible disclosure.

License

MIT © Jerry Jiao