brain

A Go library and CLI that turns a plain folder into a persistent, evidence-first brain (keep it in git for a free audit trail — init writes plain files, it does not run git init for you). It records experiences, recalls grounded cite-or-abstain answers, distils repeated experience into validated convictions, and runs a deterministic constraint shield that vetoes "profitable but ruinous" decisions.

No network required. No model endpoint required. The engine is the deterministic core; an agent (a real LLM, via the bundled skill) is the reasoning layer, and git history is the audit trail.

• Library: github.com/muthuishere/brain/libs/go/engine — the brain engine (episodic memory, shield, consolidation). Also libs/go/storage (local + S3-compatible object storage), libs/go/ingest (web crawl + file chunking), and libs/go/modelclients (optional HTTP embedding/reranker/LLM clients). Docs: pkg.go.dev/github.com/muthuishere/brain.
• Polyglot shield: the constraint shield alone (not the full engine) is also ported to libs/python/brain_shield (Python), libs/js/brain-shield (TypeScript), and libs/rust/brain-shield (Rust) — each conforms to the same conformance/cases/shield.json golden vectors as the Go reference.
• CLI: github.com/muthuishere/brain/clis/go/brain — a thin binary over the library.
• Chunking/tokenizing are delegated to the tested citenexus/golang module rather than reimplemented.
• Design + research: docs/BRAIN.md. Feature specs land as docs/SPEC-<slug>-v1.md — see docs/SPEC-record-from-file-v1.md.
• libs/go/engine (the shield veto, conviction confidence, consolidation clustering, and recall gating) is covered by tests under libs/go/engine/*_test.go — the safety-critical core is proven, not just asserted.

Status — what's ready today

Capability	Status
Git/file storage	✅ Ready, default and only storage path the CLI uses. engine.FileStore persists episodes.ndjson/convictions.json/objective.json as plain files in a folder — commit that folder yourself, git log is the audit trail.
Agent skill	✅ Ready. brain install-skills embeds and installs the skill (below) into ~/.claude/skills/brain.
Offline recall (hash embedding)	✅ Ready, zero network by default.
Optional embedding/reranker/LLM endpoints	✅ Ready (libs/go/modelclients), opt-in via endpoints.json.
S3 / object storage (libs/go/storage)	⚠️ Library-only. S3Backend/LocalFsBackend implement a generic bytes/JSON blob interface and are usable from Go code, but there is no engine.Store implementation on S3 yet and no --store s3 CLI flag — brain --repo always uses the local file store today.
File ingest (libs/go/ingest)	✅ Ready. brain record --from-file PATH chunks a local file (ingest.ChunkFile, deterministic, no network) and records one episode per chunk.
Single-URL ingest (brain record --from-url)	✅ Ready. Fetches one URL — the CLI's only network call, and only when this flag is passed — strips HTML markup if the response is HTML, and chunks it exactly like record --from-file. See docs/SPEC-record-from-url-v1.md.
Multi-page crawl (libs/go/ingest.Crawl)	⚠️ Library-only. Crawl (same-host BFS, depth/page-capped) is implemented and tested, but not wired into the CLI — a crawl's much larger network footprint (many pages, unbounded by default) is a bigger opt-in-policy decision than a single fetch and is deliberately deferred. Call it from Go if you want multi-page ingest today.
Constraint shield signal provenance (fail-closed)	✅ Ready. A hard constraint's cost is never silently treated as 0/safe when its named signal is omitted at check time — the verdict reports undetermined:true/undetermined_by and allowed:false instead. Configurable per constraint via constraints.json's when_absent (veto/abstain/assume_safe). See docs/SPEC-shield-signal-provenance-v1.md.
Polyglot shield ports (libs/python, libs/js, libs/rust)	✅ Ready. The constraint shield (fail-closed semantics included) is also ported to Python (brain_shield), TypeScript (@brain/shield in libs/js/brain-shield), and Rust (brain-shield crate) — each verified byte-identical against the same conformance/cases/shield.json golden vectors in CI. Only the shield is ported so far, not the full engine (recall/consolidation/convictions remain Go-only). See docs/SPEC-shield-conformance-v1.md.

Install

Prebuilt binaries from GitHub Releases — no Go toolchain needed. The installer also drops the agent skill into ~/.claude/skills/brain and seeds ~/.config/brain/config.json.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/muthuishere/brain/main/install.sh | bash

Windows (PowerShell / cmd) — download install.cmd from the repo and run it, or:

curl -fsSL -o install.cmd https://raw.githubusercontent.com/muthuishere/brain/main/install.cmd && install.cmd

Already have Go? go install github.com/muthuishere/brain/clis/go/brain@latest && brain install-skills also works.

Release binaries are built for darwin/linux/windows (amd64 + arm64) by .github/workflows/release.yml on every v* tag.

Use directly

brain --repo ./mybrain init
brain --repo ./mybrain objective "preserve capital"
brain --repo ./mybrain record "Overtrading in chop bled the account" --reward -1
brain --repo ./mybrain record "Overtrading in chop bled the account again" --reward -1
brain --repo ./mybrain consolidate          # → distils a validated conviction
brain --repo ./mybrain recall "overtrading" --json
brain --repo ./mybrain check "bet the account" --reward 0.95 --signal ruin_risk=1 --signal unrepeated=0 --json
#   → allowed:false  alarm:true  vetoed_by:[never-ruin]  guaranteed:true   ("winning is actually losing")

# bulk-ingest a doc into episodic memory — one episode per chunk, no network:
brain --repo ./mybrain record --from-file postmortem.md --reward -1 --label "postmortem"

# same, but fetch a single URL instead (the CLI's only network call, opt-in):
brain --repo ./mybrain record --from-url https://example.com/postmortem --reward -1 --label "postmortem"

check requires every hard constraint's named signal to be supplied above (both ruin_risk and unrepeated — the two starter constraints from init) — that's what makes guaranteed:true meaningful. Hard constraints fail closed by default: drop --signal ruin_risk=... and the shield returns allowed:false, undetermined:true, undetermined_by:["never-ruin"] instead of silently treating the missing signal as safe. See docs/SPEC-shield-signal-provenance-v1.md for the full rationale and the when_absent escape hatch.

Endpoints (optional — works fully offline without them)

By default the CLI runs with no network: deterministic hashing recall, no reranker, no LLM. To upgrade, drop an endpoints.json in the brain repo (init writes an endpoints.example.json to copy):

{
  "embedding": {"base_url": "http://localhost:11434/v1", "model": "bge-m3", "api_key_env": "OLLAMA_API_KEY"},
  "reranker":  {"base_url": "http://localhost:11434", "model": "bge-reranker-v2-m3", "api_key_env": ""},
  "llm":       {"base_url": "http://localhost:11434/v1", "model": "qwen2.5", "api_key_env": ""}
}

Each block is independent. api_key_env names an env var — the key is read at runtime and never stored or printed. Env overrides: BRAIN_EMBED_URL, BRAIN_RERANK_URL, BRAIN_LLM_URL (+ _MODEL, _KEY_ENV).

Agent skill

brain install-skills installs skills/brain/SKILL.md into ~/.claude/skills/brain/SKILL.md and seeds ~/.config/brain/config.json (a {default, brains: {name: repoPath}} map so an agent can resolve "the crypto brain" → a repo folder). Once installed, an agent should:

1. Resolve the brain: look up the named brain in ~/.config/brain/config.json (or the default), and always pass --repo "$REPO" --json.
2. Use the command table: objective (set the goal), record (log an experience with --reward), reappraise (flip a past judgment), recall/learn (grounded, cite-or-abstain answers), check (the constraint shield — pass --signal name=value for measured risk signals), consolidate (distil repeated experience into convictions), convictions (list current beliefs).
3. Commit after every mutation — objective/record/reappraise/consolidate change the repo; git add -A && git commit right after so git history stays the audit trail. recall/learn/check/convictions are read-only, no commit.
4. Honor check's verdict literally: "allowed": false → don't take the decision, offer "fallback" instead. "alarm": true → "profitable but ruinous" — the loudest signal, surface it to the human rather than proceeding quietly. "guaranteed": true → every constraint was self-evaluated in code from a real supplied input; if false, some cost came from outside the code or was never supplied. "undetermined": true → treat exactly like "allowed": false (don't take the decision, use the fallback) — it means a required hard constraint's signal was never passed with --signal, so the shield couldn't tell if the decision was safe, fails closed by default (docs/SPEC-shield-signal-provenance-v1.md), and "undetermined_by" names which constraints were unresolved.
5. Keep multiple brains isolated — each is its own git repo; never merge two brains' folders. To share one brain across agents, share the same repo (commit/pull) and let conflicting experiences surface as conflicts instead of being averaged away.

Full behavioral spec (constraints format, endpoint config, reading raw memory directly): skills/brain/SKILL.md.

The brain on disk (all git-friendly plain text)

mybrain/
├── constraints.json   the slow layer: what this brain will never do
├── objective.json     current foreground goal + retired history
├── episodes.ndjson    raw experiences, one JSON line each (append-only)
└── convictions.json   distilled, validated beliefs

git log over the folder is the reappraisal history — the brain never overwrites its past, unlike a human.

Design in one line

Signal-to-noise, made honest: it states a belief only when experience repeats and stays consistent, abstains on the noise, surfaces conflict instead of flattening it, and hard-vetoes decisions that win on the objective but break a standing constraint. Four published ideas (goal-conditioned objectives, reflection-formed convictions, truth-maintenance dormancy, and a constrained-RL shield) in a composition nobody ships.