Brain Ai Memory

English | [한국어](README.ko.md) | [简体中文](README.zh-CN.md)

Brain-AI Memory — Stop Re-explaining Your Project

Open a new Codex or Claude Code session and continue from the last one.

Brain-AI Memory keeps the facts, decisions, exact values, and next steps you choose on your computer, organized by project so memories do not spill into other work. Turn on session automation and the next session receives the relevant memory and a handoff from the last one. When a fact changes, its previous version and source remain traceable. Existing MEMORY.md files stay untouched.

Runs locally · No API key · No account · No database setup

[](https://github.com/Hahyun-Lee/brain-ai-memory/actions/workflows/ci.yml) [](https://github.com/Hahyun-Lee/brain-ai-memory/releases/latest) [](pyproject.toml) [](LICENSE)

[Try it in 60 seconds](#see-it-in-60-seconds) · [Use an existing MEMORY.md](#adopt-an-existing-memorymd) · [Connect Codex or Claude Code](#connect-codex-or-claude-code) · [See the test results](#evidence-status)

Past sessions → the right project memory → continue in the next session. Optional: stop a command when it conflicts with an approved rule.

> Search can find a similar old note. Brain-AI Memory also tracks which project > it belongs to, whether a newer fact replaced it, and what the next session > should do.

See it in 60 seconds

Install from the repository, then run the synthetic tour in a disposable directory before touching a real memory file:

git clone https://github.com/Hahyun-Lee/brain-ai-memory.git
cd brain-ai-memory
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

DEMO_HOME="$(mktemp -d)"
brain-ai --home "$DEMO_HOME" tour

Brain-AI Memory: current memory and a session handoff
1  BIND     Atlas 2.1 → belongs_to → Atlas
2  RECALL   Atlas 2.1 release day is Thursday.
3  STATE    open_reviews = 3
4  UPDATE   Friday → superseded by → Thursday
5  HANDOFF  checkpoint handoff_...
Optional action checks
6  GUARD    blocked: release approval is required before production deployment
7  FALLBACK completed after 2 attempts

The tour proves the local package runs; it does not import your files or show autonomous agent behavior.

What is tested: the complete 123-test suite runs on Python 3.12; the core runtime and adoption workflow also run on Python 3.10 and 3.11. Clean-wheel checks cover a real process restart/resume, subprocess host-hook setup, automatic checkpoint/resume, and 20/20 component contracts. This is integration evidence, not a claim about better LLM answers.

Is it for you?

Use Brain-AI Memory when all three are true:

1. Work continues across many sessions.
2. Facts, rules, or exact state keep changing.
3. A stale or cross-project memory can cause a real mistake.

Typical users run multi-project coding agents, months-long research workflows, operations agents that track tickets and approvals, or several sub-agents across Codex and Claude Code.

You probably do not need it for a one-off chat, a short single-repository task, ordinary document search, or a MEMORY.md that is easy to prune by hand.

Default recall uses transparent local multilingual BM25 over SQLite; no embedding model is downloaded. Vault and Smart Connections backends are optional. Tools-only mode waits for the host to call it. Opt-in automatic mode uses each prompt only to select same-project records, supplies bounded context, and checkpoints observed changes without saving the raw conversation.

Adopt an existing MEMORY.md

If you did not run the tour above, install the base package from a checkout:

git clone https://github.com/Hahyun-Lee/brain-ai-memory.git
cd brain-ai-memory
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

From the project that owns the memory file, pin one project root and local runtime home for the rest of the workflow, then give the records one stable scope:

cd /path/to/your/project
export PROJECT_ROOT="$PWD"
export BRAIN_AI_HOME="$PROJECT_ROOT/.brain-ai"
brain-ai audit MEMORY.md --entity my-project

Audited /path/to/MEMORY.md
Entity: my-project
Entries: 84

Ready to import:       63
Needs review:          13
Duplicate candidates:  8
Possible conflicts:     3

Review plan: /path/to/your/project/.brain-ai/workflows/audits/audit_0123456789abcdef.json
Source file and memory store unchanged.
Next: brain-ai --home /path/to/your/project/.brain-ai review audit_0123456789abcdef

Inspect the source-addressed entries, approve the unambiguous ones, and apply that saved review:

brain-ai review audit_0123456789abcdef
brain-ai review audit_0123456789abcdef --approve-ready
brain-ai apply review_0123456789abcdef --yes

--approve-ready approves ordinary semantic and episodic entries and skips exact duplicate candidates. State and executable-rule candidates stay unresolved. Audit never guesses that one fact replaces another; when that is your intent, override that item's decision with explicit --supersede. Project-scoped supersession requires the old record to be linked to the same project; it cannot deactivate global or another project's memory. Applying a review writes only to the selected Brain-AI home; it does not edit MEMORY.md.

If the current directory contains .claude/MEMORY.md or MEMORY.md, the path can be omitted. Discovery never crawls your home directory or provider logs. Use brain-ai audit ... --no-save when you want a pure preview without even a saved audit plan.

The runtime home contains ordinary local SQLite, JSON, and JSONL files. The package does not encrypt them: keep .brain-ai/ private and out of source control, and back it up according to the sensitivity of your records.

What audit does and does not decide

The audit parses inert Markdown into entries with source path, line range, and content hashes. It reports normalized exact duplicates and a possible conflict when the same explicit key has different literal values. These are review cues, not judgments about which statement is true or current.

| Review choice | How it is authorized | |---|---| | ordinary fact or event | --approve-ready, or explicit --set ITEM=semantic\|episodic | | exact state | explicit --set ITEM=state on a literal key: value entry | | procedural rule | explicit --rule ITEM=SAFE_PATTERN and --rule-effect warn\|block | | replacement fact | explicit --supersede ITEM=MEMORY_ID | | leave out | explicit --set ITEM=skip, or automatic skip for an exact duplicate candidate |

Audit never infers truth or staleness from age, wording, or file order. Before the first successful apply, a source or typed-store change stops the operation and requires a new audit. Once completed, reapplying that review is an idempotent no-op; the receipt reports whether the source later changed.

An applied batch can be rolled back explicitly:

brain-ai rollback batch_0123456789ab --yes

Rollback restores the prior active view where it can do so safely. It is logical rollback, not physical erasure: the source file, import receipt, and provenance evidence are retained. A fresh audit and review can import the same source again while retaining both attempts in the ledger.

Connect Codex or Claude Code

Use automatic mode when you want a new session to recall the same project and a turn with relevant changes to leave a checkpoint without relying on the agent to remember every call. Changes are previewed before anything is written.

# Install the automatic-session extra from the downloaded repository
cd /path/to/brain-ai-memory
python -m pip install ".[mcp]"

# Then run once from the project that owns this memory
cd /path/to/your/project
export PROJECT_ROOT="$PWD"
export BRAIN_AI_HOME="$PROJECT_ROOT/.brain-ai"
brain-ai init
brain-ai entity add --name my-project --type project  # skip if it already exists

# Codex: preview, apply, then open a new Codex session in this project
brain-ai connect codex --entity my-project --mode loop --project-root "$PROJECT_ROOT"
brain-ai connect codex --entity my-project --mode loop --project-root "$PROJECT_ROOT" --apply
brain-ai doctor --host codex --entity my-project --mode loop --project-root "$PROJECT_ROOT"

For Claude Code, replace codex with claude-code. If you imported a MEMORY.md, that import already created the project entity. Codex asks you to trust the exact project hooks; review them with /hooks, then start a fresh session. doctor reports configured after installation and active only after one real start → prompt → stop cycle has been observed.

Automatic mode is deliberately project-only. At session start it supplies the latest handoff and a hard byte-bounded set of current records. Each prompt is used transiently to select relevant records from that same project. It does not store raw prompts, raw tool output, assistant messages, or edited file contents, and it never promotes a sentence to a fact, rule, or exact state on its own. See [Automatic session memory](docs/08-autonomous-loop.md) for the event flow, privacy boundary, host differences, and removal commands.

If you only want on-demand memory tools, omit --mode loop:

brain-ai connect codex --entity my-project --project-root "$PROJECT_ROOT"
brain-ai connect codex --entity my-project --project-root "$PROJECT_ROOT" --apply

In tools-only mode, Codex or Claude Code chooses when to recall, save, and checkpoint. --scope user is available only for that deliberate tools-only setup. brain-ai disconnect ... also previews its diff and requires --apply before changing host configuration.

Previews show only a sanitized view of the managed brain-ai-memory entry; unexpected environment data is redacted and unrelated host configuration is not printed. Disconnect removes only an entry owned by this command from the same scope/project config and Brain-AI home. A supplied --entity must also match. Manually written connection entries are not owned by these commands and must be edited or removed manually.

The generated project entry pins the current Python interpreter and Brain-AI home by absolute path so it still starts outside the activated shell. Treat it as machine-local configuration; review those paths before committing or sharing the host config.

The generated connection locks every memory call to the chosen project. An explicit attempt to read or write another project is rejected rather than silently changing scope.

In tools-only mode, add an equivalent instruction to the project's AGENTS.md or CLAUDE.md when you want the host to follow a repeatable memory routine:

For cross-session work, call brain_resume first and brain_context before using
project facts. Save only durable decisions, events, or changed state with
brain_remember. Before handing work to another session, call brain_checkpoint
with a short summary and concrete next_actions.

Hand off and resume

At the end of a session, record the settled summary and concrete next actions. The next session can read the latest handoff for exactly the same entity:

brain-ai handoff --entity my-project \
  --summary "Release review completed; Thursday is the approved date" \
  --next "Run the staging deploy"
brain-ai resume --entity my-project

Connected agents can use brain_checkpoint and brain_resume for the same flow; the project connection supplies the default entity. Before the first handoff, resume/brain_resume returns status: not_found with an empty summary and next_actions; this is a normal first-run result.

What changes when you add it?

| Failure you see | What Brain-AI Memory adds | |---|---| | an existing MEMORY.md mixes durable facts, events, rules, and state | source-addressed audit, explicit review, and an import receipt | | two projects or releases leak into each other | keeps records bound to one entity out of another entity's recall; intentionally unscoped records remain shared | | a reviewed fact replaces an older fact | removes the chosen old version from that project's active view while keeping its source history and any other project bindings | | the model estimates a value that is already known | typed exact state outside prose | | repeated experience remains buried in session logs | lets you review it before promoting it to knowledge or a rule | | the next session starts without the prior decision | a project-scoped handoff with the last summary and unfinished work |

Use it when you are building a coding, research, operations, or assistant agent that works across sessions. It is also useful when RAG finds relevant text but still mixes projects, returns stale facts, or loses exact state. For one-off chat or ordinary document search, RAG alone is usually simpler.

For provider-neutral manual MCP configuration, follow the [MCP guide](docs/07-mcp-server.md). You can also use the [CLI and Python runtime](docs/05-runtime.md). See the [ways to start](#start-with-the-part-you-need) or [test results](#evidence-status) for more detail.

What the system manages

| Memory-management responsibility | What the current source does | |---|---| | existing Markdown memory | audits, reviews, and imports approved entries with line-level provenance while leaving the source file unchanged | | selected evidence | stores explicit memory writes; automatic mode may also store bounded relative edit-target metadata, never file contents or the raw transcript | | working context | reconstructs an entity-scoped bundle; automatic mode adds a hard 6,000-byte ceiling and source identifiers before supplying it to the host | | episodic memory | preserves ingest-timestamped events, entity bindings, and retained import evidence | | semantic memory | stores sourced reusable knowledge and versions facts only through explicit supersession | | procedural memory | stores rules and only promotes episode candidates after preview and approval | | exact state | keeps knowable values in a typed store rather than asking the model to estimate them | | lifecycle and handoff | records consolidation, reconsolidation, logical active/inactive decisions, rollback evidence, handoff/resume, and dirty-only idempotent automatic checkpoints | | host connection | previews and writes a project-locked connection; opt-in hooks automate recall, action checks, acknowledgement, and checkpoint timing |

Entity links, source labels, and the component schema apply across all stores. Tools-only mode does not collect provider sessions or place memory into model context on its own. Automatic mode uses prompts transiently for retrieval but does not persist raw prompts, raw tool output, assistant messages, or edited file contents. File compaction, splitting, and physical deletion stay with the host. CLI limit bounds records; the automatic context path is byte-bounded.

Write and query memory directly

The adoption workflow creates its project entity. You can also create entities and write records directly:

brain-ai entity add --name "Atlas" --type project --alias A
brain-ai remember --type episodic --entity Atlas \
  --text "The release moved to Thursday" --promote semantic
brain-ai remember --type state --entity Atlas --key open_reviews --value 3
brain-ai run --entity Atlas \
  "What changed recently and how many reviews remain?"
brain-ai consolidate          # preview
brain-ai consolidate --apply  # promote after preview
brain-ai handoff --entity Atlas --summary "release review complete"

The component ontology is validated when the runtime starts. Inspect it with brain-ai ontology; the canonical schema remains [schema/brain_components.yaml](schema/brain_components.yaml).

Add an action check (optional)

Tools-only mode exposes brain_check_action; it never runs arbitrary shell commands, so the host must treat gate.allowed = false as a stop. Automatic mode wires project-scoped block rules to the supported

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Hahyun-Lee
• Source: Hahyun-Lee/brain-ai-memory
• License: MIT

Install and usage instructions live in the source repository linked above.