Metadata-Version: 2.5
Name: another-brain
Version: 0.13.0
Summary: Shared long-term memory for MCP agents — one brain, many agents. Standalone embedded runtime: SQLite + FTS5 + exact vector hybrid search, local Harrier q4 ONNX embeddings, self-expiring diary model. No server, container, or daemon required.
Project-URL: Homepage, https://github.com/Flowerf19/another-brain
Project-URL: Repository, https://github.com/Flowerf19/another-brain
Project-URL: Changelog, https://github.com/Flowerf19/another-brain/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Flowerf19/another-brain/issues
Author: flowerf19
License-Expression: MIT
License-File: LICENSE
Keywords: agents,embeddings,mcp,memory,rag,sqlite
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: filelock<4,>=3.16
Requires-Dist: mcp<2.1,>=2.0
Requires-Dist: numpy<3,>=2.1
Requires-Dist: onnxruntime<1.29,>=1.28
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: pyyaml<7,>=6
Requires-Dist: sqlite-vec<0.2,>=0.1.9; sys_platform != 'win32' or platform_machine != 'ARM64'
Requires-Dist: tokenizers<0.24,>=0.23
Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Another Brain

Long-term memory your AI coding agents actually share. One brain, many agents:
what Claude Code learns on Monday, Codex can recall on Friday.

It runs as a single installed executable — no server to start, no container,
no database to administer, and nothing leaves your machine. Memories live in
one SQLite file in your user directory; embeddings are computed locally on
CPU.

## Install

Another Brain is a standard Python package — the only prerequisite is Python
3.12+ (no daemon, no root, no container runtime). Install the published
package into a venv with pip:

```bash
python -m venv .venv
.venv/bin/python -m pip install another-brain   # Windows: .venv\Scripts\python
.venv/bin/another-brain setup                   # Windows: .venv\Scripts\another-brain
```

Or install a checkout of this repo from its root:

```bash
python -m venv .venv
.venv/bin/python -m pip install .
```

The console script `another-brain` lands in the venv's `bin` directory
(`Scripts` on Windows); activating the venv puts it on PATH.

Restart the harness and your agent has memory. `setup` is a one-shot
bundle of `model pull` + `connect`: it downloads the hash-verified
embedding model (~206 MB) once, then writes the MCP server entry into each
detected harness's own config and installs a skill that teaches the agent
when to use it — no JSON to edit by hand, on any OS. Both steps are
idempotent, so re-running `setup` is safe; the individual commands stay
available below.

[uv](https://docs.astral.sh/uv/) is an optional convenience: `uv tool
install another-brain` does the same install and puts `another-brain` on
PATH in one command. The `uv.lock` file is a maintainer/development
artifact — pip installs never read it, and uv is never needed at runtime.

Run `another-brain connect` with no arguments to see which harnesses are
known and which are installed here. Supported today: `claude-code`, `codex`,
`cursor`, `gemini-cli`, `pi`.

For `pi` the connector writes the standard `{"command": "another-brain"}`
entry into `~/.config/mcp/mcp.json`, like every other harness. With the
tools renamed to bare verbs, each harness adds its own prefix on top of the
wire names: pi's adapter exposes `another_brain_health`, Claude Code shows
`mcp__another-brain__health`, and the MCP wire names themselves never
change.

## What your agent can do

Eight tools appear in the agent's toolbox (your harness may prefix them):

| Tool | What it does |
|---|---|
| `remember` | store one thing worth recalling later — a decision, a bug and its fix, a preference |
| `search` | find memories by meaning *and* keywords at once |
| `recent` | list the newest entries, or walk one day or one topic |
| `get` | fetch one memory in full |
| `reinforce` | a memory proved useful — keep it longer |
| `forget` | a memory proved wrong — drop it |
| `health` | is the brain reachable and which one is bound |
| `audit` | what changed, when, and by which agent — never the memory text |

Memory here is a **diary that forgets on purpose.** Each entry gets a
lifespan from its importance — 1 to 5 maps to 7, 30, 90, 180, or 365 days —
and expires unless an agent reinforces it after actually using it. Nothing
accumulates forever, and a memory that turns out to be wrong can be
forgotten. Forgetting is soft for 30 days, so a mistake is recoverable.

Search combines two independent signals: semantic similarity (so "how do we
handle expired tokens" finds a note about refresh logic) and full-text
keyword match (so an exact error string or file path is findable verbatim).

## 0.13.0 — 2026-08-13
Changed
Tool names shortened to bare verbs — remember, search, recent, get, reinforce, forget, health, audit (was brain_*); your harness still prefixes them, so Claude Code shows mcp__another-brain__remember and pi shows another_brain_remember. Hard rename, no aliases.
pip is a first-class install path — python -m pip install another-brain; uv stays an optional dev convenience.

## Commands

| Command | Purpose |
|---|---|
| `another-brain` | the MCP server itself (your harness runs this; you normally don't) |
| `another-brain setup` | one-shot onboarding: pull the model + connect detected harnesses |
| `another-brain connect [harness…]` | register the server + install the skill |
| `another-brain model pull` / `model status` | download or check the embedding model |
| `another-brain recent [--limit N]` | print the newest entries from the terminal |
| `another-brain doctor` | full health report; exits nonzero if something is wrong |
| `another-brain admin restore\|hard-delete ID` | undo a forget inside its grace window, or purge |
| `another-brain import-jsonl PATH` | import a JSONL v1 export |
| `another-brain serve --http` | optional loopback HTTP on 127.0.0.1:1905 instead of stdio |

`recent`, `admin`, `connect`, and `doctor` all work without the model
installed.

## Your data

Memories live in `brain.sqlite3` in your per-user data directory, and the
model in your per-user cache directory — `another-brain doctor` prints both
exact paths. Nothing is uploaded; after `model pull` the tool never needs the
network again.

| Variable | Effect |
|---|---|
| `BRAIN_DATA_DIR` | where `brain.sqlite3` lives |
| `BRAIN_MODEL_CACHE_DIR` | where the model lives |
| `BRAIN_ID` | which brain this process is bound to (default `default`) |
| `TIMELINE_TIMEZONE` | IANA zone deciding the diary day (default `UTC`) |

Each agent process loads its own copy of the embedding model, about 322 MiB
of RAM once it has embedded something — worth knowing if you run several
harnesses at once.

## Platform support

Gated in CI on Linux x86_64, macOS 14+ Apple Silicon, and Windows x86_64,
with Python 3.12–3.14. Linux ARM64 and Windows ARM64 work but have no CI
hardware. macOS Intel, macOS 13 and older, and Alpine/musl are not supported
— the install fails clearly rather than silently building from source.
`another-brain doctor` reports the tier for your machine. Full matrix in
[CHANGELOG.md](CHANGELOG.md).

## More

- [CHANGELOG.md](CHANGELOG.md) — release notes, support matrix, measured performance
- [docs/deployment.md](docs/deployment.md) — harness setup in detail, configuration
- [docs/mcp-tools.md](docs/mcp-tools.md) — the tool contracts
- [docs/memory-trust-model.md](docs/memory-trust-model.md) — how much to trust a recalled memory

MIT licensed.
