# mubit-agno

Agno memory and toolkit integration backed by the [MuBit](https://mubit.ai) memory engine.

## Installation

```bash
pip install mubit-agno[agno]
```

## Quick Start

### Memory DB — Persistent Agent Memory

Use `MubitMemoryDb` as the database backend for Agno's built-in memory system:

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.memory.v2.memory import Memory
from mubit_agno import MubitMemoryDb

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

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

### Toolkit — Direct Memory Tools

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

```python
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",
    )],
)

# Agent can now call mubit_remember, mubit_recall, mubit_reflect,
# mubit_get_context, mubit_checkpoint, mubit_diagnose, mubit_memory_health
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:

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.memory.v2.memory import Memory
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"),
    memory=Memory(db=mubit.as_memory_db()),
    tools=[mubit.as_toolkit()],
)

# MAS coordination
mubit.register_agent("researcher", role="researcher",
                      read_scopes=["fact", "lesson"],
                      write_scopes=["trace", "lesson"])
mubit.checkpoint("Phase 1", "Research complete")
mubit.record_outcome("task-1", "success", rationale="All sources verified")
strategies = mubit.surface_strategies()
```

## Extended Features

The `MubitAgnoMemory` wrapper provides full MAS capabilities:

- **Context**: `get_context(query)` — pre-assembled memory context
- **Reflection**: `reflect()` — extract lessons from evidence
- **Lessons**: `lessons()` — list and filter learned lessons
- **Checkpoints**: `checkpoint(label, snapshot)` — durable snapshots
- **Outcomes**: `record_outcome(ref, outcome)` — RL-style feedback
- **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)` — exact reference storage
- **Dereference**: `dereference(ref_id)` — fetch archived content
- **Diagnostics**: `diagnose(error)` — failure analysis
- **Health**: `memory_health()` — quality assessment

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MUBIT_ENDPOINT` | MuBit server URL | `http://127.0.0.1:3000` |
| `MUBIT_API_KEY` | MuBit API key | (empty for local dev) |

## License

Apache-2.0
