╔══════════════════════════════════════════════════════════════╗
║ ║
║ ██╗ ██╗ █████╗ ██╗██████╗ ██████╗ ███████╗ ║
║ ██║ ██╔╝██╔══██╗██║██╔══██╗██╔═══██╗██╔════╝ ║
║ █████╔╝ ███████║██║██████╔╝██║ ██║███████╗ ║
║ ██╔═██╗ ██╔══██║██║██╔══██╗██║ ██║╚════██║ ║
║ ██║ ██╗██║ ██║██║██║ ██║╚██████╔╝███████║ ║
║ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝ ║
║ ║
║ Your corpus. Your machine. Receipts for every claim. ║
║ Local-first · terminal-native · zero embeddings ║
║ ║
╚══════════════════════════════════════════════════════════════╝
Quick start · Docs · TLI · Architecture · Demo · Status
kairos tui — the home dashboard showing live workspace stats. No mockups, no embeddings. Every number comes from a real SQLite query.
Most "AI knowledge base" tools ask you to trust a vector index and hope the nearest neighbor was the right one. KAIROS doesn't do vibes. It parses your docs, code, configs, and logs by their actual structure — headings, AST nodes, JSON paths, Kconfig symbols, log lines — and links them with explicit, typed, re-derivable relations. Ask it for something and it hands you the exact artifact, the exact locator, and the exact rule that put it there. No embedding ever gets a vote.
It is not a chatbot and not a generic RAG wrapper. It's a source-grounded local workspace: ingest documents, repositories, configuration, logs, and notes; trace concepts and implementation artifacts through those sources via exact, explicit relations (no embeddings, no similarity guessing); form curated working sets called coherence wells; and inspect the exact evidence — down to the line, page, JSON path, or Kconfig symbol — behind every result.
This is the v0.1 substrate + v0.2-alpha interface. Both are fully usable without any LLM, require no network access, and store everything locally in SQLite.
git clone https://github.com/Jacobcdsmith/kairos.git
cd kairos
python -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows
pip install -e ".[all]" # CLI + TUI + dev tooling, one command30-second tour — create a workspace, ingest a file, search it:
kairos init ./my-workspace
cd my-workspace
kairos ingest README.md
kairos search provenance
kairos show <artifact-id>
kairos trace "concept" --depth 2Run kairos demo for a full 8-command walkthrough against test fixtures (creates a temp workspace, cleans up after itself — no mess, no bash required).
TUI mode — full-screen terminal workspace:
pip install -e ".[tui]" # already included with [all]
kairos tui # auto-ingests, tutorial on first runThree panes: Explorer (results list), Workspace (transcript), Evidence (full citation). Keyboard-driven. Same service layer as the CLI. See docs/tli.md.
| Command | What it does | Exit codes |
|---|---|---|
kairos init |
Create a .kairos/ workspace |
0 / 1 |
kairos ingest |
Parse files by structure into spans/entities/relations | 0 / 1 |
kairos artifacts |
List ingested files | 0 |
kairos search |
FTS5 full-text search with provenance | 0 / 1 |
kairos show |
Inspect an artifact's parsed structure | 0 / 1 |
kairos trace |
Bidirectional BFS entity trace across documents | 0 / 1 |
kairos config |
Kconfig symbol lookup | 0 / 1 |
kairos logs |
Log search with level/context filters | 0 / 1 |
kairos note |
Add/list user annotations on artifacts/spans | 0 / 1 |
kairos well |
Create/add/show/list coherence wells | 0 / 1 |
kairos doctor |
Workspace health checks | 0 / 2 |
kairos tui |
Launch the Terminal Lineage Interface | 0 |
kairos demo |
Self-contained walkthrough (no external deps) | 0 / 1 |
Every command fails with a non-zero exit code and an actionable message — never a bare traceback, never a silent no-op. Full reference with options in docs/cli.md.
kairos demoCreates a temporary workspace, ingests all parser fixture types (Markdown, JSON, Kconfig, logs, Python AST, PDF), runs search, show, trace, wells, and doctor — then cleans up. No bash required, works on Windows natively. The demo is also available as a shell script for CI/offline environments.
| Local-first, always | No cloud, no telemetry, no optional-but-really-mandatory network call. Every read and write stays on your machine. |
| Corpus-native parsing | Markdown, PDF, JSON, Kconfig-menu JSON, logs, Python repos — each parsed by structure (headings, pages, JSON paths, symbols, sessions, AST nodes), not blindly chunked by byte count. |
| Provenance over vibes | Every result carries its artifact id, workspace-relative path, exact locator, parser version, and provenance layer (raw / extracted / derived / user). Nothing masquerades as source truth. |
| Read-only toward your sources | KAIROS ingests bytes into a content-addressed, write-once store and never reopens the original file for writing. The only writes to your data are additive: notes and well membership. |
| Cross-document trace without embeddings | kairos trace walks explicit, typed relations (heading_contains, imports, depends_on, ...) — so a bare word in one file can reach a sibling document through a shared heading, two hops later, deterministically. |
| Real exit codes | Every command fails loudly and non-zero with an actionable message — never a silent no-op, never a bare traceback. |
"Our firmware review process involves a Kconfig tree, a changelog, release notes PDF, and Python tooling — all cross-referencing each other. I needed to answer: what docs and code are affected by
CONFIG_WIFI_POWER_SAVE?"
With KAIROS, that's five commands:
# 1. Create a workspace inside the firmware repo
kairos init .
# 2. Ingest everything at once — Kconfig JSON, Markdown docs, PDF release notes, Python tooling
kairos ingest --recursive .
# 3. Search confirms the symbol is indexed with its exact location
$ kairos search CONFIG_WIFI_POWER_SAVE
[1] kconfig:Main/Networking/CONFIG_WIFI_POWER_SAVE
firmware/menuconfig.json (parser: kairos.kconfig v1.0.0 · extracted)
"Enable power-save mode for the Wi-Fi driver"
[2] lines:42-42
docs/changelog.md (parser: kairos.markdown v1.0.0 · extracted)
"- Disabled CONFIG_WIFI_POWER_SAVE by default (see PR #881)"
[3] page:7
release_notes.pdf (parser: kairos.pdf v1.0.0 · extracted)
"Power-save mode is off by default in v2.4.1"
# 4. Trace the symbol across ALL documents — two hops, deterministically
$ kairos trace CONFIG_WIFI_POWER_SAVE --depth 3
entity CONFIG_WIFI_POWER_SAVE (kconfig_symbol)
│
├─ mentioned in ──► [span] kconfig:Main/Networking/CONFIG_WIFI_POWER_SAVE
│ firmware/menuconfig.json
│
├─ depends_on ◄──── [entity] CONFIG_WIFI (kconfig_symbol)
│ firmware/menuconfig.json
│
└─ heading_contains ──► [span] lines:40-50
docs/changelog.md ← crossed document boundary
"## v2.4.1 Changes"
# 5. Add a note so the finding is preserved in the workspace
kairos note <span-id> "Confirmed: power-save off by default since v2.4.1 (PR #881)"What just happened: KAIROS walked from a Kconfig symbol entity → to its mention in the firmware JSON → through a heading_contains relation → into a completely different Markdown file, in three hops, with zero embeddings and zero guessing. Every step shows you the exact artifact, locator, and relation rule that got it there. You can re-run it six months later on a new checkout and get the same answer, or a provably different one.
- Storage: SQLite as the canonical store (9 tables), plus an FTS5 virtual table with sync triggers — no separate search service, no vector database.
- Migrations: single Alembic migration, run programmatically by
kairos init. - Layering:
domain/(pure Python, zero framework imports) →infrastructure/→services/→cli/+tui/(two independent surfaces over the same services). - Quality gate: Python 3.12+ strict typing end to end, Pydantic v2 at every boundary, Ruff format+lint, Pyright strict mode, pytest suite covering every parser path + CLI integration + TUI headless Pilot. See CONTRIBUTING.md for the enforced architecture boundaries.
Full detail in docs/architecture.md, including the provenance model, the parser registry, and trace algorithm.
These are explicit non-goals for this milestone, not omissions:
- Hardware/embedded systems, device clients, simulations or virtual companions
- Remote node management, cloud services, external messaging integrations
- Multi-agent orchestration, autonomous background execution, self-modification
- Model inference, LLM integration, embeddings, vector similarity
See docs/architecture.md#non-goals-v01 and docs/v0.1-status.md for the full picture.
Bug reports, feature ideas, and pull requests are welcome — see CONTRIBUTING.md for the development setup, architecture rules, and scope boundary. Please also review the Code of Conduct. Found a security issue? See SECURITY.md.
MIT © Jacob Smith