BrainKit

• 

  Logo

Inspiration

I wanted an LLM wiki (Karpathy's idea, later formalized as Google's Open Knowledge Format) combined with retrieval, in something I could actually carry around: a "brain" I build from my research runs and hand to any agent. No hosted memory service, no vector database I can't open in an editor: a folder of markdown in Git that my agents query and cite.

What it does

brainkit ingests researchkit research packs into a brain: one topic note per run, one deduplicated source note per URL, report sections chunked into queryable notes. Writes are provenance-gated — nothing enters without a source URL, project, or title, so no anonymous text quietly becomes truth.

Retrieval is a ladder, every rung a rebuildable projection over the markdown: grep works (rung 0), brainkit search does title-weighted lexical search with a deterministic freshness tie-break; newest content date wins, undated notes never borrow freshness from ingest time (rung 1). Every hit prints its citation URL, published date, and a (social) trust marker on user-generated sources. Notes carry a deterministic corroboration count: how many research runs independently cite that URL: computed, not LLM-judged. brainkit pointer writes a discovery snippet into AGENTS.md so agents actually find the brain.

Re-ingesting is idempotent; a source cited by five runs is one note with five attributions; a log.md journal makes every write diffable in Git.

How we built it

The design was argued out with a review panel of rival models, Codex among them running GPT-5.6 Sol. The panel forced two real fixes before merge: the freshness ranking originally used naive timestamps (rank order would have depended on the host machine's timezone — fatal for a Git-shared brain), and the agent-discovery pointer originally wrote absolute paths into committed files. Both were rewritten to deterministic, machine-independent forms.

Codex is also a consumer: the brain ships an agent skill discoverable by Codex via the Agent Skills standard (.agents/skills/), and the pointer snippet teaches any agent in the repo to query the brain before answering from memory. Research that flows in via researchkit is itself produced with GPT-5.6 as a provider and summarizer.

Challenges we ran into

Deterministic beats clever, repeatedly. Freshness had to work without LLM judgment (published evaluations found deterministic timestamp resolution more reliable than asking a model to track freshness); corroboration had to be a count derived from provenance the brain already tracks, not a model's opinion; and merging the same URL across runs without ever losing provenance took careful union semantics plus pruning that mirrors each run's current citation set.

What we learned

Studying LangChain's OpenWiki launch mid-build was clarifying: LLM-written wiki pages drift into what one Hacker News commenter called "a journal-y mess," and their conflict handling is an open issue. brainkit's bet (deterministic ingestion, URL-keyed identity, provenance gates) avoids that failure class by construction. The markdown stays boring; the intelligence lives in retrieval.

What's next

Rung 2 of the ladder (embeddings + reciprocal rank fusion, still a rebuildable projection), an MCP server so any agent queries the brain as a tool, and cross-run topic synthesis.

Built With

• agent-skills
• codex
• git
• gpt-5.6
• markdown
• mypy
• okf
• pytest
• python
• uv