MnemeBrain Python SDK

Python client for MnemeBrain — biological belief memory for LLM agents.

Beliefs carry evidence, confidence, provenance, and revision logic. Unlike flat key-value memory, MnemeBrain can explain, retract, and revise what it knows.

Install

pip install mnemebrain

Requires: Python 3.10+ and a running MnemeBrain backend.

Quick Start

Brain (high-level API)

The Brain class provides a simple interface for experiments and agent integration:

from mnemebrain import Brain

brain = Brain(agent_id="my-agent", base_url="http://localhost:8000")

# Store a belief with evidence
brain.believe(
    claim="user is vegetarian",
    evidence=["msg_12"],
    confidence=0.9,
)

# Query beliefs semantically
result = brain.ask("Is the user vegetarian?")
for belief in result.retrieved_beliefs:
    print(f"{belief.claim} (confidence={belief.confidence:.2f})")

MnemeBrainClient (low-level API)

For full control over the REST API:

from mnemebrain import MnemeBrainClient, EvidenceInput

with MnemeBrainClient(base_url="http://localhost:8000") as client:
    # Store a belief with detailed evidence
    result = client.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,
        )],
        belief_type="preference",
        tags=["dietary"],
    )
    print(result.truth_state)  # "true"
    print(result.confidence)   # 0.65

    # Explain a belief
    explanation = client.explain("user is vegetarian")
    if explanation:
        print(f"Supporting: {len(explanation.supporting)}")
        print(f"Attacking: {len(explanation.attacking)}")

    # Search beliefs
    results = client.search(query="dietary preferences", limit=5)
    for hit in results.results:
        print(f"{hit.claim} (sim={hit.similarity:.2f})")

    # List beliefs with filters
    page = client.list_beliefs(truth_state="true", belief_type="preference", limit=20)
    print(f"Total: {page.total}")

    # Revise with new evidence
    client.revise(
        belief_id=result.id,
        evidence=EvidenceInput(
            source_ref="msg_50",
            content="confirmed vegetarian",
            polarity="supports",
            weight=0.9,
            reliability=0.95,
        ),
    )

    # Retract evidence
    client.retract(evidence_id="<uuid>")

WorkingMemoryFrame (multi-step reasoning)

Ephemeral context buffer for complex reasoning tasks:

with MnemeBrainClient(base_url="http://localhost:8000") as client:
    # Open a frame with a reasoning query
    frame = client.frame_open(
        query="should we refactor auth?",
        preload_claims=["auth uses JWT"],
        ttl_seconds=600,
    )

    # Add more beliefs as reasoning progresses
    client.frame_add(frame.frame_id, "JWT tokens expire after 1 hour")

    # Use the scratchpad for intermediate reasoning
    client.frame_scratchpad(frame.frame_id, "step_1", "JWT is well established")

    # Get full context at any point
    ctx = client.frame_context(frame.frame_id)
    print(f"Beliefs: {len(ctx.beliefs)}, Steps: {ctx.step_count}")

    # Commit new beliefs back to the graph
    client.frame_commit(
        frame.frame_id,
        new_beliefs=[{"claim": "auth refactor not needed", "evidence": [], "belief_type": "inference"}],
    )

    # Or close without committing
    # client.frame_close(frame.frame_id)

API Reference

Brain

MnemeBrainClient

Models

Enums

Full documentation: docs/api-reference.md

Proof the Claim: 7B + MnemeBrain vs 70B

The examples/proof_the_claim/ directory contains a complete experiment demonstrating that a 7B model with MnemeBrain can outperform a 70B model on knowledge-intensive tasks.

# 1. Start the MnemeBrain backend
cd mnemebrain-lite && uv run python -m mnemebrain_core

# 2. Download data
pip install mnemebrain[experiment]
cd examples/proof_the_claim
python 1_download_data.py

# 3. Load knowledge into MnemeBrain
python 2_load_brain.py

# 4. Run the 3-condition evaluation
ollama pull mistral
ollama pull llama3.1:70b  # or set USE_GROQ=1 GROQ_API_KEY=...
python 3_evaluate.py

Development

git clone git@github.com:mnemebrain/mnemebrain-sdk.git
cd mnemebrain-sdk
uv sync --extra dev
uv run pytest tests/ -v --cov=mnemebrain --cov-fail-under=100
uv run ruff check src/ tests/

See CONTRIBUTING.md for full guidelines.

License

MIT