Metadata-Version: 2.4
Name: another-brain
Version: 0.12.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: 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'
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

The one prerequisite is [uv](https://docs.astral.sh/uv/) — no daemon, no
root, no container runtime:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh              # Linux / macOS
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows
```

Then:

```bash
uv tool install another-brain
another-brain setup    # pulls the ~206 MB model, connects every detected harness
```

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

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

## What your agent can do

Eight tools appear in the agent's toolbox:

| Tool | What it does |
|---|---|
| `brain_remember` | store one thing worth recalling later — a decision, a bug and its fix, a preference |
| `brain_search` | find memories by meaning *and* keywords at once |
| `brain_recent` | list the newest entries, or walk one day or one topic |
| `brain_get` | fetch one memory in full |
| `brain_reinforce` | a memory proved useful — keep it longer |
| `brain_forget` | a memory proved wrong — drop it |
| `brain_health` | is the brain reachable and which one is bound |
| `brain_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).

## New in 0.11.0

- Redis and Docker are gone: one executable and one SQLite file, nothing running in the background.
- `another-brain connect` sets up any supported harness on Linux, macOS, and Windows with one command.
- `another-brain doctor` checks your install, model hashes, and database, and tells you what to fix.

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