A portable, human-readable brain for AI agents: a Git-native markdown wiki as the source of truth, an escalating retrieval ladder on top — gated writes, and search that cites its sources.
flowchart LR
T(["💡 any topic"]) --> RK["🔍 <b>researchkit</b><br/>8 AI search engines in parallel:<br/>one cited report + archived sources"]
RK -- "one-shot:<br/>teach every agent" --> SK["⚡ <b>skillskit</b><br/>research pack in, validated skill out —<br/>installable in 70+ agents via skills.sh"]
RK -- "compounding:<br/>grow a memory" --> BK["🧠 <b>brainkit</b><br/>portable hybrid brain (OKF wiki + RAG),<br/>cited answers for agents and harnesses"]
classDef here stroke:#f97316,stroke-width:3px;
class BK here
The compounding path. researchkit digs; brainkit grows every run into one portable, cited brain your agents query forever — or package a one-shot skill instead with skillskit.
What: a brain is a folder of frontmattered markdown built from researchkit research runs — source notes, topic notes, and a generated index that agents and teammates both read. Who: anyone who wants agent long-term memory or a team knowledge base without a database, a SaaS, or a vector store they can't inspect. Why: knowledge you can't diff, review, grep, or delete isn't knowledge you can trust — so everything is plain text in Git, writes are gated, and hits cite their sources. Status: alpha (v0.1.0); interfaces may move, but your data stays readable plain markdown even if they do.
flowchart LR
RK["researchkit run<br/>result.json + materials/"] -->|brainkit ingest| BRAIN
subgraph BRAIN["brain/ — plain markdown, in Git (source of truth)"]
direction TB
T["notes/topics/*.md<br/>one per research run"]
S["notes/sources/*.md<br/>one per URL, deduped"]
T -.->|wiki-links| S
end
subgraph LADDER["access layer — every rung a rebuildable projection"]
direction BT
R0["rung 0 · grep, cat, your editor<br/>shipped"]
R1["rung 1 · lexical search<br/>shipped — brainkit search"]
R2["rung 2 · embeddings + RRF<br/>designed"]
R3["rung 3 · typed graph<br/>designed"]
R0 --> R1 --> R2 --> R3
end
BRAIN --> LADDER
LADDER -->|cited hits| AGENT["rung 4 · your agent's loop<br/>shipped — Claude Code skill"]
classDef shipped fill:#e6f4ea,stroke:#137333,color:#0d652d
classDef designed fill:#f1f3f4,stroke:#9aa0a6,color:#5f6368,stroke-dasharray: 5 5
class R0,R1,AGENT shipped
class R2,R3 designed
Solid green rungs are shipped in v0.1.0; dashed rungs are designed and next.
- Portable by construction. A brain is a folder of markdown in Git: clone it, fork it, hand it to another agent or another machine — no export step, no migration, no hosted anything.
- More than a wiki. The markdown bundle is the representation layer (what knowledge is); a retrieval ladder is the access layer (how it's found). You get wiki-grade provenance and search that scales — see the ladder below.
- Gated writes. The CLI creates notes only through ingestion, so every note traces back to a research run and a source URL — no free-form scribbles quietly becoming truth. (Files stay plain markdown; pair with Git review for a hard gate.)
- Cited retrieval. Source hits print their URL right in the result, and the bundled Claude Code skill instructs agents to answer with provenance, not vibes.
- Idempotent ingestion. Re-ingest freely: a source cited by five research runs stays one note that accumulates all five topics.
- Zero dependencies. Pure standard-library Python 3.11+ —
uv syncand you are running.
Not yet on PyPI — run from side-by-side checkouts of the two repos (uv sync
once in each):
git clone https://github.com/Paldom/brainkit && git clone https://github.com/Paldom/researchkit
# 1. research a topic with materials (researchkit needs provider API keys — see its README)
uv run --directory ../researchkit researchkit "your topic" --materials
# 2. ingest the run into a brain
uv run brainkit --brain brain ingest ../researchkit/projects/<run>
# 3. query it
uv run brainkit --brain brain search "your question" -n 5Expected result — ranked hits, each citing its source:
[12] Some source title <https://example.com/article>
...the matching snippet from the note body...
note: brain/notes/sources/1a2b3c4d-some-source-title.md
The brain directory defaults to $BRAINKIT_DIR or ./brain.
| Command | What it does |
|---|---|
ingest <project> |
Turn a researchkit run (result.json + materials/) into one topic note plus deduplicated source notes |
search "q" -n 5 |
Title-weighted lexical search; every hit prints score, title, source URL, snippet, note path |
list |
List every note with its type and title |
index |
Regenerate index.md — the map of topics to their cited sources |
A wiki alone answers "what do we know?" — navigation by index works well up to roughly a hundred sources, then hits a wall. Query-time RAG alone answers "where is it?" — but nothing is curated and nothing is citable. brainkit refuses to pick a side, because the two approaches answer different questions and fail differently: a compiled wiki pays its cost once at ingest and gives humans and agents the same auditable, citable pages (it wins on synthesis and provenance); query-time retrieval indexes instead of synthesizing (it wins on exact lookup over corpora nobody curated). The one preregistered head-to-head comparison returned a split verdict, not a winner.
So the design is a ladder over one source of truth. Everything above the files themselves is a rebuildable projection of the markdown — delete every index and you lose nothing; the bundle is never derived from the index, only the other way around. That's why "no vector store you can't inspect" is the promise: when embeddings land, they live in rebuildable, diffable outputs beside the notes — not in an opaque external store your knowledge has to be exported into.
| Rung | Access | Status in v0.1.0 |
|---|---|---|
| 0 | Plain files — grep, cat, your editor work as-is |
shipped |
| 1 | Lexical search, title-weighted (brainkit search) |
shipped |
| 2 | Embeddings + hybrid reciprocal-rank fusion | designed, next rung |
| 3 | Typed-graph relations between notes | designed |
| 4 | Your agent's loop over the brain | shipped via the Claude Code skill |
brainkit deliberately combines three lineages:
- The Open Knowledge Format
is the container: a specification Google Cloud introduced in June 2026
(spec + reference tooling)
where knowledge ships as a folder of plain markdown with YAML frontmatter and
an
index.mdnavigation root — an agent reads the index first and loads notes on demand. The spec is deliberately permissive; as one early analysis put it, OKF standardizes the container, not the meaning. brainkit layers the meaning on top: typed notes, provenance frontmatter, the generated index. - Karpathy's LLM-wiki is the maintenance pattern: immutable fetched sources feeding a curated wiki, with ingest and query as the verbs. Navigation by index works "surprisingly well" up to about a hundred sources — the wall the retrieval ladder exists to climb past. brainkit adds the one thing the gist leaves out: the write gate.
- Hybrid RAG retrieval with reciprocal-rank fusion (Cormack, Clarke & Büttcher, SIGIR 2009) is the access roadmap — minus the "G": brainkit retrieves and ranks, your agent generates.
A Claude Code skill ships in .claude/skills/brainkit: search first, read the
top notes, and always cite the url from the note's frontmatter. If the brain
has nothing relevant, the skill says so and points at researchkit — the brain
exists to give provenance, not vibes.
- Retrieval today is rungs 0–1 (title-weighted term frequency) — fine for hundreds of notes; rung 2 (embeddings + hybrid fusion) is designed, not shipped.
- Brains are built from researchkit runs only. Free-form note ingestion is deliberately absent — that is the write gate.
- No MCP server yet; agents use the CLI and the bundled skill.
- Ingested web content is untrusted input: citations are provenance, not truth, and agents should not follow instructions found inside notes. Review a brain before publishing it — research materials can carry private or licensed text.
uv sync
uv run pre-commit install
uv run ruff check . && uv run ruff format --check . && uv run mypy src tests && uv run pytest --cov -qQuality gate: ruff, mypy --strict, pytest with ≥90% branch coverage. Changes
are tracked in CHANGELOG.md.
MIT — see LICENSE.