SparkofSpike/Brain4Agent

What it does

Brain4Agent gives an agent a persistent memory of past sessions. Conversation turns are written to a single SQLite file, and searches return whole sessions ranked by BM25 rather than individual turns. Indexing combines character bigrams with dictionary words, so Chinese, Japanese, Korean and Vietnamese text can be searched without a segmentation model. The core retrieval path makes no LLM calls, requires no accelerator, and runs in single-digit milliseconds per query on the project's measurements.

Instead of a single confidence score, the store reports evidence: corpus_missing lists question words absent from the whole corpus, missing_terms lists question words absent from a given session, and coverage summarizes how much of the query a session matches. The caller decides whether that evidence justifies refusing to answer.

It is aimed at agent builders who want retrieval they can run entirely locally and inspect, and who work with CJK content. The library, a CLI, and an MCP server expose the same store.

Install and first run

Python 3.11 or newer is required. The recommended install adds jieba for dictionary-based tokenization:

pip install "Brain4Agent[precise]"

A zero-dependency install falls back to bigrams only. Both are published on PyPI.

Store and search an exchange from the CLI:

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

brain4agent search "中文查询为什么搜不到" -k 1

Existing history can be bulk-loaded from JSONL where each line has a session_id, role and content field:

brain4agent import conversations.jsonl

From Python, the same flow uses MemoryStore:

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)

For agent frameworks that speak MCP, register the server module and point it at a database path:

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

The MCP server exposes five tools: b4a_remember, b4a_recall, b4a_ask, b4a_session and b4a_stats. The retrieval tools work without a model; b4a_ask needs one and reports when none is configured. An agent skill package is also available. Windows command-line arguments containing non-ASCII text require PYTHONUTF8=1; the MCP server and CLI already pin their stdin/stdout to UTF-8.

Limits you should know about

Retrieval is session-level, so a session's best three turns are folded into one score; callers cannot rank individual turns directly. The project's own Chinese benchmark reaches hit@1 0.950 over 44 sessions, but that number collapses on corpora with hundreds of dense same-topic sessions: 300 added sessions bring hit@1 to 0.000. The documented mitigation is to read the top five results, weight corpus_missing over raw score, and tag memories at write time.

Several frontier capabilities are explicitly not built: temporal/graph memory with validity windows, cross-session synthesis, multi-retriever fusion, and schema validation on kind. Extraction on the write path exists but is off by default. Forgetting is recency-based (prune) plus weight signals, not model-driven consolidation. Retrieval matches an unknown English word one edit away from a corpus word, but this does not extend to CJK terms.

Abstention is a signal, not a gate: at its natural operating point corpus_missing keeps 87.5% of answerable questions, meaning 12.5% would be refused if acted on automatically. The optional hosted judge adds roughly 0.81 s per lookup and returns a third uncertain state.

Do not run two memory MCP servers in the same agent. The README records an agent querying the other server and reporting no memory while five relevant memories sat in Brain4Agent, so use one memory server per agent or unambiguous tool names.

Licensed under Apache-2.0.

HotRepo's take

Brain4Agent appeared on the Python new-project list on 11 November 2026, adding 17 stars during an observation window of about four and a half hours and reaching 117 stars with no forks. That is a small sample, so the ranking record supports only the fact that the project drew brief attention after launch, not a trend claim.

The more useful signal is in the repository itself: the README publishes its benchmark methodology, acknowledges where the Chinese hit@1 number breaks down, lists capabilities it has not built, and keeps a decision log with the measurements behind rejected designs. The PrecisionMemBench comparison against named third-party systems is attributed to that benchmark's own site, and the LoCoMo figures are explicitly session-retrieval rates rather than answer accuracy, so they are not directly comparable to published LoCoMo numbers. For a young project in a crowded memory-server field, that self-reporting makes it easier to judge fit before adopting it.