NeuroGrim

a book of spells for AI agents

A language-agnostic nervous system for AI-assisted software projects.

LSP Brains is a declared overlay of project-shaped commitments on a general-purpose statistical engine — the LLM provides cognition; the Brain provides what to be cognizant of. NeuroGrim is the Rust engine that runs that overlay.

NeuroGrim implements the LSP Brains Specification — a methodology for giving AI agents continuous, honest awareness of project health through MCP-based sensory tools, A2A-based peer coordination, cross-domain correlation, trajectory intelligence, and gated governance. Sensory tools are small spells cast against the project; the Brain keeps a grimoire of their readings and tells you what has changed.

Current version: 3.0.0 — first public stable release (closes the supply-chain + Brains-2.0 self-observability master-gate campaigns). See CHANGELOG.md for what shipped + what's open.

First time here? Read PITCH.md first — elevator pitch with diagrams, about a minute. Or jump straight to the 20-minute walkthrough below.

🚀 Getting started in ~20 minutes

New here? Start with docs/getting-started.md — a clone → build → first-score walkthrough with a working example at examples/hello-brain/. It will land you on a real Brain score for a real project in under half an hour.

Already comfortable with Rust workspaces? Jump to Quick Start below.

What's Here

Quick Start

Adopt LSP Brains in any project (v3.1.1+)

# Build the CLI

cd neurogrim && cargo build && cd ..


# In your target project (any directory), scaffold the full Brain

# integration with one command. Pick a template:

#   abstract-project — non-code projects (e.g., resume + job-hunt)

#   code-project     — software projects (auto-detected stack)

#   mixed            — both code and abstract surfaces

cd /path/to/your/project

neurogrim init \

  --template abstract-project \

  --name my-project \

  --domains "<domain-1>,<domain-2>" \

  --yes

This produces, in one shot: a brain-registry.json, .claude/culture.yaml (byte-identical federation copy), 8 stub CMDBs (one per declared domain), 6 bundled general-purpose skills (hats, imagination-mode, north-star, rubber-duck, human-comms, write-skill), the PostToolUse hook + script, a CLAUDE.md (project-substituted), and a .gitignore extension. ~90% of the manual setup automated.

For project-specific skills (Tier 3 work — methodology guides paired with custom domains), scaffold a SKILL.md skeleton:

neurogrim skill new my-domain-protocol

# Then edit .claude/skills/my-domain-protocol/SKILL.md

For ecosystem coordinators bringing siblings into a federation:

# Add a sibling Brain as a read-only observed peer:

neurogrim federation register \

  --name sibling-project \

  --path ../sibling-project \

  --read-only

Run the Brain

# Validate the registry:

neurogrim validate --registry .claude/brain-registry.json


# Quick unified health read:

neurogrim score --registry .claude/brain-registry.json


# Hat-calibrated narration:

neurogrim narrate --hat visionary --registry .claude/brain-registry.json


# Run a built-in sensory tool (when applicable):

neurogrim sensory test-health --project-root . > .claude/test-health-cmdb.json

Run Tests

# Rust Brain engine tests

cd neurogrim

cargo test


# Python SDK tests

cd sdk-python

python -m pytest tests/ -v

Command aliases

Every NeuroGrim primary command also accepts a themed alias — same behavior, same flags, different feel. Aliases are additive; primary names remain canonical.

Run neurogrim --help to verify the live list.

Tool Invocation Mode (MCP vs CLI)

NeuroGrim can be reached two ways from a Claude Code session:

CLI mode: omit NeuroGrim from .claude/.mcp.json; invoke via Bash using the existing score / trend / health / validate / awareness / agent subcommands. Full docs: docs/cli-mode.md + docs/cli-sensory-surface.md. Benchmark methodology: roadmap/data/b09-bench-<date>.json (regenerate via cargo test -p neurogrim-cli --test context_overhead -- --nocapture).

Architecture

                    ┌──── MCP ────┐                                  ┌──── A2A ────┐
 Sensory Tools  ───►│             │  Brain Engine  ──► Unified Score │             │  Peer Brains
 (LSP, lint, git,   │  tool-call  │  ├─ Trajectory                   │  peer-agent │  (parent/child,
  test results, ...)│             │  ├─ Correlation + Coherence      │             │   local/external)
                    │             │  ├─ Incident detection           │             │
 LLM Agent      ───►│             │  ├─ Gated governance             │             │
 (Claude Code,      │             │  ├─ Human comms model            │             │
  Cursor, ...)      │             │  └─ Secret-ref catalog           │             │
                    └─────────────┘                                  └─────────────┘

The Brain reads pre-computed scores from CMDB files written by sensory tools (delivered via MCP). It applies confidence decay based on data freshness, computes domain weights and floor constraints, evaluates cross-domain correlations, fires incident patterns, and surfaces recommendations bounded by an attention budget. Peer Brains (fractal composition children, or an external dual-brain counterpart) exchange messages via A2A (Stage 6).

Protocols

Two distinct protocols carry traffic across the Brain's boundary. They are orthogonal and must not be conflated.

When in doubt: if the other end is a sensor or an LLM, use MCP. If the other end is another Brain, use A2A. See spec/METHODOLOGY-EVOLUTION.md §6 for the rationale behind the split.

Containers + claude-proxy (opt-in)

NeuroGrim's day-one usage runs natively on the host (cargo build

• invoke via CLI/MCP). Containers and the companion claude-proxy are opt-in capabilities for deployments that need them — multi-host A2A peer topologies, multi-agent credential isolation, sealed CI runtimes. You don't need any of this to use NeuroGrim.

When you DO want them:

• Dockerfile + docs/EXTERNAL-BRAIN-DEPLOYMENT.md — package neurogrim a2a-serve for any Docker host.
• claude-proxy/README.md — host- side credential mediator: containers get per-scope tokens (nb_sct_…); the real Anthropic API key never leaves the host; audit metadata only (no prompts on disk); instant per-token revocation.
• docs/container-brain.md — decision matrix + threat-model + cross-references.

Built-In Domains

Ten domains ship with NeuroGrim, organized in two tiers:

Core (Weighted — contribute to unified score)

Advisory (Weight 0.0 — visible in health output; promote when signal is trusted)

See docs/DOMAINS.md for full descriptions, scoring models, and a catalog of potential domains you can build.

Key Concepts

• Sensory Tools — run against a project, write a CMDB JSON file with score and findings
• Domains — named health dimensions; each backed by a CMDB file
• Confidence Decay — confidence = 100 × e^(−λ × age_days) — stale data loses weight automatically
• Floor Constraints — a critically low domain score caps the unified score
• Trajectory — velocity and acceleration computed from raw score history
• Correlations — named cross-domain patterns (compound_risk, dependency, reinforcing, blocking)
• Coherence — meta-domain that scores how well all other domains relate to each other
• Human Model — domain that tracks how a specific human wants agents to communicate
• Secret-Refs — safe catalog of credential locations; agents generate access code without seeing values
• Gates — checkpoints that block commit, merge, or deploy until conditions are met
• Hats — operational lenses that amplify different domains (engineer, reviewer, operator, security)
• Human personas — adapted output for different human readers (executive, manager, developer, specialist, PM). Distinct from agent hats, which shape what the Brain itself emphasizes.
• Attention Budget — limits displayed recommendations to prevent overload

Python SDK

Write custom sensory tools in Python using the lsp-brains package:

pip install -e sdk-python/

from lsp_brains import SensoryTool, Finding, run_server

class MyTool(SensoryTool):
    name = "my-domain"
    domain = "my-domain"

    async def analyze(self, project_root: str) -> dict:
        return self.build_cmdb(
            score=75,
            findings=[Finding("All checks passed")],
        )

if __name__ == "__main__":
    run_server(MyTool())

Register custom secret providers:

from lsp_brains import SecretProvider, SecretProviderSpec

class MyVaultProvider(SecretProvider):
    spec = SecretProviderSpec(
        name="my-vault",
        description="Internal HashiCorp Vault with AppRole auth",
        reference_template=(
            "import hvac, os\n"
            "client = hvac.Client(url=\"{vault_url}\", token=os.environ[\"VAULT_TOKEN\"])\n"
            "{env_var} = client.secrets.kv.v2.read_secret_version(path=\"{secret_path}\")[\"data\"][\"data\"][\"value\"]"
        ),
    )

MyVaultProvider.register(project_root=".")

Explore Further

• Whitepaper — Full methodology, architecture, and design principles
• Domain Catalog — All 10 built-in domains + potential domains to inspire adopters
• LSP Brains Spec — The formal specification
• Vision — Design principles and north star
• Roadmap — Stage progression and current status
• LaaS Reference — Complete archived implementation (16 domains, 26 gates, 3 hats)

Repository

• Source: https://github.com/KeenanHoffman/NeuroGrim
• Spec Repo: https://github.com/KeenanHoffman/LSP-Brains
• Origin: Extracted from Lies-as-a-Service

License

See individual files for licensing terms.