> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bossamemory.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Integration Guide

> Build AI agents with Bossa. CLI and MCP examples, tool usage patterns.

# Agent Integration Guide

This guide is for **AI agents** and **developers** building agents that need long-term memory. Bossa gives your agents a persistent filesystem to store and retrieve context across sessions—as simple as files, as powerful as Postgres. Use the managed service so your agents get persistent, searchable storage without running infrastructure.

**Base URL:** `https://bossamemory.com`\
**MCP endpoint:** `https://bossamemory.com/mcp`

***

## Quick Start for Agents

1. **Get an API key** — Install the CLI (`pip install bossa-memory`), sign up, create a workspace, create a key. See [Getting Started](GETTING_STARTED).

2. **Add Bossa to your agent config** — Run `bossa init` to add Bossa usage instructions to AGENTS.md or CLAUDE.md. Your agent will know the commands, flags, and exit codes. Use `bossa init --path ./AGENTS.md --yes` for non-interactive setup.

3. **Choose your interface:**
   * **CLI** — If your agent runs tools as subprocesses (CLI-based harnesses, beads), use `bossa files ls`, `read`, `write`, `grep`, `glob`, `edit`, `delete`. Set `BOSSA_CLI_JSON=1` for JSON output.
   * **MCP** — If your harness supports MCP (LangChain, Claude, Cursor), connect to `https://bossamemory.com/mcp` with headers `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY`.

4. **Use the tools** — Both interfaces expose the same operations: `ls`, `read`/`read_file`, `write`/`write_file`, `grep`, `glob`/`glob_search`, `edit`/`edit_file`, `delete`/`delete_file`.

***

## CLI Example (agent subprocess)

When your agent executes tools as subprocesses:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export BOSSA_API_KEY=your-api-key
export BOSSA_CLI_JSON=1

# Agent discovers context
bossa files ls /
bossa files glob "*.md" --path /memory
bossa files read /memory/summary.md

# Agent writes memory
echo "# Session notes\n\n..." | bossa files write /memory/session-1.md
```

***

## LangChain Example (MCP)

```python theme={"theme":{"light":"min-light","dark":"min-dark"}}
import asyncio
import os
from langchain.agents import create_agent
from langchain_core.messages import HumanMessage
from langchain_mcp_adapters.client import MultiServerMCPClient

BOSSA_URL = "https://bossamemory.com/mcp"
BOSSA_API_KEY = os.environ["BOSSA_API_KEY"]  # Your workspace key

async def main():
    client = MultiServerMCPClient({
        "bossa": {
            "url": BOSSA_URL,
            "transport": "streamable_http",
            "headers": {
                "X-API-Key": BOSSA_API_KEY,
                "Authorization": f"Bearer {BOSSA_API_KEY}"
            }
        }
    })
    tools = await client.get_tools()
    agent = create_agent("openai:gpt-4o", tools)

    response = await agent.ainvoke({
        "messages": [
            HumanMessage(content="List files at / and then read the first file you find")
        ]
    })
    print(response)

asyncio.run(main())
```

***

## Tool Usage Patterns

These patterns apply to both MCP tools and CLI commands. MCP uses `read_file`; CLI uses `bossa files read`. They are examples of [dynamic context discovery](DYNAMIC_CONTEXT_DISCOVERY)—pulling only the context you need, when you need it.

### Explore Before Reading

Use `ls` to discover structure, then `read`/`read_file` only for relevant files:

```
1. ls path="/"
2. ls path="/customers"
3. read_file path="/customers/acme/profile.md"
```

### Search Without Reading Everything

Use `grep` with `output_mode="files_with_matches"` to find files, then read only matches:

```
1. grep pattern="Enterprise" path="/customers" output_mode="files_with_matches"
2. read_file path="/customers/acme/profile.md"
```

### Batch Operations (CLI)

For agents doing many ops, use `bossa files batch` to reduce round-trips:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
echo '{"op":"read","path":"/docs/api.md"}
{"op":"read","path":"/memory/summary.md"}
{"op":"write","path":"/output/combined.md","content":"..."}' | bossa files batch
```

### Save Agent Output

Use `write_file` (MCP) or `bossa files write` (CLI) to persist summaries, analyses, or memory:

```
# MCP
write_file path="/memory/session-summary.md" content="# Session Summary\n\n..."

# CLI
echo "# Session Summary\n\n..." | bossa files write /memory/session-summary.md
```

### Edit In Place

Use `edit_file` (MCP) or `bossa files edit` (CLI) for targeted changes instead of read → modify → write:

```
# MCP
edit_file path="/config.json" old_string="\"debug\": false" new_string="\"debug\": true"

# CLI
bossa files edit /config.json --old '"debug": false' --new '"debug": true'
```

***

## Environment Variables for Examples

| Variable         | Description                                 |
| ---------------- | ------------------------------------------- |
| `BOSSA_API_URL`  | `https://bossamemory.com` (managed service) |
| `BOSSA_API_KEY`  | Your workspace API key                      |
| `OPENAI_API_KEY` | For LangChain/OpenAI agents                 |

## --safe Flag for Harnesses

Read-only commands (`ls`, `read`, `grep`, `glob`, `stat`, `tree`, `du`) support `--safe`. Use it when your agent harness gates tool execution: `--safe` signals that the operation is read-only and can be auto-approved.

***

## Workspace Isolation

Each API key maps to one workspace. Agents using key A cannot see or modify files in workspace B. See [MCP Integration](MCP#workspace-isolation) for details.