mnemebrain-lite 0.1.0a6

Give your AI a real brain - Agents today store text. MnemeBrain stores beliefs with evidence, confidence, provenance, and revision logic.

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

Primitive	Class	Description
Belief	Belief	A claim the agent currently holds, with truth state and confidence.
Evidence	Evidence	A piece of supporting or attacking evidence linked to a belief.
Truth State	TruthState	Belnap four-valued logic: TRUE, FALSE, BOTH, NEITHER.
Polarity	Polarity	Evidence relation: SUPPORTS or ATTACKS.
Confidence	engine.py	Log-odds fusion of evidence weights, mapped to [0, 1] via sigmoid.
Revision	BeliefMemory.revise()	Add new evidence and recompute truth state (AGM-style minimal change).

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

Operation	Description	Embeddings?
believe()	Store a belief with evidence. Merges duplicates via embedding similarity.	Yes
retract()	Invalidate evidence and recompute affected beliefs.	No
explain()	Return full justification chain — supporting, attacking, and expired evidence.	Yes
revise()	Add new evidence to an existing belief and recompute.	No

---

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