MnemeBrain Lite

MnemeBrain Lite is the open-source belief-state engine for AI agents. Instead of storing text memories, it maintains a belief graph with evidence, provenance, and confidence. Beliefs use Belnap four-valued truth states (TRUE / FALSE / BOTH / NEITHER) and update via evidence-driven revision. Evidence is tracked with SUPPORTS / ATTACKS polarity and scored using log-odds confidence.

Most agent memory systems cannot represent contradictions; MnemeBrain Lite treats contradiction as a first-class state.

MnemeBrain is to agent beliefs what a database is to application state.

⭐ Building AI agents? Run the BMB benchmark on your memory stack.

pip install mnemebrain-benchmark
bmb run

No API keys. No LLM calls. See how your system handles contradictions, belief revision, and temporal decay — in 60 seconds.

Core Primitives

Project Structure

MnemeBrain has two layers:

• mnemebrain-lite (this repo) — Open-source core belief memory engine providing belief storage, evidence graphs, Belnap-style truth states, belief revision primitives, temporal decay, and semantic search.
• MnemeBrain Core (private research repo) — Extended cognitive architecture used in the MnemeBrain research system, including consolidation daemons, advanced retrieval (HippoRAG-style), pattern separation, and long-term memory consolidation mechanisms.

         ┌─────────────────────────┐
         │    Agent / LLM Layer    │
         └────────────┬────────────┘
                      │
         ┌────────────▼────────────┐
         │        MnemeBrain       │
         │   (private research)    │
         │   consolidation engine  │
         │   advanced retrieval    │
         │   pattern separation    │
         └────────────┬────────────┘
                      │
         ┌────────────▼────────────┐
         │    mnemebrain-lite      │
         │   open-source belief    │
         │   memory engine         │
         │                         │
         │ evidence · truth ·      │
         │ revision · search       │
         └─────────────────────────┘

The lite engine is fully usable on its own and powers the public MnemeBrain benchmark suite.

Why This Exists

Most AI agent memory systems store facts. But agents don't reason about facts — they reason about beliefs.

LLM memory systems retrieve information, but they rarely maintain beliefs.

User: "I'm vegetarian"
[later]
User: "I ate steak yesterday"

A RAG system either silently overwrites the first statement — or returns both without acknowledging the conflict. It cannot represent contradictions.

MnemeBrain is a belief memory engine that tracks contradiction, uncertainty, and revision instead of overwriting information. It borrows ideas from truth maintenance systems and belief revision research, but packages them into a developer-friendly memory engine for LLM agents.

Quick Start

pip install mnemebrain-lite                # core only (no embeddings)
pip install mnemebrain-lite[embeddings]    # + local sentence-transformers
pip install mnemebrain-lite[openai]        # + OpenAI embeddings (set OPENAI_API_KEY)
pip install mnemebrain-lite[all]           # everything

from mnemebrain_core.memory import BeliefMemory
from mnemebrain_core.providers.base import EvidenceInput

memory = BeliefMemory(db_path="./my_data")

# Store a belief
belief = memory.believe(
    claim="user is vegetarian",
    evidence=[EvidenceInput(
        source_ref="msg_12",
        content="They said no meat please",
        polarity="supports",
        weight=0.8,
        reliability=0.9,
    )]
)

# Introduce conflicting evidence — belief becomes BOTH (contradiction)
memory.revise(
    belief_id=belief.id,
    new_evidence=EvidenceInput(
        source_ref="msg_47",
        content="User ordered steak",
        polarity="attacks",
        weight=0.9,
        reliability=0.95,
    )
)

# Explain the contradiction
result = memory.explain(claim="user is vegetarian")
# → truth_state=BOTH, supporting_count=1, attacking_count=1

# Full install (Linux / Apple Silicon)
uv sync --extra dev --extra embeddings

# OpenAI embeddings (any platform, requires OPENAI_API_KEY)
uv sync --extra dev --extra openai

# Without embeddings (Intel Mac — torch 2.3+ has no x86_64 wheels)
uv sync --extra dev

# Run tests
uv run pytest tests/ -v

# Start API server
uv run python -m mnemebrain_core
# Default DB_PATH: ./mnemebrain_data
# Listens on 0.0.0.0:8000

Intel Mac note: sentence-transformers requires PyTorch, which no longer ships x86_64 macOS wheels (torch 2.3+). Use mnemebrain-lite[openai] instead — it works on any platform. Without any embedding provider, /believe and /explain return 501 Not Implemented. All other endpoints work.

Core Operations

Documentation

Detailed documentation is available in the /docs folder:

• Architecture
• REST API
• Benchmark
• Design notes

Tech Stack

Python 3.12+, uv, FastAPI, Kuzu, Pydantic v2, pytest, sentence-transformers or OpenAI embeddings (optional)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT