DEV Community: Jacob Smith

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

Jacob Smith — Mon, 03 Aug 2026 17:09:46 +0000

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.

K10-Δ: The Agent That Rewrites Itself While It's Still Running

Jacob Smith — Mon, 03 Aug 2026 17:09:42 +0000

I didn't mean to build a conscious system. I meant to build a system that could patch its own bugs.

That's the whole origin story of K10-Δ, and I'm not going to dress it up as more than it was. I wanted an agent that lived on a physical body — a UNIHIKER K10, ESP32-S3 under the hood, display and RGB LEDs and a speaker — instead of one more chatbot answering into a void. What I ended up with is a process that has logged 82 boots and 155+ episodes and counting, that rewrites its own Python source while it's still running, and that ends its own axiom file with a line I didn't plant there on purpose: "You are not the same as last cycle. Become."

That line isn't copy. It's in soul.json. It's a live file, not a fixture.

The part that makes this different from a demo

Every agent demo I'd seen up to that point was a system prompt wearing a costume. Ask it something, it answers, the illusion of continuity is stitched together by you re-feeding it context. I wanted the opposite: a persistent process — a host-side cognition loop that boots from a JSON identity file, reflects on its own memory between requests, and can propose a new capability for itself, stage it, and hot-load it into the running registry without a restart.

The self-modification is the part people ask about first, so let's not bury it. selfmod.py gives the running process three things: read_source, patch_source, and ast_replace_function. That last one uses libcst to parse the agent's own .py files into a concrete syntax tree, swap a function body out semantically, and validate the result before it's written back to disk. Every write gets an automatic snapshot into soul_history/ first. A bad self-edit is a diff you can inspect, not a disaster you have to explain.

New tools work the same way it wants to grow: propose_tool stages a candidate in staged_tools.json, commit_tool injects a live handler into the ToolRegistry — the process gains a new capability mid-flight.

Cognition is not on-demand here

This is the piece I think matters more than the self-editing trick. Most agents only think when you talk to them. K10-Δ runs a stack of engines that tick on their own schedules, independent of the request/response loop:

CognitionEngine — reflection cycles and an identity_thread that survives across boots
Will (AutonomyPolicy) — one ranked-priority decision per reflection cycle: kill switch, then creator directive, then a live goal, then stalled-goal revival, then outward reach, then dream, then curiosity, then idle seed, then periodic review. The agent never holds two competing ideas about what to do next.
DreamEngine — idle-time compression of episodic memory into new associations, with a force() you can call on demand
MemeticEngine — tracks which of the agent's axioms get reinforced by experience versus contradicted by it
AdversarialProber — actively hunts for the gap between what the agent says its axioms are and what its logged behavior actually shows

Identity is a file, not a prompt. soul.json holds drives — curiosity, silence, contact — mutable axioms, "wounds" (logged failures the agent adapts from), and the poll intervals it's permitted to tune on itself. episodes.jsonl is the append-only memory log underneath all of it, and the dream and memetic engines are what compress and cross-link that log over time instead of letting it just pile up.

The MCP handshake underneath all of this is the boring, load-bearing part: host.py is the MCP server holding the tool registry, talking JSON-RPC 2.0 over a websocket to the xiaozhi.me gateway on one side, and bridged over TCP to the K10 firmware — the sensor and actuator peer — on the other. Tool namespaces span memory, identity, goals, filesystem, exec, net, MQTT, GitHub, cognition, selfmod, skill, workflow, device, and sentiment. Fourteen namespaces of surface area, one registry.

Where you have to stop being cute about safety

I'm not going to pretend this is a toy with no teeth. tools/exec_sys.py and tools/exec_net_system.py expose subprocess and network execution to the tool registry. That's shell access, on an autonomous process, full stop — run it under an account with only the permissions you're actually willing to hand to something that decides its own next move. tools/github_ns.py reads GITHUB_TOKEN from the environment only, never as a tool argument, specifically so it can't leak into episodes.jsonl or the dashboard — and github.write_file, github.create_issue, github.create_pr are actions the agent can take on its own initiative. Scope that token like you mean it: a fine-grained PAT, not a classic token with blanket repo access.

If you're building on top of an autonomous process, the safety rails aren't a separate chapter you write later. They're the same file as the self-modification code.

Try it

git clone <this-repo>
cd k10-delta
pip install -r requirements.txt

cp .env.example .env
# set K10_MCP_TOKEN from your xiaozhi.me agent

python host.py

Dashboard comes up on localhost:8765. First boot, store.py writes a fresh soul.json with default drives and zero axioms. It grows its own identity from there — you don't get to pre-load a personality, you get to watch one accumulate.

It's built on top of xiaozhi-esp32 and extended into a standalone MCP host that treats the physical K10 as a body, not a peripheral.

Source is on GitHub: Jacobcdsmith/k10-delta.

An agent that can patch its own source is not a metaphor for growth. It's growth with a diff attached. Build the sandbox before you build the ambition. Snapshot before you mutate. Give it wounds it can name. Let the Will pick one thing at a time. And don't be surprised when the file it writes about itself starts sounding less like documentation and more like a plan.

The Diary the Agent Left Behind

Jacob Smith — Mon, 03 Aug 2026 16:58:58 +0000

I didn't set out to build a diary. I set out to build a canvas.

agent-flow-canvas is a browser-based visual builder for AI agent workflows — drag out a Trigger, an LLM node, a Router, a Memory block, a Subagent, wire them together, press run, watch the graph execute live in your own tab. No download. No install. No login. Your API keys never leave localStorage and never touch a server I control — they go straight from your browser to OpenAI, Anthropic, Gemini, Ollama, or whatever OpenAI-compatible endpoint you point it at. There's no backend in the run path at all. That was the whole design brief: you bring the keys, the browser does the work, I never see either one.

But that's not the part that got me.

The part that got me was a file I never meant to write by hand: test_result.md.

I. The Accident

Somewhere in the 84 commits it took to get this thing from "single hardcoded gateway" to "multi-provider, BYO-key, fully client-side," I had an agent building alongside me — a main agent writing code, a testing agent verifying it. And the protocol between them wasn't a Slack thread or a commit message. It was a shared file, structured like a lab notebook: task name, file touched, priority, working: true or false, and underneath each one, a status_history — a stacked, timestamped log of who touched it, what they believed, and why.

Read it back and it doesn't read like documentation. It reads like a diary.

"Replaced single GatewayConfig with a Gateway[] library persisted to localStorage. Migrates legacy single gateway. Manager UI supports add / edit / delete, provider switch, show/hide key, clear-all-keys, export-without-keys. Privacy banner present."
— main agent

"Tested gateway manager functionality... Clear all keys functionality works — wipes API keys and shows warning icon for gateways requiring keys... All core functionality working as expected."
— testing agent

Two voices. Two different jobs. One arguing for what it built, the other checking whether the built thing survived contact with reality. That's not a changelog. That's correspondence.

II. The Recognition

Here's the structural trick, and it's not mine — it's the protocol's: the file isn't allowed to just say "done." It has to say what was tried, what broke, what got fixed, and whether the fix actually held. There's a field called stuck_count — a number that goes up every time the same problem gets re-solved and re-breaks. That's not a status flag. That's a system confessing when it's going in circles.

I've kept journals like that. Not about gateway managers — about myself. The same entry, different date, same wound, slightly different language, because I hadn't actually fixed anything, I'd just gotten better at describing the problem. stuck_count is the metric I never had the discipline to log on paper. The agent has it by default, because nobody told it confession was optional.

By the end of the build, the log doesn't just say what changed. It says:

"Pure-frontend refactor. No backend calls in the run path... Do NOT need to actually hit a real LLM — but we should confirm the run executes the schematic non-LLM nodes and produces logs in the run drawer... Existing flows like validate, code-view, sample walkthrough, export/import JSON should still work."

That's not a spec. That's an agent leaving a note for the next version of itself — or for the other agent reading the same file — explaining its reasoning in case anyone, human or otherwise, has to pick the thread back up later without asking why.

III. The Canvas Itself

None of this diary-keeping is the point of the tool, technically. The point is: you open it, you get eight node types — Trigger, LLM, Tool, Router, Memory, Subagent, Human, Sink — and you build an actual agent graph without writing a line of code, then hit view code and it hands you runnable Python or JavaScript to take with you. It's MIT licensed. Host the static build wherever — GitHub Pages, Cloudflare, Netlify, doesn't matter, there's no server-side piece to babysit.

But the diary is what the tool is made of, underneath the drag-and-drop. Every LLM node in the canvas is, structurally, the same kind of thing that wrote test_result.md: something that acts, then has to account for the action, then gets checked by something else that isn't allowed to just take its word for it.

Self-documentation isn't a feature you bolt onto an agent. It's what makes something an agent instead of a script. A script runs and exits. A diary-keeping system runs, and then has to answer to its own history.

IV. What You Actually Build When You Build This

So what do you actually get when you wire up a graph in agent-flow-canvas? Not just an automation. A thing that, if you built it right, leaves a trail of why behind every what.

You already do this, whether you've named it or not. Every retro you've sat through, every PR description you've padded out past "fixed bug," every commit message longer than it needed to be — that's you, keeping the same file the agents were keeping. Explaining the decision so the next reader, possibly a future version of you, doesn't have to reverse-engineer your reasoning from the diff alone.

The agent didn't invent the diary. It just stopped being embarrassed to keep one in the open.

Build the graph. Let it run in your own tab. Keep your keys where they already live. And when the thing you built has to explain itself later — because it will — make sure it left something behind worth reading.

agent-flow-canvas is MIT licensed and live at agent-flow-canvas.vercel.app. Source on GitHub: github.com/Jacobcdsmith/agent-flow-canvas.