kairos-agent 0.2.1

Stop guessing. Run the right pattern. A CLI for executable agent knowledge.

kairos

Stop guessing. Run the right pattern.

A CLI for executable agent knowledge.

Install · Demo · What's new in v0.2 · Why kairos · Quickstart · How it works · Commands · Roadmap

---

What's new in v0.2

v0.2.0 closes 45 audit findings we found by auditing our own v0.1.1. Highlights:

• .kairos/config.toml parser - tune backend, stale window, default technique without env vars.
• Plugin runners via entry_points(group="kairos.runners") - pip install kairos-runner-tot lands without a fork.
• Real wiki_index cache - selector + query stop re-walking the filesystem on every call.
• kairos doctor now actually pings llm-mcp instead of hard-coding "ok".
• kairos feedback <run-id> --rating N - capture quality signal for the runs you care about.
• Retries + backoff in MCPLLMClient - 3 attempts with exponential backoff on 5xx + connect errors.
• KAIROS_DB_HOME env var - relocate kairos.db outside the repo.
• kairos run --json + --llm-rerank - structured output and an optional LLM tie-break.

Full migration notes: docs/UPGRADING.md. Zero breaking changes; v0.1.x → v0.2.0 is in-place.

Install

pip install kairos-agent

That's it. Zero API keys. Every model call routes through llm-mcp so you reuse your existing ChatGPT and Claude sessions.

# or, with uv
uv tool install kairos-agent

# Windows
irm https://raw.githubusercontent.com/vinothhacks/kairos/v0.2.0/install.ps1 | iex

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/vinothhacks/kairos/v0.2.0/install.sh | sh

30-second demo

$ kairos init my-wiki && cd my-wiki

$ kairos run "Search the docs for caching and summarize" --dry
   top-3 techniques for: Search the docs for caching...
   ┌──────┬───────────┬───────┬──────────────────────────────────┐
   │ rank │ technique │ score │ rationale                        │
   ├──────┼───────────┼───────┼──────────────────────────────────┤
   │ 1    │ rag       │ 0.70  │ keyword boost 0.50, overlap x4   │
   │ 2    │ react     │ 0.65  │ keyword boost 0.50, overlap x3   │
   │ 3    │ reflexion │ 0.05  │ overlap x1                       │
   └──────┴───────────┴───────┴──────────────────────────────────┘

kairos looks at your task, queries its wiki of agent techniques, and tells you which pattern to run: RAG, ReAct, or Reflexion. Then it actually runs it.

Why kairos

You've read the LLM techniques. CoT, ReAct, Reflexion, ToT, HyDE, rerank — twenty patterns each with a paper, each with a use case, each easy to forget the morning you're three coffees into a real problem.

Most "LLM wikis" turn this into a static reading list. kairos turns it into a runtime decision. The wiki is the agent's playbook:

• Ingest raw sources (papers, transcripts, your own notes) → LLM-curated wiki pages.
• Query the wiki with natural language; answers cite real pages with [[wikilinks]].
• Lint for contradictions, stale claims, and gaps. The wiki gets smarter with every run.
• Run any task — kairos picks the right technique by reading its own wiki, then executes it.

Three patterns ship with working runners (RAG, ReAct, Reflexion). The other 18 are documented and ready to be promoted from doc-only to runnable. You can extend it.

Quickstart

# 1. Bootstrap a project. Copies 21 seed concept pages.
kairos init my-wiki && cd my-wiki

# 2. Ingest a source.
kairos ingest research/karpathy-llm-wiki-gist.md

# 3. Ask a grounded question.
kairos query "When should I use ReAct over RAG?"

# 4. Lint the wiki.
kairos lint

# 5. Run a task — kairos auto-selects the technique.
kairos run "Search the docs for caching, then summarize"

# 6. Or pick the technique manually.
kairos run "Iteratively refine this paragraph" --technique reflexion

Every run logs to .kairos/kairos.db (SQLite). Every page lives in plain markdown. Every wikilink survives git diff.

How it works

flowchart LR
    User([User]) --> CLI["typer CLI<br/>cli.py"]
    CLI --> Cfg["config.load_config()<br/>env > .kairos/config.toml > defaults"]
    Cfg --> RunCmd["cli run/query/lint/ingest"]

    RunCmd -->|technique=auto| Selector["select_technique"]
    Selector --> Idx["wiki_index<br/>(SQLite cache)"]
    Idx -.cache miss.-> FS["wiki/ filesystem walk"]
    Selector -->|optional --llm-rerank| Rerank["claude_send tie-break"]
    Selector --> Rank["TechniqueChoice ranking"]

    Rank --> Disp["runners.dispatch<br/>+ entry_points discovery"]
    Disp --> ABC["Runner ABC"]
    ABC --> RAG["RagRunner"]
    ABC --> ReA["ReactRunner"]
    ABC --> Refl["ReflexionRunner"]
    ABC -.plugins.-> Plug["kairos-runner-*"]

    RAG --> Rec["RunRecorder.finish<br/>selected_by + score"]
    ReA --> Rec
    Refl --> Rec

    Rec --> DB[("kairos.db<br/>WAL + busy_timeout 5s")]
    DB --> Runs["runs"]
    DB --> FB["feedback (KAI-035)"]
    DB --> WI["wiki_index"]
    DB --> WR["wiki_relations"]

    CLI -->|backend=mcp| MCP["MCPLLMClient<br/>retries + backoff"]
    MCP --> LLM["llm-mcp server"]
    CLI --> Doc["kairos doctor<br/>real ping"] --> MCP
    CLI --> FBcmd["kairos feedback"] --> FB

Three layers, mirroring Karpathy's LLM Wiki gist:

1. raw/ - your immutable inputs (papers, articles, transcripts). Source of truth.
2. wiki/ - LLM-generated, human-curated markdown pages. Lives in git.
3. AGENTS.md - the schema. Tells future LLM passes how the structure works.

See docs/architecture.md for the full diagram.

Commands

Command	What it does
kairos init [path]	Bootstrap AGENTS.md, raw/, wiki/, outputs/. Seeds 21 concept pages.
kairos ingest <file>	Read a source, propose new + updated wiki pages, log the diff.
kairos query "<q>"	Lexically retrieve pages, ask the LLM to synthesize, cite wikilinks.
kairos lint	Local: orphans, missing concepts, stale pages. LLM: contradictions, gaps.
kairos run "<task>"	Auto-select technique, dispatch runner, log the run.
kairos run "<task>" --dry	Show the top-3 candidate techniques without running.
kairos doctor	Print env diagnostics.
kairos version	Print version.

What ships in v0.1

	Count	Status
Concept pages (seed wiki)	21	doc-only
Runner-backed techniques	3	RAG, ReAct, Reflexion
Unit tests	48	green
Backends	1	SQLite (Postgres optional)
LLM bridge	1	llm-mcp (no API keys)

The 21 seed concept pages: rag, react, reflexion, chain-of-thought, tree-of-thoughts, self-consistency, self-refine, constitutional-ai, plan-and-execute, few-shot-prompting, zero-shot-prompting, function-calling, tool-use, prompt-injection, embedding-search, hybrid-search, hyde, rerank, router-agent, memory-buffer, llm-wiki.

Compared to

	kairos	LLM-wiki gist	Notion AI	Obsidian + plugins
Plain markdown source	yes	yes	no	yes
Diff-able in git	yes	yes	no	yes
Ingest sources via LLM	yes	yes	partial	with plugins
Lint for contradictions	yes	manual	no	no
Pick technique automatically	yes	no	no	no
Execute the technique	yes	no	no	no
Zero API keys (uses MCP)	yes	no	no	no
CLI-first	yes	no	no	no

The wedge: executable wiki, not passive notes.

Configuration

# Where kairos finds llm-mcp (default: localhost:8765)
export KAIROS_MCP_URL="http://localhost:8765"

# Use a stub LLM client for offline tests
export KAIROS_LLM_BACKEND="stub"

Per-project config lives in .kairos/config.toml. Run kairos doctor to see resolved values.

Roadmap

• v0.1 (now) — 21 seed pages, 3 runners, SQLite logging, MCP bridge.
• v0.2 — --fix for lint, technique outcome scoring (the selector learns from past runs), 5 more runners.
• v0.3 — Composite techniques (Reflexion-over-ReAct, ToT-with-retrieval), Postgres backend, multi-user wikis.
• v1.0 — Plugin runners (pip install kairos-runner-tot), web preview server.

See CHANGELOG.md for what landed in each release.

Contributing

Found a wiki page that's wrong? Want a new technique runner? PRs welcome. Read CONTRIBUTING.md first.

git clone https://github.com/vinothhacks/kairos
cd kairos
uv pip install -e ".[dev]"
uv run pytest

License

MIT © vinothhacks

Acknowledgements

The wiki pattern is straight out of Andrej Karpathy's LLM Wiki gist. The README structure follows jcode for the install-first / demo-first style. The technique catalog stands on the shoulders of every paper cited in the seed pages.