# Framework integrations (Coming soon)

Use Mirabase's tools, memory, and retrieval from the Vercel AI SDK, LangChain, LlamaIndex, the OpenAI Agents SDK, Mastra, and CrewAI.

> **Warning:** These integration packages are not published yet, and their names may change before they are. This page will give the install commands when they are published. Until then, use the [SDK](https://mirabase.io/developers/sdks.md) or [MCP](https://mirabase.io/developers/agents.md) directly.

Every integration offers the same five tools: `mirabase_search`, `mirabase_answer`, `mirabase_read_file`, `mirabase_write_file`, and `mirabase_list_files`. Citations carry the file path and version. Pass a client pinned with `spaceFor(userId)` (`space_for` in Python) to keep one Space per end user. The integrations build on SDK 0.3.0-rc.1 (0.3.0rc1 in Python).

- `mirabase_list_files` returns a file's size as `size_bytes`, in TypeScript as in Python. When the response has `pending_processing`, `mirabase_search` passes it on to the model.
- Conversation-backed message histories and sessions read the most recent 20 batches by default; change the number with `maxBatches` (`max_batches` in Python).
- `mirabaseAnswerModel` sends the 10 most recent turns, each cut to its first 4,000 characters; a question over 4,000 characters is cut to its end, with a warning on the call. The retrievers and tools likewise cut an overlong query, task, or question to its end.

| Framework | Language | Package (not published) | Components | Tested with |
| --- | --- | --- | --- | --- |
| Vercel AI SDK | TypeScript | `@mirabase/vercel-ai` | Tools; memory middleware; Mirabase's cited answer as a model | `ai` 7.0.173 |
| LangChain.js | TypeScript | `@mirabase/langchain` | Retriever, conversation-backed chat message history, document loader, tools | `@langchain/core` 1.4.1 |
| LangChain | Python | `mirabase-langchain` | Retriever, conversation-backed chat message history, document loader, tools | `langchain-core` 1.8.1 |
| LlamaIndex | Python | `mirabase-llamaindex` | Retriever, query engine with citations, reader | `llama-index-core` 0.14.26 |
| OpenAI Agents SDK | TypeScript | `@mirabase/openai-agents` | Tools, conversation-backed `Session` | `@openai/agents` 0.22.0 |
| OpenAI Agents SDK | Python | `mirabase-openai-agents` | Tools, conversation-backed session | `openai-agents` 0.24.0 |
| Mastra | TypeScript | `@mirabase/mastra` | Tools, memory processor | `@mastra/core` 1.83.0 |
| CrewAI | Python | `mirabase-crewai` | Tools, Mirabase-backed `Knowledge` | `crewai` 1.15.41 |

> **Note:** `model` in the examples stands for the model you use with that framework.

## Vercel AI SDK

`mirabaseTools` provides the five tools. `mirabaseMemory` is model middleware: before a call, it builds context from the last user message; after the call, it stores the turn as a conversation from which the service distills memories. If you do not use your own model, `mirabaseAnswerModel` wraps Mirabase's cited answer as a model.

```ts
import { Mirabase } from "@mirabase/sdk/developer";
import { mirabaseMemory, mirabaseTools } from "@mirabase/vercel-ai";
import { generateText, stepCountIs, wrapLanguageModel } from "ai";

const mb = await new Mirabase().spaceFor("user-42"); // one Space per end user
const { text } = await generateText({
  model: wrapLanguageModel({ model, middleware: mirabaseMemory({ client: mb, sessionId: "chat-1" }) }),
  tools: mirabaseTools({ client: mb }),
  stopWhen: stepCountIs(5),
  prompt: "What did we decide about the launch?",
});
```

## LangChain

`MirabaseRetriever` returns cited documents whose `metadata` contains the file path, version, and citation id. `MirabaseChatMessageHistory` stores message history as a Mirabase conversation. A document loader and the five tools are also included.

TypeScript:

```ts
import { Mirabase } from "@mirabase/sdk/developer";
import { MirabaseChatMessageHistory, MirabaseRetriever } from "@mirabase/langchain";

const mb = new Mirabase();
const docs = await new MirabaseRetriever({ client: mb, k: 5 }).invoke("When do we ship?");
console.log(docs[0]?.metadata.path, docs[0]?.metadata.citation_id);
const history = new MirabaseChatMessageHistory({ client: await mb.spaceFor("user-42"), sessionId: "chat-1" });
```

Python:

```python
from mirabase import Mirabase
from mirabase_langchain import MirabaseChatMessageHistory, MirabaseRetriever

mb = Mirabase()
docs = MirabaseRetriever(client=mb, k=5).invoke("When do we ship?")
print(docs[0].metadata["path"], docs[0].metadata["citation_id"])
history = MirabaseChatMessageHistory(mb.space_for("user-42"), "chat-1")
```

## LlamaIndex

`MirabaseQueryEngine` answers through Mirabase's answer endpoint, with the cited passages as `source_nodes`, and needs no model of your own. `MirabaseRetriever` plugs into a LlamaIndex query engine when your own model writes the answer.

```python
from mirabase import Mirabase
from mirabase_llamaindex import MirabaseQueryEngine, MirabaseRetriever

mb = Mirabase()
response = MirabaseQueryEngine(client=mb).query("When do we ship?")
print(response, [n.node.metadata["path"] for n in response.source_nodes])
nodes = MirabaseRetriever(mb, similarity_top_k=5).retrieve("launch owner")
```

## OpenAI Agents SDK

`mirabaseTools` (`mirabase_tools` in Python) gives the five tools with strict schemas. `MirabaseSession` stores each turn as a Mirabase conversation.

TypeScript:

```ts
import { Agent, run } from "@openai/agents";
import { Mirabase } from "@mirabase/sdk/developer";
import { MirabaseSession, mirabaseTools } from "@mirabase/openai-agents";

const mb = await new Mirabase().spaceFor("user-42");
const assistant = new Agent({ name: "Assistant", instructions: "Answer from the user's files.", tools: mirabaseTools({ client: mb }) });
const session = new MirabaseSession({ client: mb, sessionId: "chat-1" });
const result = await run(assistant, "What did we decide about the launch?", { session });
```

Python:

```python
from agents import Agent, Runner
from mirabase import Mirabase
from mirabase_openai_agents import MirabaseSession, mirabase_tools

mb = Mirabase().space_for("user-42")
assistant = Agent(name="Assistant", instructions="Answer from the user's files.", tools=mirabase_tools(mb))
result = Runner.run_sync(assistant, "What did we decide?", session=MirabaseSession(mb, "chat-1"))
```

## Mastra

`mirabaseMemory` is a processor: on input it adds the context Mirabase builds, and on output it stores the turn as a conversation. It works alongside Mastra's own thread memory.

```ts
import { Agent } from "@mastra/core/agent";
import { Mirabase } from "@mirabase/sdk/developer";
import { mirabaseMemory, mirabaseTools } from "@mirabase/mastra";

const mb = await new Mirabase().spaceFor("user-42");
const memory = mirabaseMemory({ client: mb, sessionId: "chat-1" });
const assistant = new Agent({ id: "assistant", name: "Assistant", instructions: "Be brief.", model,
  tools: mirabaseTools({ client: mb }), inputProcessors: [memory], outputProcessors: [memory] });
const { text } = await assistant.generate("What should I cook tonight?");
```

## CrewAI

`mirabase_knowledge` is a CrewAI `Knowledge` source backed by Mirabase search, requiring no local vector store or embedding model API key. `mirabase_tools` provides the five tools.

```python
from crewai import Agent, Crew, Task
from mirabase import Mirabase
from mirabase_crewai import mirabase_knowledge, mirabase_tools

mb = Mirabase()
planner = Agent(
    role="Planner",
    goal="Answer from the team's notes",
    backstory="Knows the release plan.",
    tools=mirabase_tools(mb, read_only=True),
    knowledge=mirabase_knowledge(mb, path="/notes"),
)
task = Task(description="When do we ship, and who owns it?", expected_output="A day and a name", agent=planner)
print(Crew(agents=[planner], tasks=[task]).kickoff())
```

## Next steps

- [SDK](https://mirabase.io/developers/sdks.md): the client the integrations build on.
- [Connect an Agent (MCP)](https://mirabase.io/developers/agents.md): reach the same tools over MCP without a framework.
- [Retrieval and context](https://mirabase.io/developers/retrieval.md): the retrieval endpoints the integrations call.
