Metadata-Version: 2.4
Name: braincell-mcp
Version: 1.0.0
Summary: Local-first persistent-memory MCP server. Per-project brain with hybrid vector + FTS5 search, recall, remember, forget, and supersede over a single SQLite file.
Author-email: Karl Toussaint <kt2saint.create@gmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/kt2saint-sec/braincell
Keywords: mcp,memory,embeddings,sqlite,claude,rag
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COMMERCIAL-LICENSE.md
License-File: NOTICE
Requires-Dist: mcp[cli]<2,>=1.12.0
Requires-Dist: numpy<3,>=1.26.0
Requires-Dist: aiosqlite<1,>=0.20.0
Requires-Dist: rich<15,>=13.7.0
Requires-Dist: ollama<1,>=0.2.0
Requires-Dist: python-ulid<4,>=2.2.0
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn<1,>=0.30
Requires-Dist: httpx<1,>=0.28.0
Requires-Dist: anyio<5,>=4.14.0
Requires-Dist: pydantic<3,>=2.13.0
Requires-Dist: tomlkit<1,>=0.13
Requires-Dist: PySide6<7,>=6.8
Provides-Extra: openai
Requires-Dist: openai<3,>=1.40.0; extra == "openai"
Provides-Extra: native
Provides-Extra: gui
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0.0; extra == "dev"
Requires-Dist: ruff==0.16.0; extra == "dev"
Dynamic: license-file

# BrainCell

Created by [Karl Toussaint (kt2saint)](https://github.com/kt2saint-sec).

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](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

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

#### macOS

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

#### Windows PowerShell

```powershell
py -m pip install --user pipx
pipx ensurepath
pipx install braincell-mcp
```
Install and start Ollama:

- **Debian/Ubuntu:** install from [ollama.com](https://ollama.com/download/linux), then run `ollama serve` if it is not already running.
- **macOS:** `brew install ollama`, then run `ollama serve`.
- **Windows:** install Ollama from [ollama.com](https://ollama.com/download/windows); the Ollama application starts the service.

Then download the verified embedding model:


```bash
ollama pull qwen3-embedding:4b
```

Verify:

```bash
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:

```bash
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:

```bash
pipx install "braincell-mcp[openai]"
```

For source/developer installation from a checkout:

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

For a temporary source install directly from Git:

```bash
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.

```bash
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.

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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:

```bash
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

```bash
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](CONTRIBUTING.md) for contribution requirements and [ARCHITECTURE.md](ARCHITECTURE.md) for the module, CLI, schema, and on-disk state map.
