kern

kern

A self-learning memory daemon for AI agents. One long-running process per working directory owns a knowledge graph that captures durable facts from your sessions, keeps itself small without gardening, and serves the right context back when you need it.

kern is not a vector store you bolt onto an app. It is a memory substrate: it learns on its own, compacts on its own, and (optionally) federates across machines on its own.

session text → spool → distill (LLM) → typed claims → graph → digest → recall

---

What it does

• Captures automatically. A Claude Code Stop hook extracts the new conversation delta and drops it in <cwd>/.kern/capture/. The daemon drains it, runs one LLM distillation pass that pulls out durable facts, decisions, and preferences as typed claims, and ingests each into the graph. Nothing is lost on an LLM outage — the delta stays queued until it succeeds.

• Recalls into context. The daemon keeps a fresh digest (root anchors + hottest thoughts) at <cwd>/.kern/digest.md. A SessionStart hook injects it into every new session. For deeper mid-session lookups the agent calls the query MCP tool directly.

• Compacts itself. Every access leaves a heat trace; heat decays on each tick. A stigmergy GC evicts cold, stale, non-durable thoughts (Facts are immune) and spills them to an append-only cold store before dropping them — so compaction never destroys data. Similar thoughts cluster into child kerns. The hot graph stays small; the long tail stays cheap.

• Federates (opt-in). Multiple nodes share knowledge over LAN gossip with no coordinator. Each node heartbeats peers and merges entity bodies via a content-addressed CRDT — a thought ingested on node A becomes searchable on node B under the same content-hash id. Off by default.

• One graph per directory. The daemon is per-cwd. Each project gets its own isolated memory; no cross-project contamination, multiple daemons per host.

---

How it works

The graph

kern stores two things:

• Thoughts — factual chunks and LLM-extracted claims. Typed (normal, fact, document) and weighted by confidence + heat.
• Reasons — justified edges between thoughts. The why connecting two facts, not just a similarity score.

Ids are content hashes, so identical content is the same node everywhere — existence is a set union, which is what makes conflict-free merge across nodes work.

Retrieval

A query runs a hybrid pipeline, all hand-rolled, dependencies deliberately minimal:

1. Seed — vector (HNSW) + lexical (BM25) candidate generation.
2. Expand — walk reason edges out from the seeds; optionally HyDE a hypothetical answer to broaden recall.
3. Fuse — reciprocal-rank fusion of the vector and lexical lists.
4. Rerank — a GNN layer scores relationships with learned embeddings; PageRank weights graph centrality.
5. Diversify — drop near-duplicates so the k results actually differ.
6. Answer (optional) — synthesize an LLM answer over the top results.

Cold-store results fill remaining slots (marked cold:true) when the hot graph returns fewer than k.

The daemon

kern --daemon exposes its surface two ways:

• MCP (stdio + HTTP/SSE) for external clients like Claude Code.
• tarpc KernRpc over a per-cwd socket for other local clients.

A background tick (default 60s) drives decay, eviction, and clustering — an idle daemon still maintains itself. Persistence is LMDB (via heed) — an ACID, multi-process embedded KV. Hot graph and cold tier live together in one kern.mdb file per data dir; vectors are stored int8, values are zstd(bincode). The daemon, CLI, and recall hook all open the same data dir concurrently without contention. HNSW, the GNN, beam search, gossip, and the MCP server are all written from scratch.

---

Using it

Quickstart

Prerequisites: Node.js (for the hooks) and a local Ollama with the default models pulled:

ollama pull qwen3-embedding:0.6b  # embeddings (default)
ollama pull qwen2.5:7b        # distillation / reasoning (default)
ollama pull qwen3.5:4b        # /ask oracle answer model (default)

1. Install the binary. A prebuilt binary for your platform (built by CI and published to GitHub Releases):

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/yesitsfebreeze/kern/master/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/yesitsfebreeze/kern/master/install.ps1 | iex

Or build from source (needs a Rust toolchain): cargo build --release → target/release/kern, or cargo install --path ..