BrainCell

Created by Karl Toussaint (kt2saint).

BrainCell is local-first project memory for MCP clients. Each Project has one database and a stable project ULID. Connecting BrainCell to Project A never starts it for, or exposes it to, Project B.

See CHANGELOG.md for verified public release notes.

Current status

This release establishes project-local connections and skills, live named Pools, native Memory Map Pool controls, and preview-first recovery for retired shared data. Legacy automation and shared-data behavior are not part of the project-only workflow.

What is isolated

• Project memory is stored and queried per Project.
• Codex uses only <project>/.codex/config.toml; Codex must trust the project before it loads that configuration.
• VS Code uses only <project>/.vscode/mcp.json.
• Claude connection is project-bounded: private local-project scope is the default, and shareable .mcp.json scope is an explicit choice.
• A package installation can live anywhere on the machine. It does not select a Project or enable BrainCell in another Project.

Connection management preserves unrelated client configuration. It writes only BrainCell's entry, refuses a conflicting user-managed entry, creates a backup, and replaces the configuration atomically. Existing legacy client-wide entries are detected for explicit cleanup; BrainCell never silently removes them.

Install

The native Memory Map desktop GUI (PySide6/QtWebEngine) is a required BrainCell runtime dependency and is installed with every supported installation. There is no supported headless or server-only BrainCell installation.

Install with pipx

BrainCell uses Ollama locally with the verified default embedding model qwen3-embedding:4b.

Debian/Ubuntu

sudo apt update
sudo apt install -y pipx python3-venv
pipx ensurepath
source ~/.bashrc
pipx install braincell-mcp

macOS

brew install pipx ollama
pipx ensurepath
source ~/.zshrc
pipx install braincell-mcp

Windows PowerShell

py -m pip install --user pipx
pipx ensurepath
pipx install braincell-mcp

Install and start Ollama:

• Debian/Ubuntu: install from ollama.com, then run ollama serve if it is not already running.
• macOS: brew install ollama, then run ollama serve.
• Windows: install Ollama from ollama.com; the Ollama application starts the service.

Then download the verified embedding model:

ollama pull qwen3-embedding:4b

Verify:

braincell --help
braincell-mcp --help
pipx list

braincell --help lists every subcommand; pipx list reports the installed braincell-mcp version. There is no braincell --version flag.

Upgrade later:

pipx upgrade braincell-mcp

Ubuntu/Debian may reject ordinary system pip install commands because of the externally managed Python environment. pipx is the recommended production installation method.

For hosted embeddings, install the optional OpenAI extra and configure its documented provider environment:

pipx install "braincell-mcp[openai]"

For source/developer installation from a checkout:

git clone https://github.com/kt2saint-sec/braincell.git
cd braincell
./scripts/install.sh

For a temporary source install directly from Git:

python3 -m pip install "braincell-mcp @ git+https://github.com/kt2saint-sec/braincell.git"

Installing the package never selects a Project, creates a database, or changes a client configuration. After installation, connect one selected Project with the dry-run/apply flow below. The commands are braincell, braincell-mcp, and braincell-map.

Connect one Project

Choose the Project deliberately. BrainCell resolves symlinks, refuses /, and requires acknowledgements for a home directory, a non-Git Project, or a privileged/root invocation.

cd /path/to/project
braincell setup . --dry-run --client codex
braincell setup . --client codex --yes

The first command resolves the path and displays every planned database, registry, client-configuration, skills, and optional Pool-recall write without applying it. --yes applies the plan. Use --with-skills for project-local skills and --automatic-pool-recall "Pool name" only for an existing named Pool with Claude.

braincell build .
braincell connect . --client claude --scope local

braincell install remains a compatibility alias for braincell connect; uninstall remains an alias for disconnect. Disconnecting removes only BrainCell's managed entry for that client and Project. It does not delete Project memory.

For Codex, open the selected trusted Project after connecting. A Codex session outside that Project has no BrainCell project configuration to load.

Skills are a separate, explicit choice:

braincell skills add . --client claude
braincell skills add . --client codex
braincell skills add . --client opencode
braincell skills remove . --client claude

BrainCell never installs these skills machine-wide. Installing and removing skills preserves an edited same-name skill and reports it as protected; a skill an earlier BrainCell release installed is recognized and updated in place. In the Memory Map, Install skills and Remove unchanged skills apply only to the Connected Project. They never change Pool membership or widen memory access.

Use Project memory

braincell recall "how did we handle rate limiting?"
braincell search "throttle"
braincell start .

braincell start, braincell gui, and braincell-map open the native Memory Map for the selected Project. The embedded localhost server is an implementation detail of that desktop app, not a browser product or an always-on service.

Build reads supported documents and transcripts into that Project's database. braincell sync is the incremental compatibility alias for Build. Remember, Forget, and Correct memory are MCP actions; normal Recall and Search are always limited to the connected Project.

In the Memory Map, selecting a Project changes its catalog card, statistics, and Pool membership controls. The ordinary Search and Recent notes panes always name and read the Connected Project. Use named Pool Search or Recall for an intentional cross-Project read.

Inspect persistent state without changing it:

braincell storage .
braincell storage . --keep-backups 3
braincell storage . --keep-backups 3 --backup-root /path/to/recovery-backups
# Warning-only review thresholds; values are bytes and never change memory.
braincell storage . --warn-project-bytes 1073741824 --warn-free-bytes 2147483648

The report includes file sizes and Project row counts. Retention output is a dry-run plan by default: it never deletes backups, indexed transcripts, operation history, tombstones, or curated memory. Project databases grow with indexed content and retained history, so use this report to review storage deliberately.

The optional --warn-project-bytes and --warn-free-bytes thresholds make a read-only review warning visible in CLI output. They are intentionally per command rather than a hidden machine assumption: choose margins that suit the actual disk. A warning never blocks normal use, deletes memory, or enables cleanup. The Memory Map also highlights when the exact optional snapshot or compaction workspace cannot fit on the local disk.

Executing retention is a separate, explicit step:

braincell storage . --keep-backups 3 --apply
braincell storage . --expire-operations-days 180 --expire-tombstones-days 180 --apply

Nothing is ever expired by default — --apply is refused unless at least one retention option is configured, snapshots referenced by undo history (and tombstoned notes referenced by recorded operations) are never deleted, and active or superseded memory is never touched.

Permanent stale-state cleanup and compaction

For the smaller, evidence-backed permanent workflow, preview first and retain the printed digest:

braincell storage . --hard-prune --keep-backups 3 --expire-tombstones-days 180
braincell storage . --hard-prune --keep-backups 3 --expire-tombstones-days 180 \
  --apply --approve <digest> \
  --confirm "DELETE WITHOUT LOCAL RECOVERY SNAPSHOT"

Hard-prune can only remove expired tombstones, old operation history, and unprotected backup files. It never selects active/superseded memory, indexed documents/chunks, semantic similarity matches, or LLM suggestions. Add --local-recovery-snapshot to request a same-host copy first, then confirm with DELETE; a snapshot is optional and is not a guaranteed backup. If a live reader blocks WAL truncation, cleanup remains recorded and consistent, while compaction reports a safe retry state instead of closing clients.

The Memory Map offers the same Connected Project-only Analyze → Review → Confirm → Run flow. Its optional trust setting only skips retyping DELETE; it never skips evidence, digest verification, final Apply, or execution safeguards.

Pools: intentional, live cross-Project reads

A Pool is a named set of stable Project ULIDs. It stores memberships only: it never contains copied notes, documents, chunks, or vectors. Pool Search and Recall resolve members through the registry at query time and open their databases read-only. Missing, inaccessible, corrupt, or incompatible members are reported and skipped without failing the whole query.

braincell pool create "release work"
braincell pool add "release work" <project-a-ulid> <project-b-ulid>
braincell pool search "release work" "deployment rollback"
braincell pool recall "release work" "which rollout guardrail applies?"
braincell pool decouple "release work" <project-b-ulid>

Decouple from Pool removes only that membership. It never changes either Project's memory, client connection, Project registration, or membership in another Pool. Re-adding a member restores its live results without a Build.

Optional Automatic Pool recall

Automatic Pool recall is disabled by default. Enable it only for a selected Project and Pool:

braincell automatic-pool-recall enable . --pool "release work"
braincell automatic-pool-recall status .
braincell automatic-pool-recall disable .

Claude private-local scope writes only .claude/settings.local.json. Add --scope project only when you intentionally want shareable .claude/settings.json. The hook stores the stable Project ULID and Pool name, not an absolute Project path. It no-ops outside that connected Project, and ordinary Recall remains Project-only.

Safety model

• There is no ordinary query that reads every Project.
• There is no shared operational memory database.
• Writes remain pinned to the Connected Project.
• Concurrent Build and maintenance mutations for one Project are refused rather than allowed to interleave.
• Pool reads are explicit; ordinary Recall or Search never silently widens scope.
• Keyword operations remain available when embeddings are unavailable; an explicitly semantic Search still reports the provider failure.
• A legacy shared installation or database is a recovery/migration concern, not a normal runtime mode. Do not delete it until the dedicated migration workflow has previewed, backed up, and verified the recovery.

Development

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e ".[dev,openai]"
python3 -m pytest
ruff check braincell tests

The Memory Map is a PySide6/QtWebEngine application. Test its native window and bridge for desktop changes; a standalone-browser test is supplemental only. See CONTRIBUTING.md for contribution requirements and ARCHITECTURE.md for the module, CLI, schema, and on-disk state map.