███╗ ███╗███████╗███╗ ███╗██████╗ ██╗ ██╗███████╗
████╗ ████║██╔════╝████╗ ████║██╔══██╗██║ ██║██╔════╝
██╔████╔██║█████╗ ██╔████╔██║██████╔╝██║ ██║███████╗
██║╚██╔╝██║██╔══╝ ██║╚██╔╝██║██╔══██╗██║ ██║╚════██║
██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║██████╔╝╚██████╔╝███████║
╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═════╝ ╚══════╝
Scoped memory for LLM agents. Install and go.
Most agent frameworks treat memory as an afterthought — a global dict, a hacked-together file, or nothing at all. MemBus fixes that.
It gives your agents a clean, scoped memory layer backed by a real server — so memories survive restarts, agents can share context, and you can swap the storage backend without touching a line of agent code.
Install
pip install membus
After installing, type membus in your terminal to open the interactive quick-start guide.
How it works
MemBus has two parts:
| Part | What it does | Where it runs |
|---|---|---|
| membus-server | Stores memories, handles scopes, auth, and adapters | Your server (Render, Railway, self-hosted) |
| membus (this package) | Python client — read, write, manage memories | Your agent code |
The client talks to the server over HTTP. Swap the server's adapter in one env var — no client code changes ever.
Quick Start
from membus import MemBus, Scope
bus = MemBus() # uses your deployed server by default
# Store something
bus.write("user_name", "Alice", scope=Scope.USER, scope_id="user_123")
# Get it back — anywhere, any agent
name = bus.read("user_name", scope=Scope.USER, scope_id="user_123")
# → "Alice"
# Clean up a session when it ends
bus.manage(scope=Scope.SESSION, operation="prune", scope_id="sess_456")
Memory Scopes
The four scopes are the heart of MemBus. Each one answers the question: who should remember this, and for how long?
| Scope | Lifetime | Use it for |
|---|---|---|
user |
Forever (until deleted) | Preferences, name, history — anything tied to a person |
session |
One conversation | Scratchpad state, context window overflow |
agent |
Long-lived | An agent's private notes, persona, learned behaviours |
org |
Shared across the team | Research findings, shared context, team knowledge |
# Each scope is fully isolated — same key, different scope = different memory
bus.write("status", "active", scope=Scope.USER, scope_id="u1")
bus.write("status", "thinking", scope=Scope.SESSION, scope_id="s1")
bus.write("status", "idle", scope=Scope.AGENT, scope_id="researcher")
Storage Adapters
Your server decides where memories actually live. The client doesn't care — it just calls the API.
| Adapter | Backed by | Survives restarts | Best for |
|---|---|---|---|
memory |
RAM | ❌ | Dev & testing — zero infra |
redis |
Redis | ✅ | Fast, session-friendly production |
supabase |
Postgres | ✅ | Persistent, Postgres-backed |
chroma |
ChromaDB | ✅ | Semantic / vector memory |
Switch adapters in one line on your server:
# In your server's .env
MEMBUS_ADAPTER=supabase
No client code changes. Ever.
You can also declare which adapter you expect in your client code — MemBus will warn you if there's a mismatch:
bus = MemBus(expected_adapter="supabase")
bus.health()
# ⚠ UserWarning: expected 'supabase' but server is running 'memory'
Operations
write — store a memory
bus.write(
key="model_preference",
value="gpt-4o",
scope=Scope.USER,
scope_id="user_123",
ttl=3600, # optional: expire in 1 hour
)
read — retrieve a memory
model = bus.read(
key="model_preference",
scope=Scope.USER,
scope_id="user_123",
default="gpt-4o-mini", # fallback if not found
)
manage — keep memory clean
# Remove null/empty memories
bus.manage(scope=Scope.SESSION, operation="prune", scope_id="s1")
# Remove exact duplicates
bus.manage(scope=Scope.SESSION, operation="deduplicate", scope_id="s1")
# LLM-powered compression (requires OpenAI key on server)
bus.manage(scope=Scope.SESSION, operation="compress", scope_id="s1")
flush — wipe a scope
deleted = bus.flush(scope=Scope.SESSION, scope_id="sess_456")
# → 12
stats — see what's stored
bus.stats()
# → {"total_keys": 42, "by_scope": {"user": 10, "session": 5, "agent": 20, "org": 7}, "adapter": "supabase"}
MCP Interface
MemBus is MCP-native. Expose all memory operations as tools that any MCP-compatible agent can call directly.
Standalone MCP server:
from membus import MemBus
from membus.mcp import MemBusMCPServer
bus = MemBus(
default_scope_ids={"user": "u1", "session": "s1", "agent": "my_agent", "org": "team"},
)
server = MemBusMCPServer(bus, name="membus")
server.run() # stdio — plug into Claude, AutoGen, CrewAI, or any MCP host
Register into an existing FastMCP server:
from membus.mcp import register_membus_tools
register_membus_tools(my_existing_mcp_server, bus)
# Adds: memory_read, memory_write, memory_manage, memory_flush, memory_stats
Multi-Agent Example (AutoGen)
from membus import MemBus, Scope
from membus.mcp import register_membus_tools
from autogen_agentchat.agents import AssistantAgent
from autogen_core.tools import FunctionTool
bus = MemBus()
# Researcher stores findings
bus.write("findings", "LLMs excel at reasoning tasks", scope=Scope.ORG, scope_id="team")
# Analyst reads them — even in a separate process or server
findings = bus.read("findings", scope=Scope.ORG, scope_id="team")
Memories flow between agents through MemBus — not through chat history. That means they survive context resets, cross-process boundaries, and outlive any single conversation.
CLI
# Open the interactive guide
membus
# Check server health
membus health --server https://your-server.onrender.com
# View memory stats
membus stats --server https://your-server.onrender.com
# Flush a scope
membus flush --server https://your-server.onrender.com --scope session --scope-id sess_456
# Show the guide again any time
membus guide
Skip the flags by setting env vars:
export MEMBUS_SERVER_URL=https://your-server.onrender.com
export MEMBUS_API_KEY=your-secret-key
membus stats # just works
membus health
Deploy Your Own Server
MemBus client connects to a membus-server instance you control. Deploy one in minutes:
- Clone membus-server
- Push to GitHub
- Deploy on Render —
render.yamlis included, everything is pre-configured - Set your env vars in the Render dashboard
- Point the client at your URL
bus = MemBus(server_url="https://your-membus.onrender.com", api_key="your-key")
Links
Metadata
Release files for membus 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| membus-0.1.3.tar.gz | 11.4 kB | Without provenance | Details for membus-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| membus-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for membus-0.1.3-py3-none-any.whl |
Total release size: 24.9 kB
Release files / membus-0.1.3.tar.gz
| Download URL | membus-0.1.3.tar.gz |
|---|---|
| Size | 11.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
98516c6348626c2644d1d2ca822bde89fa62519ee99d747b7a16096543f157cc
|
|
BLAKE2b-256 checksum How to use checksums |
abe754231a32dc91fb0a947cf8925eac70a4bd02ac0c5e562fdcab26e7d1a3ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Release files / membus-0.1.3-py3-none-any.whl
| Download URL | membus-0.1.3-py3-none-any.whl |
|---|---|
| Size | 13.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ece4e0764e82459480b65c7857a91580eaab3d6824cc2bb3f19b27230ee952b4
|
|
BLAKE2b-256 checksum How to use checksums |
fe9c312ff622a971600edac917f1e95ca2ab338bc1bda9802fa3dfbaddadba6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Security for membus 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.