CLI reference

Every command in sibyl-memory-cli. Install with pip install 'sibyl-memory-cli[mcp]'; it brings the SDK, the Hermes provider, and the MCP server with it.

Command summary

init

Opens the browser sign-in page. Sign in with a wallet, or with your email and the code the terminal prints; the terminal picks up the sign-in by itself and writes credentials at mode 0600. Afterwards it offers to add or confirm your email (terminal only).

An account is required to use Sibyl Memory, on Free as on Pro. Until sibyl init has run, the memory tools in Claude Code, Codex, Hermes and the SDK answer that an account is needed. Your local data is never deleted and sibyl memory reads it without an account.

Sibyl Memory runs on Linux, macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is not supported. sibyl init and sibyl setup refuse to run on native Windows and point you at the WSL2 steps. Every other command keeps working on a machine that already activated there, so status, upgrade, claim, devices and logout are unaffected. To run unsupported anyway, set SIBYL_ALLOW_NATIVE_WINDOWS=1.

$ sibyl init
$ sibyl init --no-email        # skip the email prompt
$ sibyl init --replace         # re-activate this computer in place of its earlier sign-in

Signing in again on the same computer never uses a second computer slot. Free covers one computer and Pro up to 2. When the account is at its limit, sibyl init lists the computers already signed in and, in a terminal, offers to open the account page so you can sign one out there; the terminal itself cannot sign another computer out.

setup

Auto-detects your stack and wires Sibyl as the memory provider. No argument detects everything; name one target to wire just it.

$ sibyl setup                 # detect all
$ sibyl setup claude-code     # target: hermes | claude-code | codex | cursor | grokbot | deepseek
$ sibyl setup --dry-run       # print changes, write nothing
$ sibyl setup --print-config  # absolute server path + an mcpServers block, then exit

Flags: --yes (accept defaults), --force (overwrite a non-Sibyl provider config), --dry-run, and --hermes-home / --claude-settings / --codex-config / --cursor-config / --dsh-home to override autodetection, and --dsh-profile <name> to wire one DeepSeek Harness profile instead of all of them.

Setup needs no terminal prompts with --yes, so an agent can run it in its own shell. grokbot is never auto-detected: it is the Cursor wiring plus a printed confirmation (server name, command path, config file) for Grok Bot. deepseek (short name dsh) wires DeepSeek Harness. Every config file setup changes is backed up first under ~/.sibyl-memory/backups/. When no agent is detected, setup prints the server's absolute path and a copy-paste mcpServers block instead of stopping.

Setup also installs the save and debloat procedures: /sibyl-save and /sibyl-debloat in Claude Code (plus five hooks), a block in Codex's AGENTS.md and a Codex skill, a skill in Hermes, and the save and debloat prompts on any MCP host. An edit you make to any of these files is never overwritten.

migrate

Moves existing agent memory into Sibyl without risk. Backs up and byte-verifies every file it finds, wires Sibyl into each detected harness, prints an extraction prompt you run in your own agent (locally), then slims the instruction files it found (CLAUDE.md, AGENTS.md, .cursorrules, ...), one question per file, only on your confirmation. Config files are never trimmed.

$ sibyl migrate
$ sibyl migrate --no-debloat   # skip the trim step

Flags: --backup-dir PATH, --no-debloat, --yes (the trim step still asks separately), --force (overwrite a non-Sibyl memory provider when wiring a harness).

status

Shows your local credentials, DB size, and tier cache, this computer's access, the computers on your account, and the server's view of your tier and cap. If LOCAL and SERVER tiers diverge, run sibyl refresh.

$ sibyl status

  LOCAL
    Account           a1b2c3d4…e5f6
    Tier              FREE
    DB size           1,247,000 bytes (1.19 MB · 23.8% of free cap)

  ACCESS
    Access            active · renews in 1h
    Computers         1 of 1 (Free) · Pro: up to 2

  SERVER
    Tier              FREE
    Cap bytes         5,242,880

The Access row says whether the memory tools can run on this computer, and what to do when they cannot:

refresh

Checks your account now instead of waiting for the next check-in, and says what changed (tier, cap, computers, email, access). It also refreshes the save and debloat procedures, the skill shims, the Codex block and hooks that are already wired. Run it after an upgrade, a staking unlock or a plan change.

$ sibyl refresh

With no account it says to run sibyl init and exits 0; it exits 2 when the server could not be reached.

upgrade & claim

Opens the account billing page when it is offered, otherwise the stake / USDC page through a one-time link (no token in the URL). Bought by card before installing? Link the purchase with sibyl claim. See Tiers & access.

$ sibyl upgrade
$ sibyl claim cs_...           # code shown after paying

A confirmed email is required before buying; sibyl upgrade says so and still opens the page.

email

Your account email is used for receipts and security notices.

$ sibyl email                          # confirmed, not confirmed, or none
$ sibyl email add [email protected]      # send a code to a new address
$ sibyl email verify                   # send a code to the address on file
$ sibyl email confirm 123456           # confirm the six-digit code

whoami & devices

$ sibyl whoami                 # masked one-line summary (--full to unmask)
$ sibyl devices                # computers signed in to this account
$ sibyl devices revoke 2       # sign one out by its listed index

The list shows the account's computer limit when the server sends it: Free 1, Pro up to 2.

memory (inspect, adopt)

Look at your own store without an agent in the loop. list, search and recall are read-only and need no account, so your local data is always readable.

$ sibyl memory list                    # list entities (optionally by category)
$ sibyl memory search "atlas"           # FTS across entities + state + reference + journal
$ sibyl memory recall project atlas    # one entity by category + name
$ sibyl memory neighbors --entity project atlas   # the links of one memory
$ sibyl memory adopt                   # move memory from before sign-in into your account

Memory written on this computer before you signed in moves into your account by itself the first time a signed-in agent uses the store. adopt is the explicit version for a store that has held another account: it asks first (--yes to skip the question), works locally in one transaction, and deletes nothing.

save

The save procedure runs inside your agent (/sibyl-save in Claude Code, the save prompt on MCP hosts). The command is the terminal side of it.

$ sibyl save                           # how to run the save procedure in your agent
$ sibyl save --fact "deploys go out on Fridays"
$ sibyl save --status                  # last save, writes since, decisions queued

Flags: --fact, --status, --preview (say what would be written, write nothing), --capsule (Pro: write a session capsule now; counts only, no content).

debloat

Measures the instruction files your agent loads every start (CLAUDE.md, AGENTS.md, .cursorrules and the rest of the scan set) and moves accreted history out of them without losing a byte: the history moves out and a one-line pointer stays. Free keeps the history in a sibling *-history file; Pro stores it in Sibyl Memory, where it stays searchable, after a verified backup.

$ sibyl debloat                        # measure (--fyi one line, --json record)
$ sibyl debloat plan                   # what a trim would move; nothing moves
$ sibyl debloat apply CLAUDE.md        # trim one file now, after a confirmation
$ sibyl debloat auto ~/CLAUDE.md       # Pro: trim that file at its path by itself
$ sibyl debloat manual ~/CLAUDE.md     # back to asking first
$ sibyl debloat undo                   # undo the last trim

auto <file> authorizes that file at its path, never a file with the same name elsewhere. Flags: --root, --config, --include (repeatable), --yes.

skills

$ sibyl skills status                  # version, checksums, shims and hooks
$ sibyl skills install                 # install or refresh; never overwrites your edits
$ sibyl skills reset SAVE.md           # replace one file with the shipped version
$ sibyl skills uninstall               # run it before pip uninstall

uninstall removes the procedures, the shims, the Claude Code hooks in ~/.claude/settings.json and the Codex block (files you edited are kept). Run it before pip uninstall: the hooks call this package's sibyl command.

On Pro, Sibyl finds repeated work in your journal (locally) and proposes it as a skill. Nothing is created without a yes:

$ sibyl skills proposals               # list
$ sibyl skills proposals show <id>
$ sibyl skills proposals accept <id>   # writes the skill for Claude Code, Codex and Hermes
$ sibyl skills proposals reject <id>
$ sibyl skills proposals mute <kind>   # unmute <slug> to undo

Flags: --to <dir> (accept: write <dir>/<name>/SKILL.md instead of the harness folders), --note, --days (mute length, default 30).

autosave

On Pro, Claude Code saves your session by itself: once early, then about every hour of active work; on Hermes, Cursor and Codex the plugin asks your agent to save at the same moments; a session capsule is recorded either way. Each automatic save is one extra model turn that reads and writes memory.

$ sibyl autosave                       # status
$ sibyl autosave every 90              # minutes of active work, 30 to 240 (default 60)
$ sibyl autosave off                   # e.g. on a CI box
$ sibyl autosave on

On Free the setting is kept for the day you upgrade.

reminders & hook

$ sibyl reminders off                  # on | off | quiet (quiet silences Pro reports)

On Free, Sibyl reminds you quietly to run /sibyl-save and /sibyl-debloat; sibyl reminders off turns that off. sibyl hook is the entry point the Claude Code hooks call; it is installed by setup and not for manual use.

health & update

$ sibyl health                 # provider self-check
$ sibyl doctor                 # end-to-end MCP check: save, recall, delete a test memory
$ sibyl doctor --fix           # also repair stale or broken agent wiring (never adds a missing one)
$ sibyl doctor --harness codex # check one agent's wiring; --no-harness skips them; --json for agents
$ sibyl update                 # report outdated sibyl-memory-* packages
$ sibyl update --apply         # pip install -U the outdated ones