Metadata-Version: 2.4
Name: braincell-mcp
Version: 0.4.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.

The public vocabulary is defined in [NAMINGS.md](NAMINGS.md). In particular,
BrainCell uses **Project**, **Build**, **Connect**, **Pool**, and **Decouple
from Pool**. Earlier terms are compatibility or migration language only.
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

After PyPI publication, use `pipx` for a production install:

```bash
pipx install braincell-mcp
ollama pull qwen3-embedding:4b
```

The default embedder is local Ollama `qwen3-embedding:4b`. For hosted
embeddings, install the optional OpenAI extra instead 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
```

Before publication, install directly from source:

```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 any install, 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. You can still run Build and Connect individually:

```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 # writes .claude/skills
braincell skills add . --client codex  # writes .agents/skills
braincell skills remove . --client claude
```

BrainCell never installs these skills machine-wide. Add and Remove preserve an
edited same-name skill and report it as a conflict.

## 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.

## 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
# Obtain a Project ULID when building/registering the Project.
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.
Pool names compare after Unicode NFKC normalization, whitespace normalization,
and case-folding; the original spelling remains visible.

### 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 command 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.
- Pool reads are explicit; an ordinary Recall or Search never silently widens
  scope.
- 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
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,openai]"
python -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.
