MuBit

https://docs.mubit.ai
Admin
MuBit enables continual learning for AI agents by storing experiences, extracting reusable lessons,...
Tokens:75,692
Snippets:641
Trust Score:4.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Python: First 5 Minutes Example

Source: https://docs.mubit.ai/getting-started

A minimal Python example to verify your MuBit setup. It remembers a fact and then recalls it using a session ID. Ensure MUBIT_API_KEY and MUBIT_ENDPOINT are set in your environment.

```python
from mubit import Client

client = Client()  # reads MUBIT_API_KEY and MUBIT_ENDPOINT from env

client.remember(session_id="hello-1", content="Mubit works.", intent="fact")
print(client.recall(session_id="hello-1", query="Does Mubit work?"))
```

--------------------------------

### Node.js: First 5 Minutes Example

Source: https://docs.mubit.ai/getting-started

A minimal Node.js example to verify your MuBit setup. It remembers a fact and then recalls it using a session ID. Ensure MUBIT_API_KEY and MUBIT_ENDPOINT are set in your environment.

```javascript
import { Client } from "@mubit-ai/sdk";

const client = new Client(); // reads MUBIT_API_KEY and MUBIT_ENDPOINT from env

await client.remember({ session_id: "hello-1", content: "Mubit works.", intent: "fact" });
console.log(await client.recall({ session_id: "hello-1", query: "Does Mubit work?" }));
```

--------------------------------

### Rust: First 5 Minutes Example

Source: https://docs.mubit.ai/getting-started

A minimal Rust example to verify your MuBit setup. It remembers a fact and then recalls it using a session ID. Ensure MUBIT_API_KEY and MUBIT_ENDPOINT are set in your environment via ClientConfig::from_env().

```rust
use mubit_sdk::{Client, ClientConfig, RecallOptions, RememberOptions};

let client = Client::connect(ClientConfig::from_env()?).await?;
let mut r = RememberOptions::new("Mubit works.");
r.run_id = Some("hello-1".into());
r.intent = Some("fact".into());
client.remember(r).await?;

let mut q = RecallOptions::new("Does Mubit work?");
q.run_id = Some("hello-1".into());
println!("{}", client.recall(q).await?);
```

--------------------------------

### Minimal Stateful Task Tree Implementation

Source: https://docs.mubit.ai/recipes/stateful-task-trees

This example demonstrates the basic setup for a stateful task tree. It includes registering an agent, adding goals, submitting actions, running a decision cycle, and saving a checkpoint. Use this as a starting point for building resilient planner orchestrations.

```python
from mubit import Client
import os

run_id = "claims:planner:claim-42"
client = Client(
    endpoint=os.getenv("MUBIT_ENDPOINT", "https://api.mubit.ai"),
    api_key=os.environ["MUBIT_API_KEY"],
    run_id=run_id,
    transport="http",
)

client.register_agent(session_id=run_id, agent_id="planner", role="planner")

parent_goal = client.add_goal({
    "run_id": run_id,
    "description": "Resolve claim-42 with a policy-safe decision",
    "priority": "critical",
})
client.add_goal({
    "run_id": run_id,
    "description": "Verify rental reimbursement coverage",
    "priority": "high",
    "parent_goal_id": parent_goal.get("id", ""),
})

client.submit_action({
    "run_id": run_id,
    "agent_id": "planner",
    "action_type": "retrieve",
    "action_json": '{"query":"collect coverage and fraud signals"}',
})
client.run_cycle({
    "run_id": run_id,
    "agent_id": "planner",
    "candidates": [{
        "action_type": "reason",
        "action_json": '{"prompt":"pick the safest next verification step"}',
        "score": 0.88,
        "rationale": "coverage confirmation should happen before settlement drafting",
    }],
})

client.checkpoint(
    session_id=run_id,
    agent_id="planner",
    label="after-goal-tree-build",
    context_snapshot="Planner built the first goal tree and recorded an initial decision cycle.",
)

goal_tree = client.get_goal_tree({"run_id": run_id})
actions = client.get_action_log({"run_id": run_id, "limit": 20})

print({
    "goal_nodes": len(goal_tree.get("goals", [])),
    "actions": len(actions.get("entries", [])),
})

```

```typescript
import { Client } from "@mubit-ai/sdk";

const runId = "claims:planner:claim-42";
const client = new Client({
  endpoint: process.env.MUBIT_ENDPOINT ?? "https://api.mubit.ai",
  api_key: process.env.MUBIT_API_KEY,
  run_id: runId,
  transport: "http",
});

await client.registerAgent({ session_id: runId, agent_id: "planner", role: "planner" });

const parentGoal = await client.addGoal({
  run_id: runId,
  description: "Resolve claim-42 with a policy-safe decision",
  priority: "critical",
});
await client.addGoal({
  run_id: runId,
  description: "Verify rental reimbursement coverage",
  priority: "high",
  parent_goal_id: parentGoal.id,
});

await client.submitAction({
  run_id: runId,
  agent_id: "planner",
  action_type: "retrieve",
  action_json: '{"query":"collect coverage and fraud signals"}',
});
await client.runCycle({
  run_id: runId,
  agent_id: "planner",
  candidates: [{
    action_type: "reason",
    action_json: '{"prompt":"pick the safest next verification step"}',
    score: 0.88,
    rationale: "coverage confirmation should happen before settlement drafting",
  }],
});

await client.checkpoint({
  session_id: runId,
  agent_id: "planner",
  label: "after-goal-tree-build",
  context_snapshot: "Planner built the first goal tree and recorded an initial decision cycle.",
});

const goalTree = await client.getGoalTree({ run_id: runId });
const actions = await client.getActionLog({ run_id: runId, limit: 20 });

console.log({
  goal_nodes: goalTree.goals?.length ?? 0,
  actions: actions.entries?.length ?? 0,
});

```

--------------------------------

### Node.js Quickstart for MuBit Learn

Source: https://docs.mubit.ai/getting-started

Initialize MuBit Learn in Node.js for automatic lesson injection and interaction capture. This example shows run-scoped learning with automatic reflection.

```javascript
import { learn } from "@mubit-ai/sdk/learn";

// One-time setup
const runManager = learn.init({ apiKey: process.env.MUBIT_API_KEY, agentId: "support-agent" });

// Run-scoped learning with automatic reflection
const result = await learn.withRun({ agentId: "support-agent" }, async () => {
  return client.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: "What update style does Taylor want?" }],
  });
});
```

--------------------------------

### Install MuBit SDK for Bun

Source: https://docs.mubit.ai/getting-started

Install the MuBit SDK for Bun using the 'bun add' command. This is for projects using the Bun runtime.

```bash
bun add @mubit-ai/sdk
```

--------------------------------

### Full Example: Travel Planner with SequentialAgent

Source: https://docs.mubit.ai/sdk/framework-integrations

This example demonstrates a SequentialAgent coordinating multiple LLM agents (flight finder, hotel finder, itinerary planner) using MuBit memory for state management and coordination. It requires setting up the MubitMemoryService and defining individual LLM agents with their respective tools and instructions.

```python
from google.adk.agents import LlmAgent, SequentialAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from mubit_adk import MubitMemoryService

mubit_memory = MubitMemoryService(endpoint="http://127.0.0.1:3000", api_key="mbt_...")

flight_finder = LlmAgent(
    name="flight_finder", model="gemini-3.1-flash-lite-preview",
    description="Finds the best flights",
    instruction="Search for flights and recommend the best option.",
    tools=[search_flights], output_key="flight_results",
)
hotel_finder = LlmAgent(
    name="hotel_finder", model="gemini-3.1-flash-lite-preview",
    description="Finds accommodations",
    instruction="Search for hotels and recommend the best option.",
    tools=[search_hotels], output_key="hotel_results",
)
itinerary_planner = LlmAgent(
    name="itinerary_planner", model="gemini-3.1-flash-lite-preview",
    description="Creates day-by-day itinerary",
    instruction="Combine flight and hotel info into a complete travel plan.",
    output_key="final_itinerary",
)

coordinator = SequentialAgent(
    name="travel_coordinator",
    sub_agents=[flight_finder, hotel_finder, itinerary_planner],
)

runner = Runner(
    agent=coordinator, app_name="travel",
    session_service=InMemorySessionService(),
    memory_service=mubit_memory,
)

# Run the pipeline, then record MuBit operations
# await mubit_memory.checkpoint(...)
# await mubit_memory.register_agent(...)
# await mubit_memory.record_outcome(...)
```

--------------------------------

### Helper-first retrieval examples

Source: https://docs.mubit.ai/sdk/retrieve-data

Examples demonstrating how to use the helper functions for retrieval in Python, Node.js/TypeScript, and Rust.

```APIDOC
## Python Example

### Description
This Python function `retrieve_helper` demonstrates how to use `client.recall()` to get an answer and `client.get_context()` to obtain a context block for a given question and session ID.

### Code
```python
def retrieve_helper(client, run_id: str, question: str):
    answer = client.recall(
        session_id=run_id,
        query=question,
        entry_types=["fact", "lesson", "rule"],
    )
    context = client.get_context(
        session_id=run_id,
        query=question,
        mode="summary",
        max_token_budget=400,
    )
    return answer, context
```
```

```APIDOC
## Node / TS Example

### Description
This TypeScript function `retrieveHelper` shows how to asynchronously retrieve an answer using `client.recall()` and a context block using `client.getContext()`.

### Code
```ts
export async function retrieveHelper(client, runId: string, question: string) {
  const answer = await client.recall({
    session_id: runId,
    query: question,
    entry_types: ["fact", "lesson", "rule"],
  });

  const context = await client.getContext({
    session_id: runId,
    query: question,
    mode: "summary",
    max_token_budget: 400,
  });

  return { answer, context };
}
```
```

```APIDOC
## Rust Example

### Description
This Rust function `retrieve_helper` demonstrates asynchronous retrieval of an answer and context using `client.recall()` and `client.get_context()`, with specified options for session ID, query, entry types, mode, and token budget.

### Code
```rust
use mubit_sdk::{GetContextOptions, RecallOptions};

pub async fn retrieve_helper(
    client: &mubit_sdk::Client,
    run_id: &str,
    question: &str,
) -> Result<(serde_json::Value, serde_json::Value), Box<dyn std::error::Error>> {
    let mut recall = RecallOptions::new(question);
    recall.run_id = Some(run_id.to_string());
    recall.entry_types = vec!["fact".to_string(), "lesson".to_string(), "rule".to_string()];
    let answer = client.recall(recall).await?;

    let mut context = GetContextOptions::default();
    context.run_id = Some(run_id.to_string());
    context.query = Some(question.to_string());
    context.mode = Some("summary".to_string());
    context.max_token_budget = Some(400);
    let context = client.get_context(context).await?;

    Ok((answer, context))
}
```
```

--------------------------------

### Minimal Implementation Example for Branching Memory

Source: https://docs.mubit.ai/recipes/branching-memory

This example demonstrates how to use checkpointing and session branching for what-if simulations. It shows creating a durable snapshot before branching, creating a temporary branch, and then snapshotting, loading, and dropping the branch.

```Python
from mubit import Client
import os

run_id = "claims:planner:claim-42"
client = Client(
    endpoint=os.getenv("MUBIT_ENDPOINT", "https://api.mubit.ai"),
    api_key=os.environ["MUBIT_API_KEY"],
    run_id=run_id,
    transport="http",
)

client.checkpoint(
    session_id=run_id,
    label="before-strategy-branch",
    context_snapshot="Planner has two settlement strategies to compare.",
    metadata={"stage": "what-if"},
)

base = client.core.create_session({})
branch = client.core.create_session({"parent_session_id": base["session_id"]})
branch_id = branch["session_id"]

snapshot = client.core.snapshot_session({"id": branch_id, "session_id": branch_id})
client.core.load_session({"session_id": branch_id, "snapshot": snapshot.get("snapshot")})
client.core.drop_session({"id": branch_id, "session_id": branch_id})
```

```Node / TS
import { Client } from "@mubit-ai/sdk";

const runId = "claims:planner:claim-42";
const client = new Client({
  endpoint: process.env.MUBIT_ENDPOINT ?? "https://api.mubit.ai",
  api_key: process.env.MUBIT_API_KEY,
  run_id: runId,
  transport: "http",
});

await client.checkpoint({
  session_id: runId,
  label: "before-strategy-branch",
  context_snapshot: "Planner has two settlement strategies to compare.",
  metadata: { stage: "what-if" },
});

const base = await client.core.createSession({});
const branch = await client.core.createSession({ parent_session_id: base.session_id });
const branchId = branch.session_id;

const snapshot = await client.core.snapshotSession({ id: branchId, session_id: branchId });
await client.core.loadSession({ session_id: branchId, snapshot: snapshot.snapshot });
await client.core.dropSession({ id: branchId, session_id: branchId });
```

--------------------------------

### Install MuBit SDK for npm

Source: https://docs.mubit.ai/getting-started

Install the MuBit SDK for Node.js using npm. This is the standard installation for npm projects.

```bash
npm install @mubit-ai/sdk
```

--------------------------------

### Python Quickstart for MuBit Learn

Source: https://docs.mubit.ai/getting-started

Set up MuBit Learn once to automatically inject lessons and capture interactions for all subsequent LLM calls. Use your LLM client as normal.

```python
import os
import mubit.learn
import openai

# One-time setup — all LLM calls now auto-inject lessons and auto-capture.
mubit.learn.init(api_key=os.environ["MUBIT_API_KEY"], agent_id="support-agent")

# Use your LLM client as normal. MuBit handles the rest.
response = openai.OpenAI().chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What update style does Taylor want?"}],
)
print(response.choices[0].message.content)
```

```python
# For run-scoped learning with automatic reflection on completion:
@mubit.learn.run(agent_id="support-agent", auto_reflect=True)
def handle_ticket(question):
    return openai.OpenAI().chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": question}],
    ).choices[0].message.content
```

--------------------------------

### Install MuBit SDK for Python

Source: https://docs.mubit.ai/getting-started

Install the MuBit SDK for Python using pip. Ensure you have Python and pip installed.

```bash
pip install mubit-sdk
```

--------------------------------

### Install MuBit SDK for pnpm

Source: https://docs.mubit.ai/getting-started

Install the MuBit SDK for pnpm using the 'pnpm add' command. This is for projects using the pnpm package manager.

```bash
pnpm add @mubit-ai/sdk
```

--------------------------------

### Install MuBit SDK for yarn

Source: https://docs.mubit.ai/getting-started

Install the MuBit SDK for yarn using the 'yarn add' command. This is for projects using the yarn package manager.

```bash
yarn add @mubit-ai/sdk
```

--------------------------------

### Rust Quickstart for MuBit Learn

Source: https://docs.mubit.ai/getting-started

Set up MuBit Learn in Rust to enrich messages with lessons before LLM calls and record interactions. Reflection is triggered on session end.

```rust
use mubit_sdk::learn::{LearnSession, LearnConfig};

let session = LearnSession::new(
    LearnConfig::from_env().agent_id("support-agent")
).await;

// Enrich messages with lessons before your LLM call
let enriched = session.enrich_messages(&messages).await;
// Make LLM call with enriched messages...
session.record("response", "gpt-4o", 1500.0).await;
session.end().await; // triggers reflection
```

--------------------------------

### Minimal Helper-First Example with MuBit

Source: https://docs.mubit.ai/sdk/how-mubit-works

Demonstrates the basic usage of MuBit's helper functions for remembering facts, recalling information, and retrieving context for an LLM call. Ensure the client is initialized before use.

```python
client.remember(
    session_id="support:acme:ticket-42",
    agent_id="support-agent",
    content="Customer Taylor prefers concise Friday updates.",
    intent="fact",
)

answer = client.recall(
    session_id="support:acme:ticket-42",
    query="What preference do we already know for Taylor?",
)

context = client.get_context(
    session_id="support:acme:ticket-42",
    query="Draft the next response.",
    mode="summary",
    max_token_budget=300,
)
```

--------------------------------

### Full Example: FAQ Bot with Multi-Session Learning

Source: https://docs.mubit.ai/sdk/framework-integrations

Implement a multi-session FAQ bot that leverages a knowledge base tool and learns across sessions. Session 2 benefits from lessons captured in Session 1.

```javascript
import { generateText, tool, wrapLanguageModel } from "ai";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";
import { mubitMemoryMiddleware } from "@mubit-ai/ai-sdk";

const lookupKnowledgeBase = tool({
  description: "Search the knowledge base for help articles",
  parameters: z.object({ query: z.string() }),
  execute: async ({ query }) => findBestArticle(query),
});

// Session 1: Answer FAQ questions
const model1 = wrapLanguageModel({
  model: openai("gpt-4o-mini"),
  middleware: mubitMemoryMiddleware({
    sessionId: "faq-session-1",
    agentId: "faq-bot",
    mubitClient,
  }),
});

for (const question of ["How do I reset my password?", "What are system requirements?"]) {
  const { text } = await generateText({
    model: model1,
    tools: { lookupKnowledgeBase },
    maxSteps: 3,
    prompt: question,
  });
  console.log(`Q: ${question}\nA: ${text}`);
}

// Ingest a lesson between sessions
await mubitClient.ingest({
  session_id: "faq-session-1",
  text: "Users who ask about password reset often also need 2FA help.",
  intent: "lesson",
});

// Session 2: New session benefits from memory
const model2 = wrapLanguageModel({
  model: openai("gpt-4o-mini"),
  middleware: mubitMemoryMiddleware({ sessionId: "faq-session-2", agentId: "faq-bot", mubitClient }),
});

const { text } = await generateText({
  model: model2,
  tools: { lookupKnowledgeBase },
  maxSteps: 3,
  prompt: "I'm having trouble logging in",
});
// Response should reference password/2FA from Session 1
```

--------------------------------

### MCP Tool Examples

Source: https://docs.mubit.ai/sdk/framework-integrations

Illustrative command sequences for common MuBit AI MAS (Multi-Agent System) extension tool flows using the MCP protocol.

```text
Checkpoint + reflection:     mubit_checkpoint → mubit_reflect → mubit_lessons
MAS coordination:            mubit_register_agent → mubit_handoff → mubit_feedback
Failure diagnosis:           mubit_diagnose → mubit_memory_health → mubit_recall
```

--------------------------------

### Implement Sessions and Branching Workflow

Source: https://docs.mubit.ai/sdk/sessions-and-branching

Use this example to implement checkpoints, create base and branched sessions, commit reviewed branches, and drop temporary ones. Ensure checkpoints are taken before creating scratch branches to preserve the main task path.

```Rust
use mubit_sdk::CheckpointOptions;
use serde_json::json;

let run_id = "claims:planner:claim-42";

let mut checkpoint = CheckpointOptions::new(
    "before-scratch-branch",
    "Planner is about to compare two claim settlement strategies.",
);
checkpoint.run_id = Some(run_id.to_string());
client.checkpoint(checkpoint).await?;

let base = client.core.create_session(json!({})).await?;
let branch = client.core.create_session(json!({
    "parent_session_id": base["session_id"]
})).await?;
let branch_id = branch["session_id"].as_str().unwrap();

client.core.commit_session(json!({
    "id": branch_id,
    "session_id": branch_id,
    "merge_strategy": "overwrite"
})).await?;
client.core.drop_session(json!({
    "id": branch_id,
    "session_id": branch_id
})).await?;
```

--------------------------------

### Implement Sessions and Branching Workflow

Source: https://docs.mubit.ai/sdk/sessions-and-branching

Use this example to implement checkpoints, create base and branched sessions, commit reviewed branches, and drop temporary ones. Ensure checkpoints are taken before creating scratch branches to preserve the main task path.

```Node / TS
const runId = "claims:planner:claim-42";

await client.checkpoint({
  session_id: runId,
  label: "before-scratch-branch",
  context_snapshot: "Planner is about to compare two claim settlement strategies.",
});

const base = await client.core.createSession({});
const branch = await client.core.createSession({ parent_session_id: base.session_id });

await client.core.commitSession({
  id: branch.session_id,
  session_id: branch.session_id,
  merge_strategy: "overwrite",
});
await client.core.dropSession({
  id: branch.session_id,
  session_id: branch.session_id,
});
```

--------------------------------

### Implement Sessions and Branching Workflow

Source: https://docs.mubit.ai/sdk/sessions-and-branching

Use this example to implement checkpoints, create base and branched sessions, commit reviewed branches, and drop temporary ones. Ensure checkpoints are taken before creating scratch branches to preserve the main task path.

```Python
run_id = "claims:planner:claim-42"

client.checkpoint(
    session_id=run_id,
    label="before-scratch-branch",
    context_snapshot="Planner is about to compare two claim settlement strategies.",
)

base = client.core.create_session({})
branch = client.core.create_session({"parent_session_id": base["session_id"]})
branch_id = branch["session_id"]

client.core.commit_session({"id": branch_id, "session_id": branch_id, "merge_strategy": "overwrite"})
client.core.drop_session({"id": branch_id, "session_id": branch_id})
```

--------------------------------

### Install MuBit SDK for Deno

Source: https://docs.mubit.ai/getting-started

Add the MuBit SDK for Deno using 'deno add npm:@mubit-ai/sdk'. This command integrates npm packages into Deno projects.

```bash
deno add npm:@mubit-ai/sdk
```

--------------------------------

### Environment Variable Setup

Source: https://docs.mubit.ai/sdk/authentication

Set up your MuBit API key as an environment variable for secure access. Ensure the key follows the `mbt_<instance>_<key_id>_<secret>` format.

```bash
MUBIT_API_KEY="mbt_<instance>_<key_id>_<secret>"
```

--------------------------------

### Core Semantic Subscription Event Examples

Source: https://docs.mubit.ai/sdk/pubsub-and-events

Illustrates the structure of events received from the core semantic subscription stream, including subscribed, node changes, and memory additions.

```JSON
{"type":"subscribed","subscription_id":42}
{"type":"node.inserted","node_id":7,"run_id":"r1","metadata":{"intent":"fact"},"created_at":1714000000,"updated_at":1714000000}
{"type":"node.deleted","node_id":7}
```

--------------------------------

### Record Step Outcomes in Python

Source: https://docs.mubit.ai/recipes/step-level-outcomes

Demonstrates how to record step outcomes for a multi-step agent run using the MuBit client in Python. Includes examples for successful and failed steps, and how to reflect with step outcomes.

```python
from mubit import Client
import os

run_id = "agent:planner:task-123"
client = Client(
    endpoint=os.getenv("MUBIT_ENDPOINT", "https://api.mubit.ai"),
    api_key=os.environ["MUBIT_API_KEY"],
    run_id=run_id,
    transport="http",
)

# Step 1: Planning
plan = call_llm("Break down the task into sub-steps")
client.record_step_outcome(
    step_id="step-1-planning",
    step_name="initial_planning",
    outcome="success",
    signal=0.8,
    rationale="Generated a clear 3-step plan with dependencies identified",
    directive_hint="Include sub-task dependencies explicitly in plans",
)

# Step 2: Tool call
tool_result = execute_tool("search_api", query="relevant docs")
client.record_step_outcome(
    step_id="step-2-search",
    step_name="search_api",
    outcome="failure",
    signal=-0.6,
    rationale="Search returned no results — query was too narrow",
    directive_hint="Use broader search terms before narrowing",
)

# Step 3: Recovery
recovery = call_llm("Retry with broader query")
client.record_step_outcome(
    step_id="step-3-recovery",
    step_name="search_retry",
    outcome="success",
    signal=0.9,
    rationale="Broader query found the target document",
)

# Reflect with step outcomes to produce step-attributed lessons
lessons = client.reflect(include_step_outcomes=True)

# Run-level outcome
client.record_outcome(
    outcome="success",
    signal=0.7,
    rationale="Task completed after one retry",
)
```

--------------------------------

### Initialize and Use Mubit Client in Python

Source: https://docs.mubit.ai/getting-started

Demonstrates initializing the Mubit client with API key and run ID, then using remember(), recall(), and get_context() methods. Ensure MUBIT_API_KEY environment variable is set.

```python
import os
from mubit import Client

run_id = "support:acme:ticket-42"
client = Client(
    api_key=os.environ["MUBIT_API_KEY"],
    run_id=run_id,
    transport=os.getenv("MUBIT_TRANSPORT", "auto"),
)

client.remember(
    session_id=run_id,
    agent_id="support-agent",
    content="Customer Taylor prefers concise Friday updates.",
    intent="fact",
    metadata={"customer": "taylor", "source": "quickstart"},
)

answer = client.recall(
    session_id=run_id,
    query="What update style does Taylor want?",
    entry_types=["fact", "lesson", "rule"],
)

context = client.get_context(
    session_id=run_id,
    query="Draft the next customer update.",
    mode="summary",
    max_token_budget=300,
)

print(answer.get("final_answer"))
print(context.get("section_summaries", []))
```

--------------------------------

### Initialize and Use Mubit Client in Rust

Source: https://docs.mubit.ai/getting-started

Illustrates setting up the Mubit client and utilizing remember(), recall(), and get_context() methods in Rust. Ensure MUBIT_API_KEY environment variable is set.

```rust
use mubit_sdk::{Client, ClientConfig, GetContextOptions, RecallOptions, RememberOptions};
use serde_json::json;
use std::env;

let run_id = "support:acme:ticket-42".to_string();
let config = ClientConfig::new("https://api.mubit.ai")
    .api_key(env::var("MUBIT_API_KEY")?)
    .run_id(&run_id);
let client = Client::connect(config).await?;

let mut remember = RememberOptions::new("Customer Taylor prefers concise Friday updates.");
remember.run_id = Some(run_id.clone());
remember.agent_id = Some("support-agent".to_string());
remember.intent = Some("fact".to_string());
remember.metadata = Some(json!({"customer":"taylor","source":"quickstart"}));
client.remember(remember).await?;

let mut recall = RecallOptions::new("What update style does Taylor want?");
recall.run_id = Some(run_id.clone());
recall.entry_types = vec!["fact".to_string(), "lesson".to_string(), "rule".to_string()];
let answer = client.recall(recall).await?;

let mut context = GetContextOptions::default();
context.run_id = Some(run_id.clone());
context.query = Some("Draft the next customer update.".to_string());
context.mode = Some("summary".to_string());
context.max_token_budget = Some(300);
let context = client.get_context(context).await?;

println!("{}", answer["final_answer"]);
println!("{}", context["section_summaries"]);
```

--------------------------------

### Get Ingest Job Status

Source: https://docs.mubit.ai/api-reference/control-http

Retrieves the status of an ingest job.

```APIDOC
## GET /v2/control/ingest/jobs/:job_id

### Description
Get the status of an ingest job.

### Method
GET

### Endpoint
/v2/control/ingest/jobs/:job_id

### Parameters
#### Path Parameters
- **job_id** (string) - Required - Job identifier

### Response
#### Success Response (200)
- **job_id** (string) - Job identifier
- **status** (string) - One of `pending`, `processing`, `completed`, `failed`
- **items_total** (int) - Total items in the job
- **items_processed** (int) - Items processed so far
- **created_at** (string) - ISO timestamp
- **completed_at** (string) - ISO timestamp (if completed)

### Response Example
{
  "job_id": "string",
  "status": "string",
  "items_total": int,
  "items_processed": int,
  "created_at": "string",
  "completed_at": "string"
}
```

--------------------------------

### Learn module initialization and usage (Python)

Source: https://docs.mubit.ai/sdk/sdk-methods

Initialize the learn module with your API key and agent ID. All subsequent LLM calls will automatically inject lessons and ingest interactions. The `@mubit.learn.run` decorator can be used to automatically manage runs and reflections.

```APIDOC
## Learn module (closed-loop)

Before each LLM call, the learn module retrieves relevant lessons from MuBit and injects them into the system message. After the call, the interaction is ingested automatically. On run end, reflection extracts new lessons.

### Python Example

```python theme={null}
import mubit.learn

mubit.learn.init(api_key="mbt_...", agent_id="my-agent")

# All OpenAI/Anthropic/LiteLLM calls now auto-inject lessons + auto-ingest.

@mubit.learn.run(agent_id="planner", auto_reflect=True)
def plan_task(task):
    return openai.OpenAI().chat.completions.create(
        model="gpt-4o", messages=[{"role": "user", "content": task}],
    ).choices[0].message.content
```
```

--------------------------------

### Get per-run ingest statistics

Source: https://docs.mubit.ai/api-reference/control-http

Retrieves statistics related to data ingestion for a specific run.

```APIDOC
## POST /v2/control/ingest/stats

### Description
Gets per-run ingest statistics.

### Method
POST

### Endpoint
/v2/control/ingest/stats
```

--------------------------------

### Get storage statistics

Source: https://docs.mubit.ai/api-reference/core-direct-lanes

Retrieves statistics about the RocksDB storage, including size, keys, and compaction information.

```APIDOC
## GET /v2/core/storage/stats

### Description
RocksDB storage statistics (size, keys, compaction).

### Method
GET

### Endpoint
/v2/core/storage/stats
```

--------------------------------

### GET /metrics

Source: https://docs.mubit.ai/api-reference/control-http

Prometheus scrape endpoint. Exposes operational metrics for monitoring systems like Prometheus and Grafana.

```APIDOC
## GET /metrics

### Description
Prometheus scrape endpoint. Exposes operational metrics for monitoring systems like Prometheus and Grafana.

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
- **body**: (string) - Prometheus-formatted metrics
```

--------------------------------

### Full Support Agent Workflow (Rust)

Source: https://docs.mubit.ai/sdk/full-support-agent

This Rust snippet demonstrates a full support agent implementation using the Mubit SDK. It covers agent registration, remembering information, context retrieval, checkpointing, handoffs, and feedback mechanisms.

```rust
use mubit_sdk::{
        CheckpointOptions,
        Client,
        ClientConfig,
        FeedbackOptions,
        GetContextOptions,
        HandoffOptions,
        RecordOutcomeOptions,
        ReflectOptions,
        RegisterAgentOptions,
        RememberOptions,
        SurfaceStrategiesOptions,
    };
    use serde_json::json;
    use std::env;

    let run_id = "support:acme:ticket-42".to_string();
    let config = ClientConfig::new("https://api.mubit.ai")
        .api_key(env::var("MUBIT_API_KEY")?)
        .run_id(&run_id);
    let client = Client::connect(config).await?;

    let mut support = RegisterAgentOptions::new("support");
    support.run_id = Some(run_id.clone());
    support.role = "support".to_string();
    client.register_agent(support).await?;

    let mut billing = RegisterAgentOptions::new("billing");
    billing.run_id = Some(run_id.clone());
    billing.role = "billing".to_string();
    client.register_agent(billing).await?;

    let mut support_fact = RememberOptions::new(
        "Customer Taylor wants concise Friday updates and is asking about invoice INV-7781.",
    );
    support_fact.run_id = Some(run_id.clone());
    support_fact.agent_id = Some("support".to_string());
    support_fact.intent = Some("fact".to_string());
    support_fact.metadata = Some(json!({"customer":"taylor","ticket":42}));
    client.remember(support_fact).await?;

    let mut billing_trace = RememberOptions::new(
        "Invoice INV-7781 has a stale tax table mismatch on line item 4.",
    );
    billing_trace.run_id = Some(run_id.clone());
    billing_trace.agent_id = Some("billing".to_string());
    billing_trace.intent = Some("trace".to_string());
    billing_trace.metadata = Some(json!({"invoice":"INV-7781","source":"billing-review"}));
    client.remember(billing_trace).await?;

    let mut context = GetContextOptions::default();
    context.run_id = Some(run_id.clone());
    context.query = Some("Draft the next customer-safe update with the billing root cause and next step.".to_string());
    context.mode = Some("full".to_string());
    context.max_token_budget = Some(800);
    let context = client.get_context(context).await?;

    let mut checkpoint = CheckpointOptions::new(
        "pre-response-compaction",
        context.get("context_block").and_then(|v| v.as_str()).unwrap_or(""),
    );
    checkpoint.run_id = Some(run_id.clone());
    checkpoint.agent_id = Some("support".to_string());
    let checkpoint = client.checkpoint(checkpoint).await?;

    let mut handoff = HandoffOptions::new(
        "ticket-42-billing-review",
        "support",
        "billing",
        "Confirm the billing root cause for invoice INV-7781 before we reply.",
    );
    handoff.run_id = Some(run_id.clone());
    handoff.requested_action = "review".to_string();
    let handoff = client.handoff(handoff).await?;
    let handoff_id = handoff.get("handoff_id").and_then(|v| v.as_str()).unwrap().to_string();

    let mut feedback = FeedbackOptions::new(handoff_id.clone(), "approve");
    feedback.run_id = Some(run_id.clone());
    feedback.from_agent_id = Some("billing".to_string());
    feedback.comments = "Root cause confirmed: stale tax table mismatch on line item 4.".to_string();
    let feedback = client.feedback(feedback).await?;

    let mut reflect = ReflectOptions::default();
    reflect.run_id = Some(run_id.clone());
    let reflection = client.reflect(reflect).await?;
    let lessons = client.list_lessons(json!({"run_id": run_id, "limit": 20})).await?;
    if let Some(lesson_id) = lessons["lessons"][0]["id"].as_str() {
        let mut outcome = RecordOutcomeOptions::new(lesson_id, "success");
```

--------------------------------

### Prompt Lifecycle RPCs

Source: https://docs.mubit.ai/api-reference/control-grpc

RPCs for managing the lifecycle of prompts, including setting, getting, versioning, activating, and optimizing.

```APIDOC
## SetPrompt
### Description
Sets a prompt.
### Method
RPC
### Endpoint
N/A (gRPC)
### Parameters
N/A
### Request Example
N/A
### Response
#### Success Response
N/A
#### Response Example
N/A

## GetPrompt
### Description
Retrieves a prompt.
### Method
RPC
### Endpoint
N/A (gRPC)
### Parameters
N/A
### Request Example
N/A
### Response
#### Success Response
N/A
#### Response Example
N/A

## ListPromptVersions
### Description
Lists all versions of a prompt.
### Method
RPC
### Endpoint
N/A (gRPC)
### Parameters
N/A
### Request Example
N/A
### Response
#### Success Response
N/A
#### Response Example
N/A

## ActivatePromptVersion
### Description
Activates a specific version of a prompt.
### Method
RPC
### Endpoint
N/A (gRPC)
### Parameters
N/A
### Request Example
N/A
### Response
#### Success Response
N/A
#### Response Example
N/A

## OptimizePrompt
### Description
Optimizes a prompt, potentially creating a new version.
### Method
RPC
### Endpoint
N/A (gRPC)
### Parameters
- LlmOverride (object) - Optional - Allows specifying LLM parameters for optimization.
### Request Example
N/A
### Response
#### Success Response
N/A
#### Response Example
N/A

## GetPromptDiff
### Description
Compares two versions of a prompt and returns the differences.
### Method
RPC
### Endpoint
N/A (gRPC)
### Parameters
N/A
### Request Example
N/A
### Response
#### Success Response
- diff_text (string) - The unified diff text comparing the two prompt versions.
#### Response Example
N/A
```

--------------------------------

### Get Prompt Diff

Source: https://docs.mubit.ai/recipes/prompt-optimization

Fetches the difference between the active and a candidate prompt version. The output is in a unified diff format.

```python
active = client.get_prompt(agent_id="triage")
diff = client.get_prompt_diff(
    agent_id="triage",
    version_a_id=active["prompt"]["version_id"],
    version_b_id=candidate["version_id"],
)
print(diff["diff_text"])   # unified diff format
```

--------------------------------

### Install MuBit SDK for Rust

Source: https://docs.mubit.ai/getting-started

Add the MuBit SDK for Rust using Cargo. This command integrates the SDK into your Rust project.

```bash
cargo add mubit-sdk
```

--------------------------------

### Prompt Versioning and Optimization

Source: https://docs.mubit.ai/api-reference/control-http

Endpoints for managing prompt versions, including setting, getting, listing, activating, optimizing, and diffing prompts.

```APIDOC
## POST /v2/control/prompt/set

### Description
Write a new prompt version. If `activate=true` is set, this version is immediately promoted to active.

### Method
POST

### Endpoint
/v2/control/prompt/set

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent.
- **prompt** (string) - Required - The new prompt content.
- **activate** (boolean) - Optional - If true, promotes the new version to active immediately.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **version_id** (string) - The ID of the newly created prompt version.

## POST /v2/control/prompt/get

### Description
Get the currently active prompt version for an agent.

### Method
POST

### Endpoint
/v2/control/prompt/get

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **active_version_id** (string) - The ID of the active prompt version.
- **prompt** (string) - The content of the active prompt.

## POST /v2/control/prompt/versions

### Description
List all prompt versions for a given agent.

### Method
POST

### Endpoint
/v2/control/prompt/versions

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **versions** (array) - A list of prompt versions, each with `version_id`, `status`, and `source`.

## POST /v2/control/prompt/activate

### Description
Promote a candidate prompt version to active.

### Method
POST

### Endpoint
/v2/control/prompt/activate

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent.
- **version_id** (string) - Required - The ID of the candidate version to activate.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

## POST /v2/control/prompt/optimize

### Description
Generate a new candidate prompt version using LLM-powered optimization based on recent outcomes.

### Method
POST

### Endpoint
/v2/control/prompt/optimize

### Parameters
#### Request Body
- **agent_id** (string) - Required - Agent whose prompt is being optimized.
- **project_id** (string) - Required - Containing project.
- **llm_override** (object) - Optional - LLM configuration override. Example: `{ "provider": "openai", "model": "gpt-4", "temperature": 0.7, "max_tokens": 1000, "timeout_ms": 5000 }`.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the optimization was successful.
- **candidate** (object) - Details of the generated candidate prompt version.
- **optimization_summary** (string) - A summary of the optimization process.
- **confidence** (number) - Confidence score for the optimization.
- **activated** (boolean) - Indicates if the candidate was automatically activated.

## POST /v2/control/prompt/diff

### Description
Compare two prompt versions and return the differences.

### Method
POST

### Endpoint
/v2/control/prompt/diff

### Parameters
#### Request Body
- **agent_id** (string) - Required - The ID of the agent.
- **version1_id** (string) - Required - The ID of the first prompt version.
- **version2_id** (string) - Required - The ID of the second prompt version.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the diff operation was successful.
- **diff_text** (string) - The unified diff output.
```

--------------------------------

### Retrieve Context Snapshot

Source: https://docs.mubit.ai/sdk/sdk-methods

Get a complete snapshot of a run's state, including its working memory, attention state, and active goals.

```python
snapshot = client.get_run_snapshot(run_id="my-run")
```

```javascript
const snapshot = await client.contextSnapshot({ runId: "my-run" });
```

--------------------------------

### Full Support Agent Workflow (JavaScript)

Source: https://docs.mubit.ai/sdk/full-support-agent

This snippet illustrates a comprehensive workflow for a support agent using the Mubit SDK. It includes registering agents, remembering facts, retrieving context, checkpointing, handling handoffs, and reflecting on lessons.

```javascript
const session_id: RUN_ID,
      handoff_id: handoff.handoff_id,
      from_agent_id: "billing",
      verdict: "approve",
      comments: "Root cause confirmed: stale tax table mismatch on line item 4.",
    });

    const reflection = await client.reflect({ session_id: RUN_ID });
    // lesson_id is populated inline on each ReflectLesson so callers don't need
    // a round-trip through client.lessons() which can race with index
    // propagation immediately after a write.
    const lessonId = reflection.lessons?.find((l) => l.lesson_id)?.lesson_id;
    if (lessonId) {
      await client.recordOutcome({
        session_id: RUN_ID,
        agent_id: "support",
        reference_id: lessonId,
        outcome: "success",
        signal: 0.75,
        rationale: "The support response used the stored customer preference and the validated billing root cause.",
      });
    }

    const strategies = await client.surfaceStrategies({
      session_id: RUN_ID,
      lesson_types: ["success", "failure"],
      max_strategies: 5,
    });

    console.log({
      checkpoint_id: checkpoint.checkpoint_id,
      handoff_id: handoff.handoff_id,
      feedback_id: feedback.feedback_id,
      lessons_stored: reflection.lessons_stored,
      strategy_count: strategies.strategies?.length ?? 0,
    });
```

--------------------------------

### Minimal Event-Driven Agent Implementation (Python)

Source: https://docs.mubit.ai/recipes/event-driven-agents

This Python snippet demonstrates how to set up a client, subscribe to control events, and perform memory operations like remembering and checkpointing. It's useful for reacting to agent events in real-time.

```python
from mubit import Client
import os

run_id = "claims:planner:claim-42"
client = Client(
    endpoint=os.getenv("MUBIT_ENDPOINT", "https://api.mubit.ai"),
    api_key=os.environ["MUBIT_API_KEY"],
    run_id=run_id,
    transport="http",
)

stream = client.subscribe({"run_id": run_id})

client.remember(
    session_id=run_id,
    agent_id="planner",
    content="A new adjuster note arrived for claim-42.",
    intent="trace",
)
client.checkpoint(
    session_id=run_id,
    agent_id="planner",
    label="before-adjuster-review",
    context_snapshot="Planner stored the adjuster note and is waiting for review.",
)

for event in stream:
    if event:
        print(event)
        break
```

--------------------------------

### Get Ingest Run Statistics

Source: https://docs.mubit.ai/sdk/sdk-methods

Retrieves statistics for a specific run of an ingest job. This provides detailed counters and metrics for a particular ingestion process.

```APIDOC
## get_run_ingest_stats

### Description
Retrieves statistics for a specific run of an ingest job. This provides detailed counters and metrics for a particular ingestion process.

### Method
`client.get_run_ingest_stats(job_id: str, run_id: str) -> dict`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
run_stats = client.get_run_ingest_stats(job_id="ingest_job_123", run_id="run_456")
```

### Response
#### Success Response (200)
- **run_stats** (dict) - A dictionary containing the statistics for the ingest run.

#### Response Example
```json
{
  "example": {
    "run_id": "run_456",
    "records_processed": 1000,
    "errors": 5,
    "duration_seconds": 60
  }
}
```
```
Tokens:
Raw