Brain4Agent

English | 简体中文 | 日本語 | 한국어

Long-term memory for agents. CJK-first retrieval, no model in the core path, and evidence instead of confidence scores.

pip install "Brain4Agent[precise]" needs Python 3.11+, plus a 20 MB optional dictionary. Everything works without it.

Contents

• What it is
• Install
• Quick start
• How it works
• Benchmarks
• Running alongside another memory server
• Against the frontier
• Status
• Contributing
• Special thanks
• License

What it is

An agent working on a codebase accumulates context: why a decision was made, which approach failed, where a deployment lives. Brain4Agent stores those turns in one SQLite file and retrieves them by session.

• CJK works out of the box. Character bigrams need no dictionary and no segmentation model. The benchmarked numbers are Chinese; Japanese, Korean and Vietnamese are supported and tested.
• The core makes no model calls. Retrieval is BM25: no API key, no accelerator, no cold start, single-digit milliseconds per query.
• It reports evidence, not verdicts. A search returns which question words the corpus never contained (corpus_missing) and which ones a given session lacked (missing_terms). The caller decides what that means.
• What is stored is not what is indexed. A memory keeps its full text; the index can hold a narrower, more distinctive version.

Memories also carry tags (scope), superseded_by (replacement) and refs (one-hop links), supplied by the writer.

Install

pip install "Brain4Agent[precise]"   # recommended: adds jieba, hit@1 0.950
pip install Brain4Agent              # zero dependencies: bigrams only, hit@1 0.875

Windows and macOS both work; Python 3.11 or newer is required. The package is on PyPI as https://pypi.org/project/Brain4Agent/. To work on the code itself, git clone and pip install -e ".[precise,dev]".

jieba is a 20 MB static dictionary. Without it the code falls back to bigrams.

Windows, non-ASCII input. The MCP server and the CLI pin their stdin/stdout to UTF-8, so CJK content works regardless of the console code page. Command line arguments are decoded by Python before any of that runs, though — if you pass non-ASCII text as an argument, set PYTHONUTF8=1.

Quick start

CLI

$ brain4agent exchange \
    "中文查询搜不到记忆，recall 返回空" \
    "根因在 keywords.py 第 443 行，正则不含汉字范围"
stored exchange in session 913bcac81341

$ brain4agent exchange \
    "杭州那台测试机的地址是 203.0.113.42" \
    "部署目录 /opt/demo-app，跑的是 PostgreSQL 14"
stored exchange in session c060a5294037

$ brain4agent search "中文查询为什么搜不到" -k 1
1 sessions for '中文查询为什么搜不到'
  [ 6.73 cov=1.00] 913bcac81341

--- 913bcac81341  score=6.73  coverage=1.00 ---
user: 中文查询搜不到记忆，recall 返回空
assistant: 根因在 keywords.py 第 443 行，正则不含汉字范围

A question the store cannot answer:

$ brain4agent search "杭州测试机上装的是什么数据库" -k 1
1 sessions for '杭州测试机上装的是什么数据库'
  corpus has no: 数据库, 机上
  [ 4.81 cov=0.28] c060a5294037  session lacks: 数据库, 机上

Bulk-load an existing history from JSONL (one object per line, content required):

$ brain4agent import conversations.jsonl
imported 4 turns across 2 sessions

{"session_id": "s1", "role": "user", "content": "中文查询搜不到记忆"}
{"session_id": "s1", "role": "assistant", "content": "根因在 keywords.py 第 443 行"}

MCP server

{"mcpServers": {"brain4agent": {
    "command": "python",
    "args": ["-m", "brain4agent.mcp_server"],
    "env": {"BRAIN4AGENT_DB": "/path/to/brain.db"}
}}}

Five tools:

The same library is also packaged as an agent skill.

Library

from brain4agent import MemoryStore

with MemoryStore("brain.db") as store:
    sid = store.new_session()
    store.add("杭州那台测试机的地址是 203.0.113.42", session_id=sid, role="user")
    store.add("部署目录 /opt/demo-app", session_id=sid, role="assistant")

    result = store.search("杭州测试机上装的是什么数据库")
    print(result.corpus_missing)        # ['数据库', '机上']
    print(result.best().coverage)       # 0.28

add_exchange(user=..., assistant=...) stores a pair as one session. Retrieval is session-level, not turn-level.

Bulk imports go through batch(), which defers the commit to one per group:

with store.batch():
    for turn in turns:
        store.add(turn.text, session_id=turn.sid, role=turn.role)

Optional hosted judge

Off by default. Enabled only when a key is present.

from brain4agent import Judge, MemoryStore

judge = Judge.from_env()          # reads BRAIN4AGENT_JUDGE_KEY; None if unset
if judge:
    r = store.search_judged("question", judge)
    print(r.verdict)              # found / not_found / uncertain

uncertain is a third state, distinct from not_found: a judge that times out is not evidence that the memory does not exist.

How it works

                write                          read
                  │                              │
        bigrams + dictionary words          dictionary words
                  │                              │
                  ▼                              ▼
          ┌──────────────────────────────────────────┐
          │  SQLite: id, session, role, content,     │
          │          created_at, tokens              │
          └──────────────────────────────────────────┘
                  │                              │
                  ▼                              ▼
           BM25 index (in memory)  →  session-level evidence
                                        + corpus_missing
                                        + per-session coverage

Storage

One SQLite file. Rows are turns; the unit of retrieval is the session. Index tokens are computed at write time and cached in a column, so rebuilding the in-memory index is a counting exercise.

                       import    rebuild   query
127 turns   44 sessions          3.9 ms   1.8 ms
1016 turns  352 sessions  0.25 s  29 ms   3.7 ms

Writes commit in batches. A 1,016-turn import takes 3.8 s one commit at a time and 0.25 s inside batch().

Read/write tokenizer split

Indexing and querying use different tokenizers. Measured over a 3×3 grid of index strategy against query strategy (D-019), then two changes on top of the best cell (D-037):

The last row adds two things the 3×3 grid did not test: interrogatives are removed from the query side, and a session's best three turns are folded into one score. Both are measured in D-037; the first 3×3 grid is D-019.

Evidence, not verdicts

• corpus_missing — a content word from the question appears nowhere in the stored corpus.
• missing_terms (per session) — which question words that session lacked.
• term_frequencies — how many sessions each question word appears in. A word present in 453 of 2898 memories is neither missing nor misspelt; it is too common to separate anything, and the query needs another word (D-039).
• related_terms — up to five words the top sessions use that the query did not. The third word a two-word query needs, taken from the corpus (D-040).

Whether to refuse is the caller's decision; the store reports the fact.

Benchmarks

All numbers are reproducible from the bench/ scripts, which import the shipping code rather than a copy of it.

LongMemEval (English) — retrieval

470 answerable questions over the s variant (average haystack 493 turns):

hit@1    0.8660
hit@5    0.9511
hit@10   0.9660
MRR      0.8990

python -m bench.run_longmemeval --dataset s. bench/data/ is fetched by bench/fetch_data.py (264 MB, not committed).

These use the harness's bigram/bigram configuration. The store's own configuration (wide index, words minus question words, fuzzy) scored 0.8596 on the same 500 tasks and took 8× longer, so LongMemEval keeps bigrams — measured, not assumed.

Across three benchmarks:

PrecisionMemBench — retrieval precision

77 single-turn cases over 35 beliefs. No generation model and no judge: the answer is the set of belief IDs the store returns. active is the honest column, because 33 of the 77 cases pass with an empty store.

active  42/43 = 0.9767     cases that need query-dependent retrieval
 total  72/77 = 0.9351     including cases any store passes

Three changes lifted this from 34/43 and 64/77. The result set is now sized from the names a query contains at every length, and only from beliefs the case's scope can see — the old rule forced top_k=1 below eight words and counted out-of-scope beliefs. Whole-word name matching replaced substring matching, so pipe no longer matches inside pipeline. A fuzzy query path then matches a mis