Skip to main content

kea: a second brain that checks its facts

CI Release 1.0.1 PyPI kea-brain Python 3.15 No dependencies MCP server Claude Code plugin Agent skills mypy strict Code style: black MIT licence Last commit Stars

Your AI agent remembers everything you told it, including the things that were never true. kea is a second brain for you and your agents that keeps the difference: every fact carries a source and a date, every decision carries the day you will look at it again, every prediction gets scored against what happened, and every big plan faces a council of rival AI models before you commit. It also makes everything you ever said to Claude Code, Codex, OpenCode, ChatGPT and Claude searchable, on your machine.

Plain Markdown in a folder you own. One Python package with no dependencies. A CLI, an MCP server, three agent skills and a Claude Code plugin.

uv self update      # or brew upgrade uv, or pip install -U uv: an older uv knows only the 3.15 previews
uv tool install --python 3.15 kea-brain   # fetches Python 3.15
kea init ~/tidewater --example && cd ~/tidewater && kea status
kea Tidewater Coffee · ~/tidewater
  state        updated yesterday · 7 facts, 1 past recheck · 1 UNVERIFIED
  decisions    2 active · 1 due for revisit (D-0002)
  predictions  3 open · 1 due to score (P-0007) · 6 scored, Brier 0.23 (+7% vs a coin)
  roadmap      2 waiting for Mara · 3 next · 1 date in 14 days
  ideas        2 parked
  plan         second-cafe: reviewed, 3 reviews → kea synth second-cafe
  council      0 of 6 seats ready · the Chair is your own agent
  evidence     nothing indexed yet: kea ingest claude-code

health
  ✓ STATE.md is fresh · last entry yesterday
  ! facts are sourced and rechecked · 1 of 7 facts past their recheck
  ! decisions are revisited on time · 1 due
  ! predictions are scored · 1 past their date
  ✓ frameworks have boundary conditions · 0 of 1 incomplete
  ✓ decided plans carry 3 predictions · no decided plans yet
  3 of 6 checks need attention. Fix the oldest first.

That is the example brain: Tidewater Coffee, a made up roastery deciding whether to open a second cafe. Every number in it is invented, and every line above is real output.

Why

Second brains are good at collecting and bad at checking. Notes pile up, half of them guesses, and an AI agent that reads them repeats the guesses back with total confidence. Decisions get made and never revisited. Predictions get made and never scored, so nobody learns whether "I'm 80% sure" means anything. And the big calls get validated by one model that was trained to agree with you.

kea began as the private system its author works from: a folder of Markdown, a council of free model endpoints and a SQLite index over past AI conversations. This repository is that system with the private data taken out, made general, tested, and shipped for anyone.

What it does

Facts with receipts. STATE.md holds a facts table (fact, value, source, verified date) and a dated log. Anything not checked is marked UNVERIFIED and says how it would be checked. kea check lints the lot: unsourced facts, facts past their recheck date, stale state.

kea fact "Cash on hand" "EUR 18,400" --source "bank export"
kea log "Five sample bags sent to cafes" --source journal/wholesale-samples.md

Decisions that come back. Every decision carries the reasoning and a revisit date. When the date comes, kea asks what happened, how surprising it was, and what changes.

kea decide "Test wholesale first" --decision "Five sample bags before any lease" --why "roaster at 40%" --revisit +30d
kea revisit D-0003 --outcome "Two cafes ordered" --surprise 3 --lesson "Ask for volume, not a yes"

Predictions that get scored. Write them down with a date and a confidence, score them when the date comes, and find out whether your 80% means 80%:

$ kea calibration
6 scored predictions · Brier 0.233 (0 is perfect, 0.25 is a coin) · +7% skill over a coin
said 78% on average, 58% came true: overconfident

  said       count  came true
  60 to 69%      1  ██████████··········  50%
  70 to 79%      1  ████████████████████ 100%
  80 to 89%      2  ····················   0%
  90 to 100%     2  ████████████████████ 100%

A council of rival models. For the decisions that are expensive to reverse, kea brief builds one packet with the facts, the frameworks the plan names and the plan, and hashes it. kea council sends it to every ready seat in parallel: Gemini, DeepSeek, OpenAI's open weights on Groq, Mistral, and two local models by default, twelve providers preset, any OpenAI compatible server welcome. No seat sees another's review. Your own agent is the Chair: it reviews first from the packet alone and writes the synthesis last, including the section on what every seat missed, because models that share training data share blind spots.

$ kea synth second-cafe
3 of 3 reviews parsed · verdicts: PROCEED_WITH_CHANGES 2, PROCEED 1
4 recommendations: 1 strong, 0 split, 3 solo
wrote plans/second-cafe/10-synthesis-scaffold.md · now the Chair writes 11-synthesis.md: what every seat missed

Search everything you ever told an AI. kea ingest indexes your Claude Code, Codex and OpenCode sessions, your ChatGPT and Claude exports, your git history and your notes into SQLite with FTS5, read only, incrementally, with credential paths refused and secrets redacted. Every hit points back to its exact file and line, message or commit. kea effort shows where your attention actually went, project by project.

kea ingest claude-code && kea ingest codex && kea ingest git ~/code
kea search "why did we drop the market stall" --mine

A roadmap that survives the session. ROADMAP.md keeps what waits for you apart from what comes next, so an agent puts its questions where you will see them instead of guessing. kea roadmap add "..." --waiting.

Use it with your AI agent

kea is built to be used by agents as much as by people. Every command takes --json, kea guide prints the whole manual, and every brain carries an AGENTS.md (and a CLAUDE.md that imports it) with the rules and the session routine.

Skills for Claude Code, Codex, OpenCode and any agent that reads ~/.agents/skills:

kea skill install        # into ~/.claude/skills (Claude Code, OpenCode) and ~/.agents/skills (Codex and more)

Claude Code plugin, with the skills and the MCP server in one:

/plugin marketplace add jpsanders/kea
/plugin install kea@kea

The plugin starts its MCP server with uvx --python 3.15, so update uv first, as in Install below.

MCP server with 25 tools (search, show, brain_status, log_entry, record_fact, decide, predict, score_prediction, roadmap_add, council_run and more), five resources and three prompts:

claude mcp add --scope user kea -- kea mcp        # Claude Code
# Codex: ~/.codex/config.toml
[mcp_servers.kea]
command = "kea"
args = ["mcp"]
{"mcpServers": {"kea": {"command": "kea", "args": ["mcp"], "env": {"KEA_BRAIN": "/home/you/brain"}}}}

The JSON works for Cursor (~/.cursor/mcp.json) and Gemini CLI (~/.gemini/settings.json). For Claude Desktop, put the full path from which kea as the command, because it starts servers without your shell's PATH. Without kea installed, use uvx with --python 3.15 --from kea-brain kea mcp, after updating uv as in Install.

An agent can read and keep the ledger, but two things stay yours: it can only rescan sources you added in a terminal, and it can only send a council packet off your machine if your kea.toml says [council] agents_may_send = true.

The rules

  1. Verified facts only. A fact has a source and a date. Everything else is UNVERIFIED and says how to check it.
  2. Never present an estimate as a measurement.
  3. Log decisions with the reasoning and the day you will look again. Unlogged reasoning does not compound.
  4. Write predictions down and score them. A prediction names a number and a date.
  5. Import distilled, not raw. Name the decision a source changes before you import it.
  6. Frameworks only with boundary conditions. A lens cited outside its stage manufactures confidence.
  7. Consensus is a signal, not a verdict. Ask what every seat was trained not to see.
  8. Ask, do not assume. Questions for the owner go on the roadmap, never into a guess.

Install

uv tool install --python 3.15 kea-brain       # recommended
pipx install --python python3.15 kea-brain
pip install kea-brain                         # in a Python 3.15 environment
docker build -t kea . && docker run --rm -it --user "$(id -u):$(id -g)" -v ~/brain:/brain kea status

kea needs Python 3.15; with --python 3.15, uv downloads it for you. Update uv first, since an older uv knows only the 3.15 previews: uv self update, or brew upgrade uv or pip install -U uv when that is how uv came. The distribution is called kea-brain and the command is kea. Then kea man --install makes man kea work.

Commands

Command What it does
kea init [path] [--example] Make a brain (the first real one becomes your default), or put back missing files
kea status / kea check The whole brain with health checks / lint it, exit 1 on errors
kea state / kea log / kea fact Facts and the dated log
kea decide / kea decisions / kea revisit Decisions and closing their loop
kea predict / kea score / kea calibration Predictions, outcomes, Brier score
kea roadmap [add|done] / kea idea Open work and parked ideas
kea plan new / kea brief / kea council / kea synth A council review, end to end
kea ingest / kea search / kea show / kea effort The evidence index
kea digest [transcript] A Claude Code session as readable files
kea mcp / kea skill install Agents
kea guide / kea man The full manual, for people and agents

Everything is in the manual: kea guide prints it, man kea shows it.

Privacy

Your brain is a folder you own; the index is a SQLite file inside it, readable only by you, that git ignores. kea has no telemetry and no account. Ingest opens your sources read only, never opens paths such as .ssh, .aws, .env, shell histories or credentials (a symbolic link is judged by where it points, and skipped if it leads out of a folder you ingest), and redacts anything shaped like a key or a token before storing it and before a packet leaves. What you write into the ledger loses only unmistakable key shapes, so your own words stay as you wrote them. The only thing that ever leaves your machine is a council packet, and kea council asks first, naming every host. API keys travel in headers, never in URLs, and no request follows a redirect. More in SECURITY.md.

Performance

One package, the standard library only, and Python 3.15's lazy imports: kea --version returns in about 30 ms and kea status in about 70 ms. Measured on one Linux machine, 1.3 GB of Claude Code transcripts index in under five seconds, a second run takes a tenth of a second because unchanged files are skipped, and a search over thousands of messages answers in about 50 ms. make bench measures it on your machine.

Why the name

The kea is New Zealand's alpine parrot: one of the cleverest birds alive, famous for taking apart whatever it finds to see how it works. Its underwings are orange. It is the sibling of huntaway, the sheepdog that guards your machine; kea guards your thinking.

Star history

Star history of jpsanders/kea

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. Built on python-package-template.

Licence

MIT. Made by James Phillip Sanders.

Metadata

Release files for kea-brain 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kea-brain 1.0.1
File Size Uploaded Provenance Actions
kea_brain-1.0.1.tar.gz 347.2 kB With provenance Details for kea_brain-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kea-brain 1.0.1
File Interpreter ABI Platform Actions
kea_brain-1.0.1-py3-none-any.whl Python 3 none any Details for kea_brain-1.0.1-py3-none-any.whl

Total release size: 500.5 kB

Release files / kea_brain-1.0.1.tar.gz

Download URL kea_brain-1.0.1.tar.gz
Size 347.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ee1ee50f0e8589606b535f7b841eaa13bb4d080c4ea6d81b8d8f63c711f25957
BLAKE2b-256 checksum
How to use checksums
f238c6654c2b804233521af3dfb069aa58715b7d2fbfc8630419d54e350a4ed3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / kea_brain-1.0.1-py3-none-any.whl

Download URL kea_brain-1.0.1-py3-none-any.whl
Size 153.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
83e177a1c2e08c7e40fc704c7c2cf319c6e6e38389c8dba1fdf4256d7c699bb6
BLAKE2b-256 checksum
How to use checksums
5f21e0753cb9748ba985fa153a669a76df3b6df7ffcae77e293d5c123079bb94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for kea-brain 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kea_brain-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page