Install Sibyl Memory Plugin V3

This page walks you from "I've heard of it" to "my agent remembers" in about five minutes. Works on Mac, Linux, and Windows. No credit card required for the free tier.

What you'll need

• A Mac, Linux machine, or Windows computer.
• Python 3.10 or newer. (If you're not sure what you have, see the check below.)
• About five minutes.

That's it. You don't need to install a database, sign up for anything, or pay for cloud storage. Everything runs locally on your machine.

Step 1 · Check that Python is installed

Open a terminal (Terminal on Mac, any shell on Linux, PowerShell on Windows) and run:

python3 --version

You should see something like Python 3.10.12 or higher. If you see a lower number, or "command not found," install a newer Python first.

brew install [email protected]

sudo apt update && sudo apt install python3.12 python3-pip

Step 2 · Install

One line, either way works:

curl -fsSL https://install.sibyllabs.org | sh

or, if you prefer pip:

pip install sibyl-memory-cli

Either path pulls in three small Python packages: sibyl-memory-client (the local SDK with the SQLite + FTS5 memory engine), sibyl-memory-hermes (the Hermes provider), and sibyl-memory-cli (the sibyl command itself). The whole stack is less than 100 KB.

pip install sibyl-memory-hermes

Step 3 · Activate your account

Sibyl Memory Plugin needs to know who you are so it can apply the right tier (free or paid) and keep your data isolated from any other identities on the same machine. Activation is free and takes about a minute. Pick the path that matches what you have.

$ sibyl init

Sibyl Memory Plugin · activation

  Session:     a1b2c3d4…e5f6
  Opening:     https://sibyllabs.org/plugin/activate?session=a1b2c3d4-…

  Sign in with your wallet or email in the browser. This terminal will pick up automatically.

  ⠹ waiting for browser activation … 9:42 left

The CLI generates a one-time session, opens the activation page in your browser, and then polls. The browser page shows two options.

Sign in with a wallet

Best path if you hold $SIBYL or want a wallet-bound identity. Click Connect & sign, your wallet (MetaMask, Rabby, Coinbase Wallet, anything that supports Sign-In With Ethereum) opens a one-line signature request. No transaction. No gas. You're proving the wallet is yours.

Sign in with email

Best path if you don't have a wallet yet. Type your email, click Email me a code, check your inbox for a 6-digit code, type it back into the page. That's it. You can add a wallet later via sibyl upgrade (needed if you want to stake $SIBYL or subscribe in USDC).

Either path writes ~/.sibyl-memory/credentials.json (mode 0600) on your machine. The terminal picks up automatically:

✓ Activated.
  Account            a1b2c3d4…e5f6
  Tier               FREE
  Email              [email protected]
  Credentials        /Users/you/.sibyl-memory/credentials.json

Wire the provider into Hermes:
    from sibyl_memory_hermes import SibylMemoryProvider
    agent = Agent(memory=SibylMemoryProvider())

When you hit the cap, upgrade

The free tier is hard-capped at 2 MB of local memory. When you approach it, the SDK starts rejecting writes with a clear upgrade prompt. To lift the cap, run:

$ sibyl upgrade

The browser opens with two paths. Pick whichever fits:

• Stake $SIBYL. Connect any wallet (or use the Coinbase Smart Wallet for a passkey-only experience). Sign once to bind. The page checks your $SIBYL balance on Base. If you hold the threshold (currently 100,000 SIBYL, configurable, liquid + staked combined), the cap lifts.
• Subscribe in USDC. Pick monthly ($29), quarterly ($79), or annual ($290). The page builds a single USDC transfer on Base. Sign it in your wallet. The server confirms the on-chain payment and your tier flips immediately.

Once the payment settles, the CLI updates its local hints (credentials.json and the tier cache) so your next write picks up the new entitlement without an extra round trip. The cap decision itself is always made server-side against the database, not from the local file. See tiers for the full pricing breakdown.

Step 4 · Wire it into your agent

Three real paths, depending on what you're running. Pick whichever fits your stack. The integrations page covers all three with config snippets for every supported client.

If you're using Claude Code, Codex, Cursor, or Continue (MCP)

Install the MCP server alongside the SDK, then declare it in your client's config. For Claude Code, add to ~/.claude/settings.json (or project-local .mcp.json):

$ pip install sibyl-memory-mcp

{
  "mcpServers": {
    "sibyl-memory": { "command": "sibyl-memory-mcp" }
  }
}

Restart the client. 8 memory_* tools become available immediately. Codex CLI, Cursor, and Continue use the same sibyl-memory-mcp command in their respective config files — see all four.

If you're using Hermes

Drop the provider in when you create your agent:

from sibyl_memory_hermes import SibylMemoryProvider
from hermes_agent import Agent

agent = Agent(memory=SibylMemoryProvider())

Two lines. From here on, every conversation the agent has gets written to its memory automatically. Every recall runs locally. There's no round-trip to anyone's cloud.

If you're using LangChain, LlamaIndex, or custom Python

Import MemoryClient directly and call methods. ~30 lines wraps it as a LangChain BaseChatMessageHistory or a LlamaIndex BaseChatStore — full examples on the integrations page.

Step 5 · Verify it's working

Run this short script. If it prints "memory works," everything is set up correctly:

from sibyl_memory_client import MemoryClient

client = MemoryClient.local("~/.sibyl-memory/memory.db")
client.set_entity("check", "smoke-test", {"ok": True})
result = client.get_entity("check", "smoke-test")

if result["body"]["ok"]:
    print("memory works")

What just got installed on your machine

A folder at ~/.sibyl-memory/. Inside, four files:

• memory.db. The database where your agent's memory lives. Standard SQLite, openable with any SQLite browser if you ever want to look.
• memory.db-wal and memory.db-shm. Helper files SQLite creates while it's running. Don't touch.
• credentials.json. Your account id, tier, email or wallet, and session token. Only readable by your user account (file permissions 0600).
• tier_cache.json. A 7-day cache of your server-verified tier. Lets the SDK avoid phoning home on every write. Cleared automatically when you run sibyl upgrade.

Nothing else. No daemon running in the background. No data sent anywhere. The agent reads from and writes to those files directly.

Going further

• Quickstart. Your first session, write something to memory, recall it, search.
• How memory works. The five kinds of memory and when to use each.
• What's free, what's paid. When you'd want to upgrade and what each plan unlocks.

Troubleshooting

"command not found: pip"

Try pip3 instead. On some systems pip is only installed for Python 3 under the pip3 name.

"externally-managed-environment" warning on Linux

Some Linux distributions block direct pip installs by default. The cleanest fix is a virtual environment:

python3 -m venv ~/.sibyl-venv
source ~/.sibyl-venv/bin/activate
pip install sibyl-memory-hermes

"permission denied" writing to ~/.sibyl-memory

The folder needs to be writable by your user account. Run:

chmod -R u+rw ~/.sibyl-memory

It says the database is locked

SQLite holds a brief lock while writing. If you have two scripts trying to write to the same database at once, one will wait. This is normal. If a script crashed and left a lock, delete memory.db-wal and try again. Your data is safe in memory.db.

For anything else, see the full troubleshooting page (in progress) or email [email protected].