brain-engine

A case-based decision engine in Rust, plus an MCP server that exposes it to any MCP-capable client as eight tools over stdio.

IN  a SITUATION   ->   OUT  one ACTION and an EXPECTATION
IN  an OUTCOME    ->   OUT  a scored, closed CASE

Markdown stays the source of truth. SQLite holds document metadata and span offsets, Tantivy holds span text, and .index/ is derived, gitignored and rebuildable. If either index died you would rebuild it in an afternoon and lose nothing.

What is not in this repository

The corpus is not here, and that is deliberate. This repo is the engine: the loader, the matcher, the scorer, the lifecycle, the graph and the MCP surface. The claims and cases it reasons over are private. What ships here instead is a pair of synthetic fixtures under engine/tests/fixtures/, which exist to prove the loader loads and the validator rejects, not to be reasoned from.

So you can build it, run the test suite and read every line of the logic. You cannot read anybody's business out of it, because none is in it.

The command surface

brain check                     everything below, in one command
brain match <axes>              comparable cases, WITH the discard log
brain propose <axes>            one action, its counter-cases, the stops
brain open <axes> --question    a decision, opened
brain expect <id> --by <date>   what should follow, before it happens
brain close <id> --outcome --verdict --action    the outcome, scored
brain trace <id>                where a claim came from

Two design decisions worth the words

The discard log is part of the answer. match and propose return what they threw away and why, not only what they kept. A matcher that silently drops candidates is indistinguishable from a matcher that had none, and the difference is the whole point.

It refuses. close will not score an expectation that has not come due yet. A holdout keeps a tripwire on the refusal so the refusal itself stays honest. An engine that always answers is not being careful, it is being agreeable.

Build and test

cd engine
cargo build --release
cargo test

rusqlite is vendored with the bundled feature, so there is no system SQLite dependency. On a GNU toolchain you need a C compiler on PATH for that bundled build; on MSVC you need the Visual Studio C++ build tools.

cargo test gives 49 passed, 3 ignored. The three are parity tests that compare this implementation against a Python reference which sits beside the private corpus and is not in this repository. They are marked #[ignore] rather than deleted, so the gap is visible instead of tidied away. They still run in the private tree.

The MCP server

mcp/server.py wraps the compiled binary and exposes eight tools over stdio:

situation_vocab   brain_match     brain_propose   brain_open
brain_expect      brain_close     brain_trace     brain_check

Every tool shells the engine and returns its text verbatim, including the discard log and every caveat. The server does not summarise, re-rank or soften what the engine said. Point any MCP client at it:

python mcp/server.py

Licence

MIT. See LICENSE.