KAIROS Doesn't Do Vibes: A Local Knowledge Tool With Receipts for Every Claim

Let me confess something: I don't trust a nearest neighbor with my own notes.

That's the entire reason KAIROS exists. Every "AI knowledge base" tool I'd tried asked me to trust a vector index and hope the embedding happened to land near the right memory. That's not retrieval, that's a hunch wearing a UI. I wanted a workspace that could hand me the exact artifact, the exact locator, and the exact rule that put it there — no embedding ever gets a vote. So I built one. Local-first, terminal-native, zero embeddings, and it doesn't phone home, because there's no home to phone.

What it actually does

KAIROS ingests documents, repositories, configuration, logs, and notes, and parses each one by its actual structure — headings in markdown, AST nodes in Python, JSON paths, Kconfig symbols, log lines by session — instead of blindly chunking by byte count. Then it links what it finds with explicit, typed, re-derivable relations: heading_contains, imports, depends_on, and more. No similarity guessing. A bare word in one file can reach a sibling document through a shared heading, two hops later, and the path it took to get there is always inspectable.

Provenance over vibes is the whole design. Every result KAIROS hands back carries its artifact ID, its workspace-relative path, its exact locator, its parser version, and its provenance layer — raw, extracted, derived, or user. Nothing in this system gets to masquerade as source truth. And it's read-only toward your sources: bytes go into a content-addressed, write-once store, and the original file never gets reopened for writing. The only writes to your data are additive — notes, and well membership.

How it's actually built, not how it's pitched

• Storage: SQLite as the canonical store, nine tables, plus an FTS5 virtual table with sync triggers. No separate search service. No vector database.
• Migrations: one Alembic migration, run programmatically by kairos init.
• Layering: domain/ (pure Python, zero framework imports) → infrastructure/ → services/ → cli/ + tui/, two independent surfaces over the same service layer.
• Quality gate: Python 3.12+, Pydantic v2 at every boundary, Ruff format and lint, Pyright in strict mode, a pytest suite covering every parser path plus CLI integration plus headless TUI Pilot tests.

Every command — init, ingest, artifacts, search, show, trace, config, logs, note, well, doctor, tui, demo — fails loudly with a non-zero exit code and an actionable message. Never a bare traceback. Never a silent no-op. That's not a nice-to-have; it's the same discipline that makes the provenance model trustworthy in the first place. A tool that lies quietly about its own failures has no business telling you where a claim came from.

Try it in thirty seconds

git clone https://github.com/Jacobcdsmith/kairos.git
cd kairos
python -m venv .venv && source .venv/bin/activate
pip install -e ".[all]"

kairos init ./my-workspace
cd my-workspace
kairos ingest README.md
kairos search provenance
kairos show <artifact-id>
kairos trace "concept" --depth 2

Or skip all of that and run kairos demo — it stands up a temp workspace, ingests every parser fixture type (Markdown, JSON, Kconfig, logs, Python AST, PDF), runs search, show, trace, wells, and doctor, then cleans up after itself. No bash required. Works on Windows natively.

If you want the full-screen version, kairos tui gives you three panes — Explorer, Workspace, Evidence — over the identical service layer the CLI uses. Same substrate, different surface.

What it deliberately refuses to be

This is the part I actually want you to read, because it's a statement of restraint and I don't see enough of those in this space. v0.1 explicitly does not do: hardware or embedded systems, remote node management or cloud services, multi-agent orchestration or autonomous background execution or self-modification, model inference or LLM integration or embeddings or vector similarity.

That last one is not an oversight. It's the thesis. A system that traces meaning through explicit structure doesn't need to guess what a vector thinks is close enough.

Source is on GitHub: Jacobcdsmith/kairos.

---

Stop asking your tools to trust a hunch. Start asking them to show their work. Parse by structure, not by vibes. Link by explicit relation, not by proximity in some embedding space you can't audit. Make every result carry its own receipt. KAIROS doesn't do vibes — and neither should the tool you build next.