brain-core-mcp 0.2.2__tar.gz

brain_core_mcp-0.2.2/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,md}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

brain_core_mcp-0.2.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Something brain-core did wrong
+labels: bug
+---
+
+**What happened**
+
+**What you expected**
+
+**How to reproduce**
+
+```
+brain version
+brain doctor ~/Agents/NAME
+```
+
+Paste the output of both, and the tool reply if an MCP call was involved (`layers`, `stores`, `note`).
+
+**Environment**
+
+- macOS version / Linux distro:
+- Claude Code version (`claude --version`):
+- Hindsight: `brain hindsight status`

brain_core_mcp-0.2.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,15 @@
+---
+name: Feature request
+about: Something the brain should do
+labels: enhancement
+---
+
+**The situation** (what you were doing when you wished for it)
+
+**What the agent should have done**
+
+**Which tool it belongs in** (`brain_session` / `brain_recall` / `brain_remember` / `brain_distill` / `brain_status` / `brain daily`)
+
+brain-core keeps five tools. If this needs a sixth, say why it cannot live in one of the five.
+
+**Context cost** (if it touches the template pack: rules are always loaded, skills load on use, hooks and scripts are free)

brain_core_mcp-0.2.2/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+**What breaks without this change**
+
+**What changed**
+
+**Checks**
+
+- [ ] `uv run pytest` green, including `tests/eval`
+- [ ] `ruff check`, `ruff format --check`, `mypy` clean
+- [ ] if recall or remember changed: an eval row that fails without this PR
+- [ ] if the template pack changed: token cost stated here

brain_core_mcp-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: release
+
+# Tag v* → build sdist+wheel → publish to PyPI (trusted publishing, no token) → GitHub Release.
+# One-time setup on PyPI: add a "pending publisher" for xy-claude/brain-core, workflow
+# release.yml, environment pypi. See docs/RELEASING.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write     # create the GitHub Release
+  id-token: write     # OIDC for PyPI trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.12
+      - run: uv sync --all-extras --all-groups
+      - name: Tests must pass before anything ships
+        run: uv run pytest -q
+      - name: Tag must match pyproject version
+        run: |
+          v="$(uv run brain version)"
+          [ "v$v" = "${GITHUB_REF_NAME}" ] || { echo "tag ${GITHUB_REF_NAME} != pyproject $v"; exit 1; }
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with: {name: dist, path: dist/}
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with: {name: dist, path: dist/}
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with: {name: dist, path: dist/}
+      - name: Release notes from CHANGELOG
+        run: |
+          awk -v tag="${GITHUB_REF_NAME#v}" '
+            $0 ~ "^## \\[" tag "\\]" {p=1; next}
+            p && /^## \[/ {exit}
+            p {print}
+          ' CHANGELOG.md > notes.md
+          [ -s notes.md ] || echo "See CHANGELOG.md" > notes.md
+      - uses: softprops/action-gh-release@v2
+        with:
+          body_path: notes.md
+          files: dist/*

brain_core_mcp-0.2.2/.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: test
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint (ruff check)
+        run: uv run ruff check src tests
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check src tests
+
+      - name: Type check (mypy --strict)
+        run: uv run mypy
+
+      - name: Tests (pytest)
+        run: uv run pytest --cov

brain_core_mcp-0.2.2/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+pip-wheel-metadata/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.hypothesis/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+
+# uv
+.uv-cache/
+
+# Runtime artifacts (agents consuming this package store their DBs/logs;
+# ignore any that leak into this repo during development)
+*.db
+*.db-shm
+*.db-wal
+*.jsonl
+*.log
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Env
+.env
+.env.local
+
+# Machine-specific eval configs
+local/

brain_core_mcp-0.2.2/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+        args: [--maxkb=500]

brain_core_mcp-0.2.2/.python-version

@@ -0,0 +1 @@
+3.12

brain_core_mcp-0.2.2/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes. Format: [Keep a Changelog](https://keepachangelog.com). Versions follow SemVer; the tag `vX.Y.Z` must equal `pyproject.toml`.
+
+## [Unreleased]
+
+## [0.2.2] - 2026-11-02
+
+### Changed
+- PyPI distribution name is `brain-core-mcp`; PyPI rejected `brain-core` as too similar to an existing project. Command `brain` and package `brain_core` unchanged.
+
+## [0.2.1] - 2026-11-02
+
+### Added
+- Linux support: `install.sh` runs on Linux (uv, systemd user unit for Hindsight, user crontab for `brain daily` / `brain weekly`).
+- Release pipeline: tag `v*` builds, tests, publishes to PyPI by trusted publishing, and creates a GitHub Release with these notes.
+- `CHANGELOG.md`, `docs/RELEASING.md`.
+
+### Changed
+- `install.sh` installs from PyPI first and falls back to the git tag.
+
+## [0.2.0] - 2026-11-02
+
+### Added
+- The five `brain_*` MCP tools: `brain_recall`, `brain_remember`, `brain_session`, `brain_distill`, `brain_status`.
+- Store adapters: markdown vault, SQLite + FTS5, Hindsight (MCP over HTTP), entity graph as a SQLite relations table.
+- `brain init` template pack: CLAUDE.md, five generic rule files, three skills, bash guard hook, `.mcp.json`, vault skeleton (3,014 always-loaded tokens); `--user`, `--profile`.
+- `brain daily`, `brain weekly`, `brain cron install` (launchd).
+- `install.sh` one-line installer for macOS; `brain hindsight install`; `brain doctor` on `brain_status`.
+- Eval suite: 20-task fixture vault in CI, write scenarios; live recall evals on the author's vault at 100%.
+
+### Removed
+- The 14 one-tool-per-function MCP endpoints from v0.1 (still available as the Python API).
+- Kuzu as the graph backend; `brain graph import` loads a legacy dump.

brain_core_mcp-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for looking. brain-core is small on purpose; the best pull request is the one that removes a line.
+
+## Setup
+
+```bash
+git clone https://github.com/xy-claude/brain-core && cd brain-core
+uv sync --all-extras --all-groups
+uv run pytest            # 200+ tests, includes the fixture eval, no network
+uv run ruff check src tests && uv run ruff format --check src tests && uv run mypy
+```
+
+CI runs exactly those four commands. If they pass locally they pass there.
+
+## Ground rules
+
+- **Five tools stay five.** A new capability goes inside an existing `brain_*` tool or into `brain daily`, not into a sixth tool. The point of the project is an agent that never has to choose between 30 endpoints.
+- **Context is a budget.** Anything added to the template pack (`src/brain_core/templates/agent/`) must state its token cost in the PR. Rules are always loaded; skills load on use; scripts and hooks cost nothing. Prefer the cheaper one.
+- **The vault is readable.** Markdown layouts are documented in `docs/VAULT_SCHEMA.md`. A write that a human cannot read in Obsidian is a bug.
+- **Evals before claims.** A change to recall or remember comes with an eval row in `tests/eval/` that fails without it.
+- **No secrets, anywhere.** gitleaks runs in CI and the vault refuses token-shaped text. If you need a key for a test, it comes from the environment and the test skips when it is absent.
+- **Failed layers are reported, never swallowed.** Every store call returns a status; a `try/except: pass` will not be merged.
+
+## Pull requests
+
+One change per PR. Subject line under 72 characters in the imperative. Describe what breaks without the change. No attribution trailers.
+
+## Reporting a bug
+
+Use the bug template. `brain doctor` output and `brain version` save a round trip.

brain_core_mcp-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xy-claude
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brain_core_mcp-0.2.2/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.5
+Name: brain-core-mcp
+Version: 0.2.2
+Summary: Cognitive primitives for AI agents — memory, decisions, reflection.
+Project-URL: Repository, https://github.com/xy-claude/brain-core
+Author: xy-claude
+License: MIT License
+        
+        Copyright (c) 2026 xy-claude
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,ai,llm,mcp,memory
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.15
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# brain-core
+
+**A memory for your Claude Code agent that survives the session.** One local MCP server, five tools, a markdown vault you can read, an eval that proves recall. Installs with one command.
+
+[![CI](https://github.com/xy-claude/brain-core/actions/workflows/test.yml/badge.svg)](https://github.com/xy-claude/brain-core/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
+
+```
+curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex
+```
+
+---
+
+## The problem
+
+Every session with a coding agent starts from zero. You explain the project again, the decision you made last week again, the thing it got wrong on Tuesday again. Memory add-ons exist, but they put your notes in someone's cloud, expose 30 tools the agent cannot choose between, and nobody shows you an eval.
+
+brain-core is the opposite: local, five tools, markdown files you own, and a test suite that reports hit rates.
+
+## What you get
+
+```mermaid
+flowchart LR
+    CC[Claude Code] -->|MCP, 5 tools| B[brain serve]
+    B --> V[(vault/ markdown)]
+    B --> S[(brain.db SQLite + FTS)]
+    B --> H[(Hindsight vector memory)]
+    B --> G[(relations table)]
+    CRON[brain daily / weekly] --> V
+    CRON --> H
+```
+
+| Tool | One call does |
+|---|---|
+| `brain_session('start')` | the whole start block: daily brief, executive state, mental models, a recall per mission, inbox count, and a flag if the last session crashed |
+| `brain_recall(query)` | one query across every store, deduplicated, ranked by relevance and recency, capped at 6k tokens |
+| `brain_remember(text, kind)` | writes vault → SQLite → Hindsight → graph and reports each layer. Near-duplicates are skipped; a changed value gets a `⚠ Fact changed` banner and the old line stays |
+| `brain_distill(source)` | captures a URL, GitHub repo, YouTube video, PDF, file or pasted text into an immutable `raw/` folder for the agent to compile |
+| `brain_session('end')` | drains the queue, closes the day's session file, rewrites state and critique, writes the clean-close marker |
+
+Plus `brain_status()` for health in one call, and two cron jobs that write the next morning's brief, back up memory, and archive old sessions.
+
+## Install
+
+### macOS, one line
+
+<img src="docs/img/install.svg" alt="install.sh transcript" width="820">
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex
+```
+
+What it does, in order (re-running skips what is already there):
+
+```
+== 1/8 Xcode command line tools      present
+== 2/8 Homebrew                      present
+== 3/8 uv, gh, gitleaks, node, Claude Code
+== 4/8 brain-core (v0.2.0)           installed with uv tool
+== 5/8 Agent Atlas at ~/Agents/Atlas  31 files written
+== 6/8 Hindsight (required store)    service: healthy
+== 7/8 Cron                          daily 06:07, weekly Sun 07:13
+== 8/8 Doctor                        Brain: OK
+```
+
+Then, once: `export ANTHROPIC_API_KEY=...` (Hindsight uses it to reason over memories), and `claude` to sign in to Claude Code.
+
+| Flag | Meaning |
+|---|---|
+| `--agent NAME` | the agent's name (required) |
+| `--user Alex` | how the agent addresses you |
+| `--dir PATH` | where the agent lives, default `~/Agents/NAME` |
+| `--provider` | `anthropic` (default), `openai`, or `claude-code` (uses your Claude Code login; personal use only) |
+| `--profile DIR` | a folder copied over the generic rules last, for your own doctrine |
+| `--dashboard` | the Hindsight web UI on http://localhost:9999 |
+| `--ref v0.2.2` | pin a git tag instead of the PyPI release |
+
+### Linux
+
+The same one line. On Linux it installs uv, Claude Code via npm when node is present, Hindsight as a systemd user service, and the two jobs in your user crontab.
+
+### Manual, any platform
+
+```bash
+uv tool install brain-core-mcp   # or: uv tool install git+https://github.com/xy-claude/brain-core@v0.2.2
+brain init Atlas --path ~/Agents/Atlas --user Alex
+brain hindsight install          # launchd on macOS, systemd --user on Linux
+brain cron install ~/Agents/Atlas
+brain doctor ~/Agents/Atlas
+```
+
+## First session
+
+<img src="docs/img/session.svg" alt="first session transcript" width="820">
+
+```bash
+cd ~/Agents/Atlas && claude
+```
+
+The agent's `CLAUDE.md` tells it to open with `brain_session('start')`. What comes back:
+
+```json
+{
+  "session_id": "s-20261102-a1b2c3",
+  "brief": "# Daily Brief — 2026-11-02 ...",
+  "executive_state": "## Primary Objective ... ## Top Missions ... ## Pending Decisions ...",
+  "mental_models": {"active-priorities": "..."},
+  "missions": {"M-001 first mission": [ ...3 recall hits... ]},
+  "inbox": 0,
+  "recovery": null
+}
+```
+
+Say something worth keeping and the agent calls `brain_remember`:
+
+```json
+{"status": "written", "layers": {"vault": {"status": "written", "detail": "facts.md › System"},
+                                 "sqlite": {"status": "written"},
+                                 "hindsight": {"status": "written", "detail": "op 162bdbaa"}}}
+```
+
+Say "thanks, we're done" and it runs `brain_session('end')`. Tomorrow at 06:07 `brain daily` writes the next brief from what you did today.
+
+## What is in the agent folder
+
+```
+~/Agents/Atlas
+├── CLAUDE.md                 identity and the five-tool protocol (3k tokens always loaded)
+├── .claude/
+│   ├── rules/                01-identity 02-doctrine 03-authority 04-memory 05-system
+│   ├── skills/               distill, session-end, brain-check
+│   └── hooks/                block-dangerous-bash.sh (rm -rf, force-push, curl|sh …)
+├── .mcp.json                 brain serve . + Hindsight
+├── brain.yaml                stores, session files, cron schedule
+├── vault/                    facts.md patterns.md decisions_log.md corrections.md
+│   ├── sessions/             one file per day (HSAM)
+│   ├── knowledge/ raw/       the LLM-wiki: immutable sources, compiled pages
+│   └── executive_state.md    objective, missions, pending decisions
+└── data/brain.db             SQLite + FTS5 + relations
+```
+
+Everything is markdown or SQLite. Open the vault in Obsidian, grep it, commit it, delete a line. The agent will not mind.
+
+## Does it work?
+
+The eval is part of the test suite and runs in CI.
+
+| Set | Hits |
+|---|---|
+| 20 recall tasks on a synthetic fixture vault (CI) | 20 / 20 |
+| 20 tune + 10 held-out recall tasks on the author's real vault, 7 months of sessions | 20 / 20 and 10 / 10 |
+| 11 write scenarios: dedup, value-change banner, relation routing, secret refusal | 11 / 11 |
+
+Recall takes about 1.7 s per query; Hindsight is the floor. A full start block is about 4 s and under 6k tokens.
+
+```bash
+python tests/eval/run_recall.py --config ~/Agents/Atlas/brain.yaml   # your own vault
+```
+
+## How memory is organised
+
+| Kind | Lives in | Written as |
+|---|---|---|
+| fact | `vault/facts.md` under `## Domain` | `- text (date)` |
+| pattern | `vault/patterns.md` | `- **title** — text (date)` |
+| decision | `vault/decisions_log.md` | `## date — title` + Decision / Reason / Classification / Confidence |
+| correction | `vault/corrections.md` | `### [date] title` + Error / Correction / Implied rule / Theme |
+| note | `vault/sessions/YYYY-MM-DD.md` | a bullet under an HSAM section |
+| relation | `data/brain.db` | subject —[predicate]→ object |
+| raw | `vault/raw/` | immutable source with sha256; the agent compiles `vault/knowledge/` |
+
+Rules: idempotent by content hash, append-only, nothing deleted, secrets refused before any store sees them. Details in [`docs/VAULT_SCHEMA.md`](docs/VAULT_SCHEMA.md).
+
+## Requirements
+
+- macOS or Linux for the installer; the library and MCP run anywhere Python 3.12 does
+- [Hindsight](https://github.com/vectorize-io/hindsight) (MIT) as the vector store, installed for you. Postgres is embedded; embeddings run on CPU
+- an LLM key for Hindsight's reasoning, or a Claude Code login for personal use
+
+On PyPI the package is `brain-core-mcp` (the plain name collides with an unrelated project); the command is still `brain` and the import is still `brain_core`.
+
+## Roadmap
+
+- SQLite-only mode for a first run without Hindsight
+- an `import` for existing notes folders
+
+Shipped milestones: [`docs/MILESTONES.md`](docs/MILESTONES.md). Design: [`docs/SPEC_v0.2.md`](docs/SPEC_v0.2.md). Threat model for a memory that reads untrusted text: [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md).
+
+## Contributing
+
+Issues and pull requests welcome. `uv sync --all-extras --all-groups`, then `ruff check`, `mypy`, `pytest`. See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+MIT.