Skip to main content

​
Get Started in 30 Seconds

Give your AI agent persistent memory so it remembers conversations, learns preferences, and builds up context over time—just like Claude Code does. No database setup. No vector embeddings. Just simple files that work. Base URL: https://bossamemory.com

​
What You’ll Build

By the end of this guide, you’ll have an agent that:
  • Stores user preferences in /user/prefs.json
  • Searches past conversations with grep
  • Remembers context across sessions
Let’s go.

​
1. Install the CLI

The Bossa CLI manages accounts, workspaces, and API keys. 
pip install bossa-memory

​
2. Sign Up & Log In

# Create an account (email + password)
bossa signup

# Log in
bossa login

# Verify
bossa whoami
The CLI defaults to the managed service and fetches auth config automatically. No environment variables needed for signup/login.

​
3. Create a Workspace & API Key

Free tier includes 1 workspace. See Pricing & Limits for tier details. 
# Create a workspace (e.g. "my-app")
bossa workspaces create my-app

# Create an API key (copy it — shown once)
bossa keys create my-app
One-liner: Create workspace and key and save to config in one step: 
bossa workspaces create my-app && bossa keys create my-app --save
Example output: 
Created API key for workspace my-app:
  sk-7f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f

Store this key securely. It won't be shown again.
Avoid passing --key on every command by setting an active workspace: 
bossa workspace use my-app --key sk-7f3a9b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f
Or use bossa keys create my-app --save to create and save in one step. The key is stored in ~/.config/bossa/config.json. After this, you can run bossa files ls / without --key.

​
Add Bossa to your agent config (optional)

Run bossa init to add Bossa usage instructions to your AGENTS.md or CLAUDE.md. Your AI agent will then know how to use Bossa commands. 
bossa init --path ./AGENTS.md --yes

​
5. Make Your First Request

Agents can use Bossa in two main ways:
InterfaceWhen to use
CLIYour agent runs tools as subprocesses (CLI-based harnesses, beads, etc.). Use bossa files ls, read, write, grep, glob, edit, delete with --json or BOSSA_CLI_JSON=1.
MCPYour harness supports MCP (Claude Desktop, Cursor, LangChain). Connect to the MCP endpoint and use the tools directly.
Both expose the same filesystem operations. Choose based on how your agent executes tools.

​
REST (scripts, curl)

# List root directory
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://bossamemory.com/api/v1/files/list?path=/"

# Create a file
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "/hello.txt", "content": "Hello from Bossa!"}' \
  "https://bossamemory.com/api/v1/files"

# Read the file
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://bossamemory.com/api/v1/files?path=/hello.txt"

​
CLI (agent subprocess)

# Option A: Use active workspace (after bossa workspace use my-app --key sk-xxx)
bossa files ls /
bossa files read /hello.txt

# Option B: Set BOSSA_API_KEY
export BOSSA_API_KEY=YOUR_API_KEY
export BOSSA_CLI_JSON=1   # Optional: JSON output for agents
bossa files ls /
bossa files read /hello.txt
See CLI Reference for the full command reference.

​
MCP (agent frameworks)

Connect any MCP client (Claude Desktop, Cursor, LangChain) to: 
https://bossamemory.com/mcp
Pass your API key in headers:
  • Authorization: Bearer YOUR_API_KEY
  • X-API-Key: YOUR_API_KEY
See MCP Integration for client-specific setup.

​
6. Upload Files via CLI

# Single file
bossa files put ./my-doc.txt --target /docs/my-doc.txt

# Entire directory (bulk)
bossa files upload ./my-docs --target /docs
Set BOSSA_API_KEY in your environment, use --key YOUR_API_KEY, or run bossa workspace use <name> --key <key> to store the key. The CLI uses the managed service by default when BOSSA_API_URL points to the hosted URL.

​
Full filesystem access

bossa files ls /              # List directory
bossa files read /path/file   # Read file
bossa files write /path       # Write (stdin or --content)
bossa files grep "pattern"    # Search contents
bossa files glob "*.md"       # Find by glob
bossa files edit /path --old X --new Y
bossa files delete /path

​
Using the CLI as an agent

When your agent harness runs tools as subprocesses (e.g. CLI-based agents), use bossa files for full filesystem access. Use --json for machine-readable output, or set BOSSA_CLI_JSON=1 so all commands return JSON without passing the flag. Exit codes: 0 success, 1 error, 2 auth failure.

​
Environment Variables Summary

VariableRequiredDescription
BOSSA_API_URLNoDefault: https://bossamemory.com (managed service). Override for self-hosted.
BOSSA_API_KEYYes (API calls)Your workspace API key. Or use bossa workspace use <name> --key <key>.
BOSSA_WORKSPACENoOverride active workspace by name (lookup key from config).
BOSSA_CLI_JSONNoSet to 1 for agent mode — all CLI commands return JSON
OPENAI_API_KEYYes (examples)For running the example agents
Self-hosting only: Set SUPABASE_URL and SUPABASE_ANON_KEY when pointing the CLI at your own backend.

​
Next Steps

Last modified on March 13, 2026