kea-brain 1.0.1__tar.gz

kea_brain-1.0.1/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "kea",
+  "description": "kea: a second brain that checks its facts, for you and your agents.",
+  "owner": {
+    "name": "James Phillip Sanders",
+    "email": "hello@jamesphillipsanders.com"
+  },
+  "plugins": [
+    {
+      "name": "kea",
+      "description": "Sourced facts, decisions with revisit dates, scored predictions, a council of rival models and local search over your AI sessions: three skills and an MCP server.",
+      "version": "1.0.1",
+      "source": "./",
+      "category": "productivity",
+      "homepage": "https://github.com/jpsanders/kea"
+    }
+  ]
+}

kea_brain-1.0.1/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "kea",
+  "description": "A second brain that checks its facts: sourced facts, decisions with revisit dates, scored predictions, a council of rival AI models, and local search over your AI sessions. Three skills and an MCP server.",
+  "version": "1.0.1",
+  "author": {
+    "name": "James Phillip Sanders",
+    "email": "hello@jamesphillipsanders.com",
+    "url": "https://jamesphillipsanders.com"
+  },
+  "homepage": "https://github.com/jpsanders/kea",
+  "repository": "https://github.com/jpsanders/kea",
+  "license": "MIT",
+  "keywords": ["second-brain", "memory", "decisions", "predictions", "calibration", "council", "mcp", "search", "pkm"]
+}

kea_brain-1.0.1/.editorconfig

@@ -0,0 +1,34 @@
+root = true
+
+[*.{sh,py}]
+indent_style = space
+indent_size = 4
+tab_width = 4
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 120
+
+[*.{yaml,yml,toml}]
+indent_style = space
+indent_size = 2
+tab_width = 2
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 120
+
+[*.md]
+trim_trailing_whitespace = true
+max_line_length = 120
+insert_final_newline = true
+
+[*.json]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+
+# Badge rows, the skill front matter and generated roff carry long lines by design
+[{SKILL.md,*.1,README.md}]
+max_line_length = off

kea_brain-1.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,25 @@
+---
+name: Bug report
+description: A command that did not do what the manual says
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: The command you ran, what it did, and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: output
+    attributes:
+      label: Output
+      description: The output, ideally with --json. Remove anything private from your brain first.
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: kea, Python and operating system
+      placeholder: kea 1.0.1, Python 3.15.2 on Ubuntu 26.04
+    validations:
+      required: true

kea_brain-1.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+---
+blank_issues_enabled: true
+contact_links:
+  - name: Security problem
+    url: https://github.com/jpsanders/kea/security/advisories/new
+    about: Report security problems privately, please.

kea_brain-1.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,16 @@
+---
+name: Feature request
+description: A source to ingest, a provider, a check, or a command kea should have
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What you do by hand today, or what your agent gets wrong without it.
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: What would help

kea_brain-1.0.1/.github/dependabot.yml

@@ -0,0 +1,11 @@
+---
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"

kea_brain-1.0.1/.github/pull_request_template.md

@@ -0,0 +1,20 @@
+### Description
+<!--- Provide a brief description of the changes introduced by this pull request -->
+
+### Reference
+<!--- Provide the related ticket(s) or issue id(s) this PR addresses -->
+**Ticket:**
+
+### Additional Notes
+<!--- Add any additional notes or comments for the reviewers (test instructions, examples, screenshots etc) -->
+
+### Checklist
+<!--- Use this checklist to make sure you haven't missed anything -->
+
+- [ ] Related tests have been added or updated, (if applicable)
+- [ ] Updated documentation (if applicable)
+- [ ] All checks and tests passed locally (`make checks`)
+- [ ] All checks and tests passed in CI
+- [ ] The branch is current with the base branch
+- [ ] PR has a clean commit history
+- [ ] Examples/additional configuration notes added to PR description (if applicable)

kea_brain-1.0.1/.github/workflows/dev.yml

@@ -0,0 +1,70 @@
+---
+name: ci
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    branches:
+      - '*'
+  # Run CI manually
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    uses: "./.github/workflows/python-checks.yml"
+    with:
+      python-version: "3.15"
+
+  test:
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest", "macos-latest"]
+    uses: "./.github/workflows/python-tests.yml"
+    with:
+      os: ${{ matrix.os }}
+      python-version: "3.15"
+
+  # Proves the built wheel installs on its own and works, with no source tree around it.
+  package:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.15"
+
+      - name: "Build the wheel and the sdist"
+        run: |
+          python -m pip install build
+          python -m build -o dist
+
+      - name: "Install the wheel in a clean environment and use it"
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install dist/*.whl
+          cd /tmp
+          export XDG_CONFIG_HOME=/tmp/config
+          /tmp/clean/bin/kea --version
+          /tmp/clean/bin/kea init /tmp/demo --example --no-git
+          cd /tmp/demo
+          /tmp/clean/bin/kea status
+          /tmp/clean/bin/kea calibration --json
+          /tmp/clean/bin/kea synth second-cafe
+          /tmp/clean/bin/kea search wholesale --limit 1
+          /tmp/clean/bin/kea check
+          /tmp/clean/bin/kea guide | head -3
+          /tmp/clean/bin/kea man --raw | head -1
+          echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | /tmp/clean/bin/kea mcp | head -c 200

kea_brain-1.0.1/.github/workflows/python-checks.yml

@@ -0,0 +1,107 @@
+---
+name: python-checks
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        type: string
+        default: "3.15"
+
+      cache-dependency-path:
+        type: string
+        default: "pyproject.toml"
+
+      enable-ec:
+        type: boolean
+        default: true
+
+      enable-black:
+        type: boolean
+        default: true
+
+      enable-isort:
+        type: boolean
+        default: true
+
+      enable-lint:
+        type: boolean
+        default: true
+
+      enable-docstyle:
+        type: boolean
+        default: true
+
+      enable-mypy:
+        type: boolean
+        default: true
+
+      enable-bandit:
+        type: boolean
+        default: true
+
+      checkout-fetch-depth:
+        type: number
+        default: 1
+
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: ${{ inputs.checkout-fetch-depth }}
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ inputs.python-version }}
+          cache: 'pip'
+          cache-dependency-path: ${{ inputs.cache-dependency-path }}
+
+      - name: "Install dependencies"
+        run: |
+          make init-dev
+
+      - name: "Run editorconfig-checker style checks"
+        if: ${{ inputs.enable-ec && (success() || failure()) }}
+        run: |
+          make ec
+
+      - name: "Run black style checks"
+        if: ${{ inputs.enable-black && (success() || failure()) }}
+        run: |
+          make black-check
+
+      - name: "Run isort import checks"
+        if: ${{ inputs.enable-isort && (success() || failure()) }}
+        run: |
+          make isort-check
+
+      - name: "Run bandit security checks"
+        if: ${{ inputs.enable-bandit && (success() || failure()) }}
+        run: |
+          make bandit
+
+      - name: "Run flake8 lint checks"
+        if: ${{ inputs.enable-lint && (success() || failure()) }}
+        run: |
+          make lint
+
+      - name: "Run docstring checks"
+        if: ${{ inputs.enable-docstyle && (success() || failure()) }}
+        run: |
+          make docstyle
+
+      - name: "Run mypy static type checks"
+        if: ${{ inputs.enable-mypy && (success() || failure()) }}
+        run: |
+          make mypy
+
+      - name: "Check the man page, the packaged manual and the packaged skills are up to date"
+        if: ${{ success() || failure() }}
+        run: |
+          make man-check

kea_brain-1.0.1/.github/workflows/python-tests.yml

@@ -0,0 +1,52 @@
+---
+name: python-tests
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        type: string
+        default: "3.15"
+
+      os:
+        type: string
+        default: "ubuntu-latest"
+
+      cache-dependency-path:
+        type: string
+        default: "pyproject.toml"
+
+      enable-lfs:
+        type: boolean
+        default: false
+
+      checkout-fetch-depth:
+        type: number
+        default: 1
+
+
+jobs:
+  test:
+    runs-on: ${{ inputs.os }}
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@v7
+        with:
+          lfs: ${{ inputs.enable-lfs }}
+          fetch-depth: ${{ inputs.checkout-fetch-depth }}
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ inputs.python-version }}
+          cache: 'pip'
+          cache-dependency-path: ${{ inputs.cache-dependency-path }}
+
+      - name: "Install dependencies"
+        run: |
+          make init-dev
+
+      - name: "Run tests"
+        run: |
+          make pytest

kea_brain-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+---
+name: release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+jobs:
+  assets:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout the tag"
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.15"
+
+      - name: "Check the README badge, the plugin, the MCP config and the changelog all name this version"
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          grep -q "badge/release-${TAG}-" README.md
+          grep -q "\"version\": \"${TAG}\"" .claude-plugin/plugin.json
+          grep -q "\"version\": \"${TAG}\"" .claude-plugin/marketplace.json
+          grep -q "kea-brain==${TAG}\"" .mcp.json
+          grep -q "^## ${TAG} " CHANGELOG.md
+
+      - name: "Build the wheel and the sdist"
+        run: |
+          python -m pip install build
+          python -m build -o dist
+          test -f "dist/kea_brain-${{ github.event.release.tag_name }}-py3-none-any.whl"
+
+      - name: "Attach them to the release"
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${{ github.event.release.tag_name }}" dist/* --clobber
+
+
+  # Publishes kea-brain to PyPI through trusted publishing: PyPI trusts this workflow in this repository, so no token
+  # is stored anywhere. Off until the repository variable PUBLISH_TO_PYPI is "true".
+  pypi:
+    needs: assets
+    if: ${{ vars.PUBLISH_TO_PYPI == 'true' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/kea-brain/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: "Download the wheel and the sdist the release now carries"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: gh release download "$TAG" -R "${{ github.repository }}" -D dist -p "kea_brain-*"
+
+      - name: "Publish to PyPI"
+        uses: pypa/gh-action-pypi-publish@release/v1

kea_brain-1.0.1/.gitignore

@@ -0,0 +1,19 @@
+# Make text search tools know that these "hidden" directories contain code
+!/.github/
+
+# Caches and build artifacts
+__pycache__
+/build
+.terraform
+.terraform.lock.hcl
+
+# Per-user config such as the following should generally be stored in ~/.gitignore rather than here
+#.python-version
+#.envrc
+
+
+# Local virtual environment and editor state
+/.venv
+/.idea
+/src/*.egg-info
+/src/kea/_version.py

kea_brain-1.0.1/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "kea": {
+      "command": "uvx",
+      "args": [
+        "--python",
+        "3.15",
+        "--from",
+        "kea-brain==1.0.1",
+        "kea",
+        "mcp"
+      ]
+    }
+  }
+}

kea_brain-1.0.1/AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+Instructions for AI coding agents working on kea itself. People will find them useful too. (To work inside a kea
+brain, read that brain's own AGENTS.md, or the skill in `skills/kea/SKILL.md`.)
+
+## Commands
+
+```sh
+make init-dev     # install kea and the development tools into the active environment (Python 3.15)
+make format       # apply black and isort
+make checks       # every check CI runs, in CI's order; run it before you say a change is done
+make man          # rebuild the man page, the packaged manual and the packaged skills
+make bench        # start up and command times
+make demo         # the example brain in /tmp/kea-demo
+make build        # wheel and sdist into build/dist
+```
+
+## Layout
+
+```text
+src/kea/cli.py          the command line: one cmd_* function per command, lazy imports
+src/kea/brain.py        finding a brain, kea.toml, the clock, kea init
+src/kea/markdown.py     reading and writing ledger entries without touching other lines
+src/kea/ledger.py       facts, log, decisions, predictions, calibration, ideas, roadmap, check, status
+src/kea/store.py        the SQLite and FTS5 evidence index
+src/kea/ingest.py       the adapters: claude-code, codex, opencode, chatgpt, claude, git, docs, the brain
+src/kea/redact.py       the credential path denylist and secret redaction
+src/kea/council.py      plans, packets, the parallel council run, the synthesis scaffold
+src/kea/providers.py    OpenAI compatible, Gemini and Anthropic clients on urllib
+src/kea/mcp.py          the MCP server: tools, resources, prompts
+src/kea/digest.py       Claude Code transcripts as readable files
+src/kea/skills.py       installing the skills into agent folders
+src/kea/data/           templates and example brains, plus generated files: MANUAL.md, kea.1, skills/
+docs/MANUAL.md          the one source for kea guide and the man page
+skills/                 the agent skills; make man copies them into the package
+tests/kea/              pytest, one file per module
+```
+
+## Rules the checks enforce
+
+- mypy runs in strict mode, on the tests too: every function has full type hints.
+- Docstrings use the Sphinx style and darglint checks them. Private helpers (`_name`) need none.
+- Imports are absolute. Lines are at most 120 characters in every file type, Markdown included.
+- bandit fails on shell injection and string built SQL; a justified exception carries `# nosec <code>: <reason>`.
+- `make checks` fails when `src/kea/data/MANUAL.md`, `kea.1` or the packaged skills are stale.
+
+## Conventions the checks cannot see
+
+- No runtime dependencies. The standard library only; that is a feature.
+- Every command that prints data takes `--json` with stable fields. Exit 0 on success, 1 on failure, 2 on bad
+  arguments. Commands load their modules lazily so start up stays near 30 ms.
+- kea never writes outside the brain, the per user config and the folders a command names. Ingest is read only.
+- Nothing leaves the machine except `kea council`, which asks first.
+- When a command or option changes, update `docs/MANUAL.md` and the skills in the same commit, then `make man`.
+- Add an entry to `CHANGELOG.md` for anything a user would notice.
+- Tags carry the bare version, `1.2.0`, never `v1.2.0`. The release workflow checks that the README badge, the
+  plugin files, `.mcp.json` and the changelog all name the tag.
+- Never commit secrets, a real brain, `.env` files or anything from `build/`.

kea_brain-1.0.1/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+Versions follow [semantic versioning](https://semver.org). Tags carry the bare version, such as `1.0.0`.
+
+## 1.0.1 (2026-11-14)
+
+- kea is on PyPI as `kea-brain`: `uv tool install --python 3.15 kea-brain`, `pipx install kea-brain` or
+  `pip install kea-brain`. The command is still `kea`.
+- The Claude Code plugin starts its MCP server from the PyPI wheel (`uvx --from kea-brain==1.0.1`), which is faster
+  than building from git.
+- The release workflow publishes the wheel and the sdist that the GitHub release carries, through trusted publishing,
+  so no token is stored anywhere.
+- A council seat whose server drops the connection while sending an error ends as a seat error with the HTTP status,
+  instead of an unhandled connection error; kea reads at most 4 KB of an error message.
+
+## 1.0.0 (2026-11-14)
+
+The first release.
+
+- **The ledger**, in plain Markdown that people and agents edit side by side: facts with a source and a verified date
+  (`kea fact`), a dated log (`kea log`), decisions with a revisit date or trigger (`kea decide`, `kea revisit`),
+  predictions with a date and a confidence (`kea predict`, `kea score`), parked ideas and a roadmap with a section for
+  what waits for the owner.
+- **Calibration**: `kea calibration` gives the Brier score, skill over a coin, and ten buckets of stated against
+  observed confidence.
+- **Health**: `kea status` shows the whole brain and six health checks; `kea check` lints unsourced facts, facts past
+  their recheck date, malformed entries and overdue decisions and predictions, and exits 1 on errors.
+- **The council**: `kea plan new`, `kea brief` (one hashed packet for every seat), `kea council` (every ready seat in
+  parallel, with per provider pacing, after asking before anything leaves the machine) and `kea synth` (verdicts,
+  convergence, splits and solo insights). Twelve providers preset, any OpenAI compatible server, Ollama and LM Studio
+  for local seats.
+- **Evidence search**: `kea ingest` indexes Claude Code, Codex and OpenCode sessions, ChatGPT and Claude exports, git
+  history and folders of notes into SQLite with FTS5, incrementally, read only, with credential paths refused and
+  secrets redacted. `kea search`, `kea show` with provenance and context, `kea effort` for where attention went,
+  `kea forget`.
+- **Agents**: an MCP server with 25 tools, five resources and three prompts; three skills installed into Claude Code,
+  Codex, OpenCode and `~/.agents` by `kea skill install`; a Claude Code plugin; `AGENTS.md` and `CLAUDE.md` in every
+  brain.
+- **Safety**: nothing shaped like a key or token is stored in the index or sent in a packet (provider keys,
+  `NAME_API_KEY=` lines, passwords in URLs, private keys), and unmistakable key shapes never reach the ledger;
+  credential paths such as `.ssh`, `.env.local`, shell histories and `.pem` files are refused, symbolic links
+  included; the index is private to you; requests follow no redirects; agents on MCP can neither add sources nor send
+  a packet off the machine unless `kea.toml` allows it.
+  Before release, three independent review agents found 56 issues. Six further rounds, by two more agents each,
+  checked the fixes and found more problems in them. Every leak, crash and loss of data they confirmed is fixed, and
+  each code fix is pinned by a test.
+- `kea digest` turns a Claude Code transcript into private readable files in the brain's `digests/` folder.
+- `kea init --example` makes a complete example brain to explore. `kea init` on an existing brain puts back missing
+  files and changes nothing else; `--add` makes a brain beside files you already have, and `--force` keeps a backup
+  of every file it overwrites.
+- A manual for people and agents: `kea guide`, `kea man`, `man kea` after `kea man --install`.
+- Python 3.15, no dependencies, lazy imports: about 30 ms to start.

kea_brain-1.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,6 @@
+# Code of conduct
+
+This project follows the
+[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+Be kind, assume good faith, and keep discussion about the work. Report unacceptable behaviour to
+hello@jamesphillipsanders.com; reports are handled in confidence.

kea_brain-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Issues and pull requests are welcome.
+
+## Set up
+
+```sh
+git clone https://github.com/jpsanders/kea && cd kea
+python3.15 -m venv .venv && . .venv/bin/activate
+make init-dev
+make demo
+```
+
+## Before a pull request
+
+```sh
+make format      # black and isort
+make checks      # every check CI runs, in the same order
+```
+
+`make checks` runs isort, black, editorconfig-checker, darglint, flake8, mypy in strict mode, bandit, the manual and
+skills freshness check and pytest with coverage. CI runs the same, then the tests on Linux and macOS, then installs
+the built wheel in a clean environment and runs it against the example brain.
+
+## Changing things
+
+- **No dependencies.** kea runs on the standard library alone. A change that needs a package needs a very good reason.
+- **The manual** is `docs/MANUAL.md` and **the skills** are `skills/*/SKILL.md`. `make man` copies them into the
+  package and builds the man page; `make checks` fails while any copy is stale.
+- **Templates** for new brains live in `src/kea/data/templates`, the example brain in `src/kea/data/example`. Keep
+  every line at 120 characters or fewer.
+- **A new ingest source** is an adapter in `src/kea/ingest.py` that reads, never writes, passes every text through
+  `redact`, and comes with a test built on a small fake export.
+- **Commits** are signed. Tags carry the bare version, `1.2.0`, never `v1.2.0`.

kea_brain-1.0.1/Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.15-slim
+
+ARG USER=kea
+
+# git lets kea ingest repositories; nothing else is needed at run time
+RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/* \
+    && useradd -rms /bin/bash $USER
+
+WORKDIR /app
+COPY --chown=$USER:$USER src src
+COPY --chown=$USER:$USER pyproject.toml README.md LICENSE ./
+RUN --mount=source=.git,target=.git,type=bind \
+    python3 -m pip install --no-cache-dir .
+
+USER $USER
+WORKDIR /brain
+ENV KEA_BRAIN=/brain
+# docker run --rm -it -v ~/brain:/brain kea status
+ENTRYPOINT ["kea"]
+CMD ["status"]