Kernl

0.5.0 · · Release on GitHub

Kernl 0.5.0: The Graph Is Built In, and Agents Learn From Each Other

Kernl illustration: the mascot surrounded by holographic data panels

Five days after 0.4.6, Kernl 0.5.0 changes what sits under everything else: the graph that links your people, mail, tasks and what the agents learn is now part of Kernl itself.

The graph is built in

Kernl used to need a Neo4j server for its memory: another container, another password, a gigabyte or two of RAM. The graph now runs inside the kernel, on Relate, an embedded engine that speaks the same Cypher. A fresh install has nothing extra to start, and Neo4j becomes an add-on for those who want Graph Data Science.

An install that already had Neo4j moves on its own. Kernl keeps serving from Neo4j while it copies the graph in the background, checks that the counts match, switches over without a restart and brings over whatever arrived during the copy. Neo4j is left untouched, so going back is one switch in /extensions.

The cinema catalogue no longer lives in the graph: it was a copy of what SQLite already holds and, on a real install, nine nodes out of ten. Without it that install's graph copied in 7 seconds with a 230 MB peak, where the whole thing had taken 53 minutes and 12 GB.

What one agent learns, the others know

Every run, the tools it used and the lessons drawn from it now form a shared experience graph. When an agent starts a task, its prompt carries the lessons other agents learned in the same situation, ranked by how well they fit and how much they have been confirmed — and marked as someone else's experience, not as instructions.

Every change in what an agent knows is recorded and announced, and an office's lessons can be exported as a file and imported by another install, through review and with personal data blanked.

Decisions that are remembered and measured

Each answer you give an agent records who gave it and through which channel. When the same kind of question keeps getting the same answer, the next one arrives with it as a suggestion, and Kernl measures how often that suggestion was right. An office can let a category answer itself once it has been right 97% of at least 30 times — only where an extension says it is safe, and one question in ten still comes to you.

When several agents are blocked by the same outside cause, such as a server that is down, it is recorded once as an environment fact: they wait on it instead of asking again, and closing it wakes them all.

Facts with two timelines, and a time machine

Kernl now keeps facts with when they were true and when it believed them. A new value ends the old one or corrects it, and nothing is deleted, so Kernl can answer what it knew on any date and why an agent acted the way it did. The time machine shows it: pick a person, company or agent and a moment, and see what Kernl knew then, who wrote each fact, and which runs acted on one that was already stale.

One question over every memory

kernel_brain_ask searches the brain, chat history, the agents' lessons and the graph's people, tasks, notes, mail and events in one go, by meaning and by words. People are one person across every source: a contact keeps every address and handle it is known by, duplicates are found and merged with a snapshot, and a 360 view gathers everything about someone. And every write records who made it, so "who changed this?" has an answer.

See the graph at work

A 3D graph explorer lets you walk the graph from any label. The engine room shows it working: the latest statements with the engine's own timing, the schema as a blueprint and the path between two names. The offices show what they learned: each lesson's impact, a library by week and a constellation that places lessons by meaning, where a recalled lesson flares and sends a beam to the desk that used it.

Agents can read the graph too, with checked read-only queries and questions in plain words, and run PageRank, communities and betweenness on any engine. Repos get a code graph (hotspots, owners, change impact), and events and trips get places.

Before you upgrade

  • On Docker, update with scripts/kernl.sh update and leave Neo4j running until the log says the graph upgrade caught up with what reached Neo4j during the copy. To stay on Neo4j, set KERNL_KEEP_NEO4J=1.
  • Back up data/graph by hand for now: backup.sh does not include it yet. The deployment guide shows how.
  • Migrations run on start; nothing else to do by hand.

The full list is in the changelog.

Changelog

Upgrading from 0.4.6

  • The graph is built in now, and your install moves to it on its own. On the first start of this version Kernl switches to Relate, the embedded graph, once. Nothing to do by hand:
    • No graph before (the desktop app): Relate is switched on and filled from your SQLite data in the first minute. If a Neo4j with data in it answers (older stacks wrote chat memory there even with the graph switched off), it is copied instead.
    • Neo4j before (every Docker install): Kernl starts on Neo4j as before and copies the graph into Relate in the background (chat memory, contact links, news, the agents' lessons and decisions), all of it but the cinema catalogue, which no longer lives in the graph (see below). When the copy is done and the counts check out it switches to Relate without a restart, then brings over what reached Neo4j during the copy. Neo4j is left exactly as it was; activating it again in /extensions is the way back. The copy takes about 1 ms per node or relationship on an M-series Mac, and Kernl keeps working all along. On a real install the cinema catalogue was 0.93M of 0.95M nodes; without it the rest (13k nodes, 7.5k relationships) copied in 7 seconds. A restart during the copy starts it over.
    • Neo4j not running at that moment: Kernl starts on Relate anyway, filled from SQLite, and brings over what lives only in Neo4j (chat memory, contact links, news) as soon as Neo4j answers. It checks on every start and every 30 minutes.
    • If the copy fails, Kernl stays on Neo4j with all its data and tries again on the next start.
    • Large graphs: Relate keeps the graph in memory, with no cap unless one is chosen. Before copying, Kernl estimates how much your graph will take and copies it under 1.5× that, up to what the machine can hold (the container's memory limit, or 80% of RAM), then keeps that cap as Relate's memory limit. A graph larger than the machine can hold stays on Neo4j, and the copy is only tried again once there is more memory (or a larger RELATE_LOGICAL_GRAPH_SIZE_LIMIT), not on every start.
    • Memory and start time: Relate holds the whole graph in RAM. The install above, without the catalogue, takes 2.7 MB on disk, peaked at 230 MB while copying and opens in a fraction of a second; with the catalogue it was 3.3 GB, 12.2 GB and two minutes. A large graph of your own still needs that kind of headroom.
    • What happened is recorded in the kernl_upgrades table and the log (Graph upgrade: …).
    • To stay on Neo4j (you use Graph Data Science, say), set KERNL_KEEP_NEO4J=1. KERNL_GRAPH_UPGRADE=off skips the step entirely.
  • Docker: update with scripts/kernl.sh update — it pulls, builds while the old kernel keeps serving, and recreates the kernel and the dashboard with the offices drained first, as restart does. While the neo4j-data volume exists it keeps the Neo4j service up, so the copy can read it. Once the log says the upgrade is done you can stop it with scripts/kernl.sh stop neo4j; your data stays in the volume.
  • The graph's schema upgrades on start: fact times become native datetimes, embeddings become VECTOR<FLOAT32>, lessons get the time they were learned, and the provenance links are rebuilt from the audit table. Nothing to do by hand.
  • Migration agents 64 runs on start: questions remember what they are about and who answered them, through which channel.
  • Bundled extensions that changed carry a new version (Cinema 1.38.0, and Agent Advanced, CRM, Google Sync, Goals, Notes, Reminders, Repos, Shopping and Tasks one patch up), so an install whose copy lives in the extensions folder takes the new code instead of keeping 0.4.6's.
  • The cinema catalogue leaves the graph. It was a projection of SQLite (works, Wikidata identities, directors, genres, subjects, collections) that nothing read any more once its vectors moved to SQLite, and on a real install it was ~90% of the graph. The copy from Neo4j leaves it behind, and a built-in graph that already holds it gives it back once on start (the CRM's people stay: only directors without a CRM id go). Browsing, search, similar titles and "for you" work as before. Recovering yearless uploads by their aliases now runs on a SQLite full-text index (migration cinema 22 builds it from the aliases already pulled), and its proposals still go to review. The cinema share of the graph is gone from System › Storage; titles a limit there left out stay out of semantic search.

Added

  • Agents learn from each other. Runs, the tools they used and the lessons drawn from them are projected into a shared experience graph, and an agent's prompt carries other agents' lessons that fit its goal, ranked by relevance, confidence, shared tools and shared office, and marked as untrusted data. Every change in what an agent knows is recorded and announced.
  • Office packs. An office's lessons export as a JSON or Markdown file with emails, phones, tokens and home paths blanked; importing one stages its lessons for review (kernel_office_pack_review), with confidence capped at 0.6.
  • Facts with two timelines. kernel_facts_assert, _retract and _query keep when each fact was true and when Kernl believed it; a new value ends or corrects the old one and nothing is deleted. kernel_facts_explain answers why Kernl acted and what it knew then.
  • kernel_brain_ask: one question over brain items, chat, memories, the agents' lessons and the graph's people, tasks, notes, mail and events, by meaning and by words, fused into one ranked list.
  • One person across every source. Contacts keep every email, phone and handle they are known by; kernel_crm_duplicates, kernel_crm_merge (with a snapshot) and kernel_crm_not_duplicate, and kernel_crm_person_360.
  • Provenance. Every write through a tool records who made it, whether it worked and the ids it touched (kept 180 days); kernel_audit_who_changed and kernel_audit_changes.
  • Agents read the graph. kernel_graph_schema, kernel_graph_query (one read-only statement, checked three ways) and kernel_graph_ask (a question in plain words); kernel_graph_scratch and kernel_graph_slice give a run a private graph to write in. Outside MCP clients never see GRAPH_PRIVATE_LABELS (mail, chat memory and facts by default).
  • Graph analytics on any engine. kernel_graph_analyze: PageRank, communities, components and betweenness, with GDS when the graph has it, a remote GDS when GDS_REMOTE_URI is set, and plain TypeScript otherwise.
  • A graph explorer at /graph: the graph in 3D, by label or search, with neighbours pulled in one or two hops out.
  • Code graph for repos. kernel_repos_code_hotspots, kernel_repos_code_owners and kernel_repos_change_impact, from git history.
  • Places. Where events, trips and hotels are, and what is near (kernel_places_near); geocoding only with PLACES_GEOCODER=nominatim.
  • A time machine over what Kernl knew. Pick a person, company or agent and a moment: Kernl rebuilds what it knew then, who wrote each fact, which ones were replaced later, and the agent runs that acted on a fact while it was already stale. In the 3D office the graph rises as a hologram over its office.
  • The engine room. The graph at work: the latest statements with the engine's own timing, the schema as a blueprint, index use, and the path between two names. A room of its own in the 3D office.
  • What the offices learned. Each lesson's impact (the runs that recalled it, what changed, how its confidence moved), a library of every lesson by week with its lineage across agents, and a constellation that places lessons by meaning; a recalled lesson flares and sends a beam to the desk that got it.
  • Agents' decisions are remembered and measured. Every answer to an agent's question records who gave it and through which channel (dashboard, WhatsApp, Telegram, API, the Chief). When the same kind of question keeps getting the same answer, the next one shows it as a suggestion, and how often that suggestion was right is measured. An office can let a category be answered on its own once it has been right at least 97% of 30 times, and only where an extension says the case is safe; one question in ten still goes to a person, to keep measuring.
  • Environment facts. When agents are blocked by the same outside cause (a server down, a missing credential), it is recorded once; they wait on it instead of asking again, and closing it wakes them all.
  • Decisions in the graph. Questions, the work they are about, who decided and what was going on at the time become nodes, so an agent can ask what was decided last time about the same pull request and what changed since.

Fixed

  • The Docker image builds on ARM. whisper.cpp's CPU variants include one bookworm's compiler does not know on arm64, so the kernel image failed to build on Graviton, a Raspberry Pi or Docker on an Apple Silicon Mac.
  • LIMIT $n on Neo4j. The JavaScript driver sends every number as a float, which Neo4j refuses after LIMIT and SKIP ("'5000.0' is not a valid value"): the cinema graph's orphan cleanup, the graph explorer, chat memory and the lesson constellation failed on Neo4j. The parameters a statement pages with are now sent as integers.
  • AGENTS_SCHEDULER=off left the inbox sweep running, which woke agents for letters already waiting. It is off with the scheduler now.
  • Chat with Claude Code moves to the next connected account when one hits its usage limit, and to the rest of the model chain when every account is out, instead of ending the turn on a 429.
  • Relate's memory limit is applied. Under Bun the cap never reached the engine; a limit chosen in /extensions (or the one the upgrade sizes) is now enforced, and no limit is applied unless one is chosen.