Dots Brain
Dots Brain is a self-hosted MCP memory service for explicitly saved notes. It stores source metadata and revisions in one SQLite database, supports full-text search, and can add local CPU embeddings. It does not automatically collect assistant conversations.
The stable Linux core supports explicit notes, source references, revisions, full-text search and optional local CPU embeddings. Publication and acceptance on your own host remain separate steps.
A Dot means an AI assistant or client using this shared service. It is a product term, not a separate database or a grant of access.
Source version: 1.0.2. The core includes schema-v2 storage, scoped access, MCP tools and offline maintenance. Capture and CORTEX modules are disabled and excluded from the core distribution. Stability applies to the documented core; it does not guarantee that every assistant uses memory in every conversation.
Quick start on Linux
Use Python 3.11 or 3.12 with SQLite 3.42 or newer and FTS5,
uv, curl, unzip and sha256sum.
Install the versioned source/plugin ZIP from the
1.0.2 release once it is
published with its verified assets. A source checkout or PR does not establish
download availability; check published releases.
Start in a new installation directory, then verify the archive before extracting it:
set -eu
RELEASE_URL=https://github.com/OnFiala/Dots-Brain/releases/download/v1.0.2
curl --fail --location --output SHA256SUMS "$RELEASE_URL/SHA256SUMS"
curl --fail --location --output dots-brain-1.0.2-plugin.zip "$RELEASE_URL/dots-brain-1.0.2-plugin.zip"
sha256sum --check --ignore-missing SHA256SUMS
unzip dots-brain-1.0.2-plugin.zip
cd dots-brain
uv sync --locked --no-dev --python 3.12
.venv/bin/dots-brain --version
.venv/bin/dots-brain --data-dir /absolute/private/memory setup
.venv/bin/dots-brain --data-dir /absolute/private/memory doctor
The version must be 1.0.2. Use --python 3.11 instead if needed. The ZIP
contains the release's dependency lock; keep both together. See
installation for the verified wheel alternative and
prerequisite checks. Use a local POSIX filesystem with working SQLite and
advisory locks for data, backups and exports.
For several clients on the same Linux host, use up to run an authenticated
loopback HTTP service, then configure a supported local adapter. See
installation.
.venv/bin/dots-brain --data-dir /absolute/private/memory up
.venv/bin/dots-brain --data-dir /absolute/private/memory connect codex --project work
Linux is the supported deployment platform. macOS is suitable for local source
work and stdio experiments; managed lifecycle behavior is not accepted there.
Windows is not supported. A connection configured by connect is verified at the
bridge boundary; it does not prove a remote device, web account, or conversation
has loaded the new tools.
After reloading the client, ask it to save a short project decision in work,
then ask it to find that decision. The expected calls are memory_remember,
memory_search or memory_context, and memory_get for the exact source.
Saving happens when the client calls a tool; connecting alone does not save a
conversation. See the tool reference.
| Adapter | Default client configuration |
|---|---|
codex | ~/.codex/config.toml |
claude-code | ~/.claude.json, or CLAUDE_CONFIG_DIR |
cursor | ~/.cursor/mcp.json |
mcp-json | A path supplied with --config |
Boundaries
- Data remains in the selected private directory. A checkout is not a data store.
- An MCP connection gives access only to explicitly saved memory. Snapshot capture is disabled and excluded from the core package.
- Remote OAuth needs an existing HTTPS route and an explicit owner approval flow. Dots Brain does not provision public ingress or configure web accounts. Authorization lasts 30 days; refreshing tokens does not extend it. Expiry requires owner-approved pairing again and does not delete stored notes.
- CORTEX is a separate service for project context, decisions and outcomes. Its connector is disabled and excluded from the core package. Existing module configuration and state are preserved; activation needs a separate plan.
- Backups on the same disk do not recover a lost host. Restore requires a current store for deletion reconciliation; full host-loss recovery is not yet supported.
Read security, upgrading and recovery, and the documentation index before operating a long-lived store.
Development
uv sync --locked --all-extras
uv run ruff check src tests scripts modules
uv run ruff format --check src tests scripts modules
uv run pytest -q
uv run python scripts/validate_project.py
uv build
Tests use disposable stores. The retained CI matrix covers Python 3.11 and 3.12. See
verification for the distinction between source checks
and deployment acceptance. Repository tests include preserved module characterizations
under modules/tests; the core source distribution contains only core tests.
How this project is developed
The maintainer develops Dots Brain with AI coding assistants. Independent review means a separate AI reviewer unless a report names a human reviewer. Tests and review reports document what was exercised; the maintainer owns release decisions. Reviewers in one orchestration share the workspace and permissions. Their separate review tasks do not establish process or operating-system isolation.
License
MIT. Dots Brain is independent of AI providers. Third-party dependencies and model artifacts retain their own licenses. See third-party notices.