Skip to main content
 ███╗   ███╗███████╗███╗   ███╗██████╗ ██╗   ██╗███████╗
 ████╗ ████║██╔════╝████╗ ████║██╔══██╗██║   ██║██╔════╝
 ██╔████╔██║█████╗  ██╔████╔██║██████╔╝██║   ██║███████╗
 ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██╔══██╗██║   ██║╚════██║
 ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║██████╔╝╚██████╔╝███████║
 ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝╚═════╝  ╚═════╝ ╚══════╝

Scoped memory for LLM agents. Install and go.

PyPI version Python License: MIT MCP Native


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:

  1. Clone membus-server
  2. Push to GitHub
  3. Deploy on Render — render.yaml is included, everything is pre-configured
  4. Set your env vars in the Render dashboard
  5. 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)

Source distribution for membus 0.1.3
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)

Table of built distributions (wheels) for membus 0.1.3
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page