Kforge

kforge

[English](README.md) | [简体中文](README.zh-CN.md)

kforge is a local-first, Markdown-first repo protocol and CLI for LLM-maintained knowledge bases.

It gives AI research work a durable filesystem shape: source evidence goes in, agents draft from that evidence, humans review the broad writes, and the useful knowledge lands back in versioned Markdown files.

raw evidence -> agent draft -> review -> wiki/claims -> health checks

The short version:

> Git for knowledge. CI for truth. Obsidian as IDE. LLM as compiler.

Why It Exists

Most AI knowledge workflows stop at chat over documents. That is useful, but the work often disappears into transcripts, copied snippets, and half-remembered answers.

kforge treats research as a repo:

• raw/ keeps original evidence and metadata.
• wiki/ stores human-readable compiled articles.
• claims/ stores important sourced assertions.
• reviews/ stages broad or risky edits before they touch durable knowledge.
• outputs/ keeps answer packs, reports, charts, and other generated work.
• indexes/, tasks/, and runs/ make the repo inspectable and agent-friendly.

The result is a knowledge base that humans, Git, Obsidian, local scripts, MCP clients, and LLM agents can all inspect without depending on a hosted model or a vector database.

When To Use It

Use kforge when you want:

• AI research to accumulate as files instead of chat history.
• Important conclusions to stay traceable to local source evidence.
• Agents to draft wiki or claim updates without silently rewriting user data.
• Review queues, task claims, and run logs for parallel agent work.
• Deterministic health checks for links, provenance, drift, conflicts, and review

debt.

• A provider-neutral handoff layer for Codex, Claude Code, Cursor, local models,

or plain shell automation.

Do not use kforge as a replacement for Obsidian, Notion, Dify, AnythingLLM, GraphRAG, LangChain, or LlamaIndex. Those can be interfaces, app platforms, assistants, retrieval systems, or orchestration layers. kforge is the local repo protocol underneath them: raw evidence, compiled wiki pages, sourced claims, review artifacts, generated outputs, and deterministic health checks.

In other words, it is not a RAG framework, not an Obsidian plugin, and not a hosted AI app. It is also not a model wrapper. The core stays provider-neutral and usable without a vector database.

See [docs/comparison.md](docs/comparison.md) for a more detailed boundary map.

Current Status

kforge is an early prototype. Version 0.1.0 focuses on one deterministic local loop:

1. Create or inspect a knowledge repo.
2. Keep source evidence under raw/.
3. Prepare review-backed work for agents.
4. Let agents draft updates into outputs/.
5. Attach, review, and apply structured changes.
6. Run deterministic checks before trusting the repo.

The npm package is not published yet. Until the first public publish, install from a checkout.

Install

Requires Node.js 20 or newer.

From a checkout:

npm install
npm run build
npm link
kforge version

After npm publication:

npm install -g kforge
kforge version

First Loop

Create a demo repo and run the smallest review-backed agent draft loop:

kforge demo ./kforge-demo
cd ./kforge-demo
kforge agent next . --agent local-agent --json
kforge agent step . --agent local-agent --json
kforge agent draft . --agent local-agent --json
kforge doctor .

That claims one task, starts an auditable run, gives the agent a work packet, writes an editable draft into outputs/, and leaves the wiki unchanged until a review is accepted and applied.

For the full copy-paste flow, including attaching the draft to a review and applying it safely, use the [ten-minute agent draft walkthrough](docs/examples.md#ten-minute-agent-draft-walkthrough).

Repo Layout

raw/        original source documents, images, repos, datasets, captures
wiki/       LLM-compiled Markdown articles intended for human reading
claims/     important claims with source references and review state
indexes/    generated maps, inventories, summaries, backlinks, health reports
outputs/    answers, reports, charts, slides, and other generated artifacts
reviews/    proposed edits and unresolved review items
tasks/      claimable work items for parallel agents
runs/       auditable agent execution logs

The diagram is the product contract in one picture: source evidence stays in raw/, agents draft from that evidence, reviews/ gate broad writes, durable knowledge lands in wiki/, claims/, and outputs/, tasks/ and runs/ coordinate parallel agents, and deterministic indexes/ make the repo inspectable again.

Common Workflows

Create a fresh repo:

kforge init ./my-topic

Add local evidence:

kforge source add ./my-topic \
  --file ~/Downloads/article.md \
  --title "Important Article" \
  --url "https://example.com/article"

kforge source import ./my-topic \
  --dir ~/Downloads/research-folder \
  --title-prefix "Project A"

Prepare review-first compile work from queued raw sources:

kforge bootstrap ./my-topic --dry-run --json
kforge bootstrap ./my-topic --agent agent-a --agent agent-b --json

Inspect repo health and context:

kforge dashboard ./my-topic
kforge context ./my-topic
kforge graph ./my-topic
kforge score ./my-topic
kforge ci ./my-topic --json --min-score 80
kforge doctor ./my-topic

Open the local dashboard:

kforge web ./my-topic

The dashboard binds to 127.0.0.1 by default and exposes safe local actions for repo health, review queues, task queues, runs, source ingest, search, answer packs, compile drafts, Trust CI gates, and explicit review application.

Implementation Stance

The core CLI is TypeScript-first, dependency-light, local-first, and provider-neutral. It prepares deterministic handoff artifacts; it does not silently call a hosted LLM.

Python is intentionally not part of the implementation stack. Knowledge repos can still index .py files as source evidence. Rust is reserved for optional future acceleration after a measured performance need appears.

Release checks enforce the public surface with:

npm test
npm run smoke
npm pack --dry-run

See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/release-checklist.md](docs/release-checklist.md) before changing public CLI, MCP, protocol, or package behavior.

Documentation

• [Quickstart](docs/quickstart.md)
• [Five-minute tutorial](docs/tutorial.md)
• [Examples](docs/examples.md)
• [Protocol](docs/protocol.md)
• [Architecture](docs/architecture.md)
• [MCP Server](docs/mcp.md)
• [Agent templates](docs/agent-templates.md)
• [Comparison](docs/comparison.md)
• [Roadmap](docs/roadmap.md)
• [Vision](docs/vision.md)
• [Publishing](docs/publishing.md)
• [Release checklist](docs/release-checklist.md)

Browse [examples/demo-repo](examples/demo-repo) to see a complete tiny kforge knowledge repo with raw evidence, wiki pages, claims, reviews, outputs, and generated indexes.

CLI

The command surface is kept here so release checks can compare it with real CLI help. For narrative examples, start with [docs/quickstart.md](docs/quickstart.md) or [docs/examples.md](docs/examples.md).

Command reference

kforge init [path] [--force] [--example]             create a knowledge repo
kforge demo [path] [--force]                         create a ready-to-browse demo repo
kforge bootstrap [path] [--agent ] [--limit ] [--dry-run] [--json]
                                                       stage compile reviews, tasks, and optional agent runs
kforge ci [path] [--write] [--json] [--min-score ]
                                                       run doctor and freshness/conflict-aware trust score gates
kforge index [path]                                  generate inventory files
kforge refresh [path]                                refresh indexes and derived reports
kforge doctor [path] [--write] [--json]              run health checks
kforge score [path] [--write] [--json] [--min-score ]
                                                       print or write a freshness/conflict-aware trust score report
kforge context [path] [--write]                      print or write an agent context pack
kforge dashboard [path] [--write] [--json]           print or write an Obsidian-friendly status dashboard
kforge obsidian [path] [--write] [--bridge] [--json] print/write an Obsidian entry or command bridge
kforge handoff [path] [--write]                      print or write an agent handoff packet
kforge workflow [path] [--write]                     print or write an agent workflow runbook
kforge graph [path] [--write]                        print or write wiki backlinks and orphan report
kforge web [path] [--host ] [--port ]        run a local web dashboard
kforge agent next [path] --agent  [--limit ] [--no-seed] [--note ] [--json]
                                                       claim next task and start a run
kforge agent step [path] --agent  [--limit ] [--no-seed] [--note ] [--json]
                                                       create one agent work packet
kforge agent draft [path] --agent  [--run ] [--json]
                                                       create a compile draft for current work
kforge agent status [path] --agent  [--json]    show current work for one agent
kforge agent board [path] [--json]                    show active agents, runs, tasks, and coordination gaps
kforge agent reconcile [path] [--write] [--json]      reconcile recoverable agent coordination gaps
kforge agent plan [path] --agent  --agent  [--limit ] [--no-seed] [--note ] [--json]
                                                       assign independent runs to multiple agents
kforge agent launch [path] --agent  --agent  [--command ] [--write] [--exec] [--json]
                                                       generate or run a parallel worker launcher
kforge agent dispatch [path] --agent  --agent  [--command ] [--limit ] [--dry-run] [--write] [--exec] [--json]
                                                       bootstrap work and prepare parallel workers
kforge agent finish [path] --agent  [--run ] [--status ] [--task-done] [--note ] [--json]
                                                       finish the current agent run
kforge agent list                                     list installable agent instruction templates
kforge agent print [--template ]                print an agent instruction template
kforge agent install [path] [--template ] [--force]
                                                       install an agent instruction template
kforge compile [path] --source  --target  [--title ] [--write]
                                                       create a source-to-wiki compile brief
kforge compile plan [path] [--write] [--json]        print or write raw-to-wiki compile queue
kforge compile review [path] [--limit ] [--dry-run] [--json]
                                                       create compile review artifacts from queued raw sources
kforge compile draft [path] [--review |--source  --target ] [--write] [--json]
                                                       create a wiki draft template for a compile review
kforge ask [path] --question  [--query ] [--file ] [--write] [--json]
                                                       create an answer pack for a question
kforge search [path] --query  [--scope ] [--limit ] [--json]
                                                       search text files in the repo
kforge inspect [path] --file              inspect one repo-local file
kforge pack [path] --task  [--query ] [--file ] [--write]
                                                       create an agent task pack
kforge promote [path] --file  --target  [--source ] [--json]
                                                       promote an output into a review artifact
kforge output list [path] [--json]                   list generated outputs
kforge output inspect [path] --file  [--json]
                                                       inspect one generated output
kforge task seed [path] [--limit ] [--json]       seed tasks from review queue
kforge task list [path] [--status ] [--json]
                                                       list parallel agent tasks
kforge task claim [path] [--task ] --agent  [--json]
                                                       claim the next or selected task
kforge task next [path] --agent  [--limit ] [--no-seed] [--json]
                                                       seed if needed and claim next task
kforge task done [path] --task  [--note ] [--json]
                                                       mark a task done
kforge task release [path] --task  [--note ] [--json]
                                                       release a claimed task
kforge run start [path] --task  --agent  [--note ] [--json]
                                                       start an auditable agent run
kforge run next [path] --agent  [--limit ] [--no-seed] [--note ] [--json]
                                                       claim next task and start a run
kforge run list [path] [--status ] [--json]
                                                       list agent runs
kforge run inspect [path] --run  [--json]
                                                       inspect one agent run
kforge run log [path] --run  --message  [--json]
                                                       append to a run log
kforge run finish [path] --run  --status  [--note ] [--json]
                                                       finish a run
kforge source add [path] --file  [--title ] [--url ] [--json]
                                                       copy a local source into raw/
kforge source fetch [path] --url  [--title ] [--json]
                                                       fetch a text or HTML URL into raw/
kforge source fetch-list [path] --file  [--title-prefix ] [--dry-run] [--json]
                                                       fetch a URL list into raw/
kforge source import [path] --dir  [--title-prefix ] [--dry-run] [--json]
                                                       copy a local source directory into raw/
kforge source list [path]                            list raw sources and metadata
kforge source inspect [path] --file        inspect one raw source and its metadata
kforge claim new [path] --title  --source 
                                                       create a sourced claim
kforge claim deprecate [path] --file  [--reason ] [--json]
                                                       mark a claim deprecated with status history
kforge claim audit [path] [--write] [--json] [--status ] [--confidence ] [--warning ]
                                                       audit and filter claim provenance, conflicts, and review debt
kforge claim review-conflicts [path] [--dry-run] [--json]
                                                       create reviews for claim conflict warnings
kforge claim review-drift [path] [--dry-run] [--json]
                                                       create reviews for source drift warnings
kforge review queue [path] [--limit ] [--status ] [--json]
                                                       list prioritized review work
kforge review next [path] [--json]                    show the next actionable review
kforge review new [path] --title  --target  --source  [--content ]
                                                       create a review artifact
kforge review content [path] --file  (--content |--from ) [--json]
                                                       update a review Proposed Content block
kforge review status [path] --file  --status  [--note ] [--json]

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [September999999999](https://github.com/September999999999)
- **Source:** [September999999999/kforge](https://github.com/September999999999/kforge)
- **License:** MIT
- **Homepage:** https://github.com/September999999999/kforge#readme

Install and usage instructions live in the source repository linked above.