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.

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:

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)

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—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:

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 for details.