bossa-memory 0.1.1

Your AI agent's long-term memory. Persistent filesystem backed by Postgres.

Bossa

Stop building agents that forget.

Give your AI a filesystem. ls, grep, read, write. That's it.

📖 Documentation → bossa.mintlify.app

pip install bossa-memory · No infrastructure · Sign up, get a key, ship.

Get Started · Why Filesystem? · CLI · MCP · REST API · Examples · Docs

---

Your agent keeps asking the same questions.

Every session is Groundhog Day. User preferences? Forgotten. Last conversation? Gone. Project context? What project?

You've tried RAG. Embeddings. Chunking. Tuning. It's a rabbit hole—and your agent still forgets.

Claude Code and Manus figured it out: give agents a filesystem. Not vectors. Not embeddings. Files. ls, grep, read, write. Agents already know how to use them. Bossa gives your agents that filesystem—persistent, searchable, Postgres-backed—in one line.

---

Why filesystem over RAG?

Bossa (filesystem)	Traditional RAG
grep "user preferences"	Tune embeddings, pray it works
Directory structure = organization	Flat vector space
Works like CLI tools agents know	New abstractions to learn
Debuggable with ls, cat	Black box retrieval
No embedding drift	Constant re-indexing

For 80% of agent use cases, filesystems just work. Why we chose this →

---

Dynamic context discovery—built in.

Cursor and LangChain are moving to dynamic context discovery: let the agent pull context on demand instead of loading everything. Fewer tokens. Better answers.

Bossa is the storage layer for that. Your agent uses ls and grep to discover what's relevant, then read to pull only what it needs. No new concepts. Just files.

---

Get Started

30 seconds. No infrastructure. No Docker. No config.

Step	Action
1	Sign up via the CLI
2	Create a workspace & API key
3	Connect your agent via MCP or REST

Base URL: https://filesystem-fawn.vercel.app
MCP endpoint: https://filesystem-fawn.vercel.app/mcp

pip install bossa-memory
bossa signup && bossa login
bossa workspaces create my-app && bossa keys create my-app
bossa workspace use my-app --key sk-...   # Store key, then:
bossa files ls /

---

What you get

• Feels like local files — ls, read, write, grep, glob, edit, delete. No new concepts.
• Powered by Postgres — Full-text search, trigrams, ACID, JSON. Enterprise-ready.
• Plug-and-play — CLI for subprocess agents; MCP for LangChain, Claude, Cursor; REST for scripts.
• Your agent's space — Each API key = one workspace. No cross-tenant leakage.

---

What can you build?

Personal AI assistant — Preferences, conversation history, project context. Never ask twice.

Customer support agent — Account info, tickets, interaction history. One source of truth.

Research agent — Sources, findings, notes. Build knowledge over weeks.

See more examples →

---

CLI

First-class for agents. When your harness runs tools as subprocesses, use bossa files for full parity with MCP.

bossa files ls /                    # List directory
bossa files read /docs/x.md         # Read file
bossa files grep "project alpha"   # Search
echo "content" | bossa files write /note.txt

Agent mode: BOSSA_CLI_JSON=1 for machine-readable output. Full CLI reference →

---

MCP Tools

Connect to https://filesystem-fawn.vercel.app/mcp. Pass Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY.

Tool	What it does
ls	List files and directories
read_file	Read file contents
write_file	Create or overwrite
edit_file	Replace substring in place
grep	Search with literal/regex
glob_search	Find by pattern
delete_file	Delete a file

MCP setup for Claude, Cursor, LangChain →

---

REST API

Base URL: https://filesystem-fawn.vercel.app

Method	Endpoint	Description
POST	/api/v1/files	Create or overwrite
GET	/api/v1/files?path=...	Read file
GET	/api/v1/files/list?path=...	List directory
POST	/api/v1/files/search	Grep search
GET	/api/v1/files/glob?pattern=...&path=...	Glob search
PATCH	/api/v1/files	Edit in place
DELETE	/api/v1/files?path=...	Delete

Full REST reference →

---

Examples

CLI (agent subprocess)

export BOSSA_API_KEY=your-api-key
export BOSSA_CLI_JSON=1
bossa files ls /
bossa files read /memory/summary.md
echo "New content" | bossa files write /memory/note.txt

LangChain + MCP

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "bossa": {
        "url": "https://filesystem-fawn.vercel.app/mcp",
        "transport": "streamable_http",
        "headers": {"X-API-Key": "YOUR_API_KEY"}
    }
})
tools = await client.get_tools()
# Use with your agent

More examples in the repo →

---

Self-Hosting

Run Bossa on your own infrastructure. Self-hosting guide →

---

Documentation

Doc	Description
Getting Started	Sign up, API key, first request
Why Filesystem?	Filesystem vs RAG
Dynamic Context Discovery	How Bossa fits Cursor & LangChain
CLI Reference	Full command reference
MCP Integration	Claude, Cursor, LangChain
REST API	Full API reference
Agent Integration	Examples, tool patterns
Self-Hosting	Run on your infrastructure

---

License

MIT