mubit-agno

Agno (v2) DB and toolkit integration backed by the MuBit memory engine.

Targets Agno v2's agno.db.base.BaseDb. (The pre-2.0 adapter implemented agno.memory.v2.db.base.MemoryDb, which was removed in Agno 2.0.)

Installation

pip install mubit-agno[agno]   # installs agno>=2.6,<3

Quick Start

DB — Persistent User Memory + Sessions

Use MubitAgnoDb as the db for an Agno agent. User memories persist to MuBit and sessions are mirrored as MuBit checkpoints:

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from mubit_agno import MubitAgnoDb

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=MubitAgnoDb(
        api_key="mbt_...",
        session_id="user-session-1",
        user_id="user-42",
    ),
    enable_user_memories=True,
)

agent.run("Remember that I prefer concise answers")
agent.run("What are my preferences?")  # Recalls from MuBit

MubitAgnoDb is a genuine BaseDb subclass: user-memory and session methods are MuBit-backed; the remaining BaseDb surfaces (metrics, evals, knowledge, culture, learnings, traces, spans) use lightweight local storage so the class is fully concrete.

Toolkit — Direct Memory Tools

Give agents LLM-callable tools for fine-grained memory control:

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from mubit_agno import MubitToolkit

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[MubitToolkit(api_key="mbt_...", session_id="research-run-1")],
)

# Tools: mubit_remember, mubit_recall, mubit_reflect, mubit_get_context,
# mubit_checkpoint, mubit_record_outcome, mubit_diagnose, mubit_memory_health.
# mubit_recall surfaces `citations` + `entry_ids` so the agent can close the
# loop with mubit_record_outcome(entry_ids=...).
agent.run("Store a lesson: always validate input before processing")
agent.run("What lessons have we learned?")

Convenience Wrapper — Full Integration

MubitAgnoMemory bundles both surfaces and adds MAS extensions:

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from mubit_agno import MubitAgnoMemory

mubit = MubitAgnoMemory(api_key="mbt_...", session_id="crew-run-1", user_id="user-42")

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    db=mubit.as_db(),
    tools=[mubit.as_toolkit()],
    enable_user_memories=True,
)

# MAS coordination
mubit.register_agent("researcher", role="researcher",
                     read_scopes=["fact", "lesson"], write_scopes=["trace", "lesson"])
mubit.checkpoint("Phase 1", "Research complete")

Closing the Attribution Loop (v0.7.0)

Recall, act, then credit the exact entries that helped — verified-in-production lessons get a ranking boost:

result = mubit.recall("deployment runbook")
entry_ids = mubit.extract_entry_ids(result, cited_only=True)  # only cited evidence
mubit.record_outcome(
    "success",
    entry_ids=entry_ids,
    verified_in_production=True,
    rationale="Followed the recalled runbook and the deploy passed",
)

# Per-step process rewards
mubit.record_step_outcome("validate-inputs", outcome="success")

Writes are idempotent: user-memory upserts thread both an upsert_key and an idempotency_key, so retried writes don't double-count reinforcement.

Extended Features

The MubitAgnoMemory wrapper provides full MAS capabilities:

• Recall: recall(query) — evidence + citations + entry_ids
• Context: get_context(query) — pre-assembled memory context
• Reflection: reflect() — extract lessons from evidence
• Lessons: lessons() / learned() / forget()
• Checkpoints: checkpoint(label, snapshot) — durable snapshots
• Outcomes: record_outcome(outcome, entry_ids=..., verified_in_production=...)
• Step Outcomes: record_step_outcome(step_id) — per-step rewards
• Strategies: surface_strategies() — pattern discovery
• Agent Registration: register_agent(id, role, scopes) — MAS setup
• Handoffs: handoff(from, to, content) — agent coordination
• Feedback: feedback(handoff_id, verdict) — async evaluation
• Archive: archive(content, kind) / dereference(ref_id)
• Diagnostics: diagnose(error) — failure analysis
• Health: memory_health() — quality assessment

Environment Variables

License

Apache-2.0