sibyl-memory-cli 0.4.0__tar.gz → 0.5.0__tar.gz

sibyl_memory_cli-0.5.0/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: sibyl-memory-cli
+Version: 0.5.0
+Summary: Command-line interface for the Sibyl Memory Plugin. `sibyl init` activates, `sibyl upgrade` opens the Pro / Elite upgrade flow, `sibyl status` shows current tier and DB stats, `sibyl whoami` gives a one-line account summary, `sibyl devices` lists active devices and supports per-device revoke.
+Author-email: "SIBYL, Sibyl Labs LLC" <sibyl@sibyllabs.org>
+License: MIT
+Project-URL: Homepage, https://sibyllabs.org/plugin
+Project-URL: Documentation, https://docs.sibyllabs.org/memory/
+Project-URL: Repository, https://github.com/Sibyl-Labs/Sibyl-Memory
+Keywords: sibyl,memory,cli,agent,hermes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sibyl-memory-client>=0.9.0
+Requires-Dist: sibyl-memory-hermes>=0.5.0
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: mcp
+Requires-Dist: sibyl-memory-mcp>=0.3.0; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# sibyl-memory-cli
+
+Command-line interface for the **Sibyl Memory Plugin**.
+
+```bash
+pip install sibyl-memory-cli
+```
+
+Sibyl Memory runs on Linux, macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is not supported.
+
+This pulls in `sibyl-memory-client` (the local SDK) and `sibyl-memory-hermes` (the Hermes provider) automatically.
+
+## Commands
+
+```
+sibyl --version               Print the installed versions: cli, client, mcp, hermes, langgraph.
+sibyl init                    Open the browser activation page. Writes ~/.sibyl-memory/credentials.json.
+                              Afterwards it offers to add or confirm your email (terminal only).
+sibyl init --no-email         Activate without the email prompt.
+sibyl init --replace          Re-activate this computer in place of its earlier sign-in (re-activation
+                              never uses a second computer slot). At the account's computer limit
+                              (Free: one computer) init lists the computers signed in and offers to
+                              sign one out on the account page.
+sibyl refresh                 Check your account now (an upgrade, a staking unlock or a plan change
+                              lands at once), refresh the procedures, shims and hooks, and say what
+                              changed. Exits 0 with no account (it says what to do), 2 when offline.
+sibyl autosave [on|off|every N]
+                              Pro automatic save: every N minutes of active work (30 to 240, default
+                              60). On the free plan the setting is kept for the day you upgrade.
+sibyl email                   Show your account email: confirmed, not confirmed, or none.
+sibyl email add <address>     Send a code to a new address, then confirm it.
+sibyl email verify            Send a code to the address you activated with, then confirm it.
+sibyl email confirm <code>    Confirm a code from the email (for scripts and non-interactive shells).
+sibyl claim <cs_...>          Link a card purchase from sibyllabs.org/pro to this account.
+sibyl migrate                 Guided onboarding: back up your existing memory/agent files, wire Sibyl
+                              into every detected harness, populate Sibyl Memory from the backup, and
+                              optionally slim the instruction files it found (CLAUDE.md, AGENTS.md,
+                              .cursorrules, ...). Backup-first, never destructive.
+sibyl setup [target]          Wire Sibyl as the memory provider for Hermes, Claude Code, and/or Codex,
+                              and install the save and debloat procedures for each.
+                              target is one of: hermes | claude-code | codex (default: detect all).
+sibyl save                    Save: --fact "<text>" writes one fact; --status shows the last save; bare
+                              prints how to run the save procedure in your agent. --capsule on Pro.
+sibyl debloat                 Measure the instruction files your agent loads every start (--fyi, --json);
+                              plan | apply [<file>] | auto <file> | manual <file> | undo [<file>].
+sibyl skills                  install | status | reset <SAVE.md|DEBLOAT.md> | uninstall (run it before pip uninstall).
+sibyl reminders               on | off | quiet (save and debloat reminders; quiet silences Pro reports).
+sibyl status                  Show local credentials, DB size, this computer's access, and the server's
+                              view of your tier.
+sibyl whoami                  One-line account summary (masked by default).
+sibyl devices                 List the devices (active tokens) bound to your account, with the
+                              account's computer limit when the api sends it (Free 1, Pro up to 10).
+sibyl devices revoke N        Revoke a device by index (run `sibyl devices` to see the indexes).
+sibyl dashboard               Open the account page at account.sibyllabs.org (no token in the URL; you
+                              sign in there). Shows `sibyl status` while the page is not open yet.
+sibyl upgrade                 Open the tier/billing flow: the account billing page when the server offers
+                              it, otherwise the stake / USDC page through a one-time link.
+sibyl update                  Check PyPI for newer releases of the installed Sibyl packages: cli, client,
+                              hermes, the MCP server, and langgraph when installed.
+sibyl update --apply          Update the installed Sibyl packages in place (pip install -U), the MCP server
+                              included; never installs one you do not have. This is the
+                              canonical way to update the plugin, distinct from `sibyl upgrade` (which is
+                              the tier/billing flow, not a package update).
+sibyl health                  Run the SibylMemoryProvider self-check (schema version, DB path, tenant,
+                              entitlement state, pinned key ids).
+sibyl logout                  Sign this computer out: revoke it on the server, remove credentials.json and
+                              entitlement.json (your memory.db is left untouched).
+sibyl memory list [category]  List stored entities, optionally filtered by category (--limit N).
+                              `sibyl memory` never needs an account: your local data is always yours to read.
+sibyl memory search <query>   Full-text search across entities, state, reference, and journal (--limit N).
+sibyl memory recall <cat> <name>
+                              Recall a single entity by category + name.
+sibyl memory adopt [--yes]    Move memory written on this computer before sign-in into your account
+                              (local, one transaction, nothing deleted; asks first if the store has
+                              held another account). `sibyl init` does this on the first sign-in.
+```
+
+## Migrate (guided onboarding)
+
+```bash
+$ sibyl migrate
+```
+
+`sibyl migrate` moves your accumulated agent memory into Sibyl without risking
+your existing files:
+
+1. **Back up first.** Every memory/agent file it finds (`CLAUDE.md`,
+   `AGENTS.md`, `.codex/config.toml`, `.hermes/*`, and similar) is copied to a
+   timestamped backup folder and byte-verified before anything else happens.
+2. **Wire Sibyl** into every detected harness — Claude Code (via
+   `claude mcp add --scope user`), Codex (via `~/.codex/config.toml`), Hermes.
+3. **Extract** — it prints a prompt you run in your own agent. The agent reads
+   only from the backup and writes structured memory through the `sibyl-memory`
+   tool. The extraction runs locally on your machine; Sibyl Labs never sees your
+   files or memory.
+4. **Verify** the new entries that landed in your local DB.
+5. **Optionally trim** the instruction files it found (`CLAUDE.md`, `AGENTS.md`,
+   `.cursorrules`, ...), one question per file, only if you confirm and only because
+   a verified backup of that file exists. Configuration files are never trimmed. Your
+   full pre-migration files are always preserved.
+
+Flags: `--backup-dir PATH` (default: home), `--no-debloat` (skip the trim
+step), `--yes` (skip the initial confirm; the trim step still asks separately).
+
+> No warranty. Keep your backup until you've confirmed everything migrated.
+> Sibyl Labs is not responsible for data loss.
+
+## Activation
+
+```bash
+$ sibyl init
+
+─ activation ───────────────────────────────────────────────
+two paths · pick whichever fits your device
+
+  Session          a1b2c3d4…e5f6
+  Code             437 480  (use this in the email panel)
+  Opening          https://auth.sibyllabs.org/a1b2c3d4-…
+
+  desktop wallet · or email + code
+  this terminal will pick up automatically when you bind.
+
+  ⠙ watching the network for your bind … 9:59 left
+```
+
+The browser opens the sign-in page. Sign in with your email and the code shown in the terminal, or with a desktop wallet (when the server offers it, a third path sends a small USDC amount from a mobile wallet). If you already have an account, `sibyl init` also prints an approve link on `account.sibyllabs.org`: open it on a computer that is already signed in and type the same code. The terminal picks up the moment the binding lands. Credentials are written to `~/.sibyl-memory/credentials.json` at mode 0600, and this computer's signed access file to `~/.sibyl-memory/entitlement.json` (0600).
+
+An account is required for agents to use memory (MCP, Hermes, LangGraph, the SDK). `sibyl init` is the sign-in; there is no separate login command. The access pass is re-checked about once a day (and at the end of a paid plan) and keeps working offline for up to 14 days. Memory written on this computer before you signed in moves into your account at that first sign-in (on this computer only); if the store has held another account, `sibyl init` leaves it and `sibyl memory adopt` asks first.
+
+## Email
+
+Every account needs a confirmed email for receipts, security notices, purchases and recovery.
+Your local memory works either way. Wallet activation stays available.
+
+```bash
+$ sibyl email add you@example.com
+  code sent to y***@e***.com. it expires in 10 minutes.
+  code from the email: 123456
+  ✓ Email confirmed. Your account is complete.
+```
+
+`sibyl email verify` confirms the address you activated with. Confirming from the terminal keeps
+this computer signed in and signs out any other computer that was set up with the address before
+you confirmed it.
+
+## Upgrade
+
+Free is 5 MB of local memory. Pro removes the cap: $12/month or $108/year (plus applicable tax by card), bought at
+`sibyllabs.org/checkout` or through `sibyl upgrade`. Holding 100,000 $SIBYL staked also gives Pro.
+
+```bash
+$ sibyl upgrade
+```
+
+`sibyl upgrade` shows your account and current tier, then opens the purchase page in your
+browser: the account billing page (`https://account.sibyllabs.org/billing`; sign in there and buy
+Pro) when the server offers it, otherwise a one-time exchange link. No token ever rides the URL.
+It then waits for the plan change. A card purchase made elsewhere can be linked with
+`sibyl claim <cs_...>`.
+
+When the tier changes, the CLI rewrites `credentials.json` and clears `tier_cache.json` so your next write picks up the new entitlement without delay.
+
+## Status
+
+```bash
+$ sibyl status
+
+P L U G I N
+  Version          cli 0.5.0 · client 0.9.0
+L O C A L
+  Credentials      ~/.sibyl-memory/credentials.json
+  Account          a1b2c3d4-e5f6-4789-8abc-def012345678
+  Tier             Free
+  Wallet           0xa1b2c3d4e5f60718293a4b5c6d7e8f9012345678
+  Email            you@example.com
+  Issued           2026-05-16 18:12 UTC
+  Platform         Linux (x86_64)
+  DB path          ~/.sibyl-memory/memory.db
+  DB size          1,247,300 bytes (1.19 MB · 23.8% of free cap)
+
+A C C E S S
+  Access           active · re-checks in 24h
+  Tier cache       free (checked 2026-05-16 18:12 UTC)
+
+S E R V E R
+  Tier             Free
+  Source           free
+  Cap bytes        5,242,880
+  Email            not confirmed · run sibyl email verify
+  Dashboard        https://account.sibyllabs.org
+
+L I F E C Y C L E
+  save             last never · 0 writes since · manual (automatic on Pro)
+  context          no always-load files found here
+  skills           not installed · sibyl skills install
+  reminders        on
+```
+
+`$SIBYL held`, `Threshold` and `Qualified` rows appear under `SERVER` when the server reports staking details.
+
+`Email`, `Account` and `Dashboard` rows appear when the server reports them. On a paid plan a `Plan` row under `Access` shows the billing date when the server sends it: `Pro · renews 8 Oct 2027` for a renewing card plan, `Pro · ends 8 Oct 2027` when the plan is set to end (a cancellation, or a fixed term). The `Tier` rows always show the tier of this computer's current access pass.
+
+`sibyl status` runs one access check-in when online (the check-in is the status). The `Access` row reads one of:
+
+| Row | Meaning | What to do |
+|---|---|---|
+| `active · re-checks in <h>h` | this computer is signed in; the access pass is checked again in about <h> hours (not a billing date) | nothing |
+| `offline · <n> days of grace left · connect once to renew` | not reached the server lately | connect to the internet once |
+| `paused · offline too long · connect to the internet, or run sibyl init` | offline more than 14 days | connect; if it stays paused, `sibyl init` |
+| `setup not finished · connect to the internet once to finish setup` | credentials from before 0.9.0 and no check-in yet | connect once |
+| `signed out · run sibyl init` | signed out, revoked, or the sign-in expired | `sibyl init` |
+| `under review · email sibyl@sibyllabs.org` | the account is under review | email us |
+
+When the server cannot be reached, the account rows come from the last check-in, labeled `as of <date>`. With no credentials at all, `sibyl status` says so and that agents cannot use memory until you run `sibyl init`; your local data is kept.
+
+If `LOCAL` and `SERVER` tiers diverge, run `sibyl refresh` to pick up the server plan (or `sibyl init --force` to re-activate).
+
+## Environment overrides
+
+For internal testing only:
+
+```bash
+SIBYL_API_BASE=https://staging.example.internal sibyl init
+SIBYL_ACTIVATE_BASE=https://staging.example.internal/plugin/activate sibyl init
+SIBYL_UPGRADE_BASE=https://staging.example.internal/plugin/upgrade sibyl upgrade
+SIBYL_ACCOUNT_BASE=https://account.staging.example.internal sibyl dashboard
+SIBYL_NONINTERACTIVE=1 sibyl init     # never prompt (same as a non-TTY shell)
+```
+
+## Security
+
+- `credentials.json` and `entitlement.json` are written atomically at mode 0600.
+- The access file is verified offline against a public key pinned in `sibyl-memory-client`; it is never printed.
+- `session_token` is never printed in full: only a short slice.
+- No token rides a browser URL: `sibyl dashboard` opens the account page bare, and `sibyl upgrade`
+  uses a one-time exchange link.
+- No memory content ever transits these endpoints. `sibyl status` reads only the size of `memory.db`; `sibyl memory list|search|recall|adopt` read your memory locally and send none of it anywhere.
+- Wallet operations happen in the browser. The CLI sees only the resulting tier change.
+
+## Save and debloat
+
+**Save.** At the end of a session, or after a big block of work, your agent writes what happened
+into Sibyl Memory through the plugin's own tools: the decisions made and why (journal), the
+people, projects and products touched (entities), what to pick up next time and the open
+warnings (session state), the ranked priorities, and it closes what died (archive). A delta
+marker means a second save in the same day captures only what changed. It may offer to turn a
+repeated pattern into a reusable skill; that is offered, never forced. Nothing in a save leaves
+your machine.
+
+**Debloat.** Sibyl measures the files your agent loads on every session start (`CLAUDE.md`,
+`AGENTS.md`, `.cursorrules` and the rest of the scan set), deterministically (`chars/4`,
+labeled `MEASURED~`), and when they are heavy, trims the accreted history out of them without
+losing a byte: the history moves out and a one-line pointer stays. On the free plan the history
+moves to a sibling `*-history` file. On Pro it is stored in Sibyl Memory as a reference document,
+so it stays searchable, and the measurement and trim run by themselves under a policy you set
+once.
+
+| | Free (activated account) | Pro |
+|---|---|---|
+| The procedures in `~/.sibyl-memory/skills/` (`SAVE.md`, `DEBLOAT.md`), `/sibyl-save` and `/sibyl-debloat` in Claude Code, skills in Hermes and Codex, a block in Codex's `AGENTS.md`, the `save` and `debloat` MCP prompts | yes | yes |
+| `sibyl save`, `sibyl debloat` (measure, plan, apply, undo) | yes | yes |
+| Reminders (one quiet line; `sibyl reminders off`) | yes | replaced by a one-line report of what ran |
+| Where trimmed history goes | a sibling `*-history` file | Sibyl Memory, plus a byte-verified backup |
+| Automatic debloat | no | yes: `propose` by default; a file is trimmed by itself only after you run `sibyl debloat auto <file>` (that file at its path, never the same name elsewhere) |
+| Automatic save by active time: once early (after 5 memory writes or a compaction), then about every 60 minutes of active work, only when there is something to save, at most 8 a session and 12 a day (`sibyl autosave every <30-240>` or `sibyl autosave off`). Claude Code: the Stop hook asks your agent to run the save procedure headless (a scripted `claude -p` run is never asked); Cursor, Codex and other MCP hosts: a `notice` on the next tool result; Hermes: a note in the next prefetch. A session capsule (counts only) at compaction and session end. Each automatic save is one extra model turn that reads and writes memory | no | yes |
+| Skill proposals: Sibyl finds repeated work in your journal (locally, no network), names up to 3 at a session start at most once a day, and creates nothing without a yes (`/sibyl-save curate`, or `sibyl skills proposals accept <id>`, which writes the skill for Claude Code, Codex and Hermes) | no (`/sibyl-save` still offers skills when you run it) | yes |
+
+The procedures are vendored, with attribution, from the public MIT repos
+[sibyl-save](https://github.com/Sibyl-Labs/sibyl-save) and
+[debloat](https://github.com/Sibyl-Labs/debloat); both stay standalone and account-free.
+
+Uninstalling: run `sibyl skills uninstall` first. It removes the Claude Code hooks in
+`~/.claude/settings.json`, the skill shims and the Codex block (files you edited are kept); then
+`pip uninstall` the packages. The hooks call this package's `sibyl` command: if the package goes
+first they exit quietly, but they stay in your settings until you reinstall and run
+`sibyl skills uninstall`, or delete the five `sibyl hook` entries by hand.
+
+Privacy: the lifecycle reads your instruction files to measure and trim them locally; no file
+content and no conversation content ever leaves your machine.
+
+Forks: a gate-stripped fork can run the lifecycle code locally (MIT allows it). It gains nothing
+hosted, and its trims land in a store the official path cannot recognize as Pro. No file, flag
+or environment variable turns the automation on for a free account.
+
+Commands: `sibyl save` (`--fact`, `--status`, `--capsule` on Pro), `sibyl debloat` (`--fyi`,
+`--json`, `plan`, `apply [<file>]`, `auto <file>`, `manual <file>`, `undo [<file>]`),
+`sibyl skills install|status|reset|uninstall`, `sibyl skills proposals [show|accept|reject|mute|unmute]`
+(Pro), `sibyl autosave [on|off|every <minutes>]`, `sibyl reminders on|off|quiet`. `sibyl setup`
+installs the procedures and wires them: Claude Code gets the two skills plus five hooks in
+`~/.claude/settings.json` (`sibyl hook <event>`, installed by setup, not for manual use; any
+other hook you have is left alone; each hook exits 0 quietly if the `sibyl` it names is gone),
+Codex gets a marked block in `~/.codex/AGENTS.md` and two skills in `~/.codex/skills/`, Hermes
+gets two skills in `$HERMES_HOME/skills/`. `sibyl debloat auto <file>` authorizes that one file
+at its path. On Pro the Stop hook asks the agent to save once early (after 5 memory writes or a
+compaction), then about every hour of active work (`sibyl autosave`). `sibyl migrate` now slims the instruction files it
+found (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, ...), one question per file.
+
+## License
+
+MIT.

sibyl_memory_cli-0.5.0/README.md

@@ -0,0 +1,300 @@
+# sibyl-memory-cli
+
+Command-line interface for the **Sibyl Memory Plugin**.
+
+```bash
+pip install sibyl-memory-cli
+```
+
+Sibyl Memory runs on Linux, macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is not supported.
+
+This pulls in `sibyl-memory-client` (the local SDK) and `sibyl-memory-hermes` (the Hermes provider) automatically.
+
+## Commands
+
+```
+sibyl --version               Print the installed versions: cli, client, mcp, hermes, langgraph.
+sibyl init                    Open the browser activation page. Writes ~/.sibyl-memory/credentials.json.
+                              Afterwards it offers to add or confirm your email (terminal only).
+sibyl init --no-email         Activate without the email prompt.
+sibyl init --replace          Re-activate this computer in place of its earlier sign-in (re-activation
+                              never uses a second computer slot). At the account's computer limit
+                              (Free: one computer) init lists the computers signed in and offers to
+                              sign one out on the account page.
+sibyl refresh                 Check your account now (an upgrade, a staking unlock or a plan change
+                              lands at once), refresh the procedures, shims and hooks, and say what
+                              changed. Exits 0 with no account (it says what to do), 2 when offline.
+sibyl autosave [on|off|every N]
+                              Pro automatic save: every N minutes of active work (30 to 240, default
+                              60). On the free plan the setting is kept for the day you upgrade.
+sibyl email                   Show your account email: confirmed, not confirmed, or none.
+sibyl email add <address>     Send a code to a new address, then confirm it.
+sibyl email verify            Send a code to the address you activated with, then confirm it.
+sibyl email confirm <code>    Confirm a code from the email (for scripts and non-interactive shells).
+sibyl claim <cs_...>          Link a card purchase from sibyllabs.org/pro to this account.
+sibyl migrate                 Guided onboarding: back up your existing memory/agent files, wire Sibyl
+                              into every detected harness, populate Sibyl Memory from the backup, and
+                              optionally slim the instruction files it found (CLAUDE.md, AGENTS.md,
+                              .cursorrules, ...). Backup-first, never destructive.
+sibyl setup [target]          Wire Sibyl as the memory provider for Hermes, Claude Code, and/or Codex,
+                              and install the save and debloat procedures for each.
+                              target is one of: hermes | claude-code | codex (default: detect all).
+sibyl save                    Save: --fact "<text>" writes one fact; --status shows the last save; bare
+                              prints how to run the save procedure in your agent. --capsule on Pro.
+sibyl debloat                 Measure the instruction files your agent loads every start (--fyi, --json);
+                              plan | apply [<file>] | auto <file> | manual <file> | undo [<file>].
+sibyl skills                  install | status | reset <SAVE.md|DEBLOAT.md> | uninstall (run it before pip uninstall).
+sibyl reminders               on | off | quiet (save and debloat reminders; quiet silences Pro reports).
+sibyl status                  Show local credentials, DB size, this computer's access, and the server's
+                              view of your tier.
+sibyl whoami                  One-line account summary (masked by default).
+sibyl devices                 List the devices (active tokens) bound to your account, with the
+                              account's computer limit when the api sends it (Free 1, Pro up to 10).
+sibyl devices revoke N        Revoke a device by index (run `sibyl devices` to see the indexes).
+sibyl dashboard               Open the account page at account.sibyllabs.org (no token in the URL; you
+                              sign in there). Shows `sibyl status` while the page is not open yet.
+sibyl upgrade                 Open the tier/billing flow: the account billing page when the server offers
+                              it, otherwise the stake / USDC page through a one-time link.
+sibyl update                  Check PyPI for newer releases of the installed Sibyl packages: cli, client,
+                              hermes, the MCP server, and langgraph when installed.
+sibyl update --apply          Update the installed Sibyl packages in place (pip install -U), the MCP server
+                              included; never installs one you do not have. This is the
+                              canonical way to update the plugin, distinct from `sibyl upgrade` (which is
+                              the tier/billing flow, not a package update).
+sibyl health                  Run the SibylMemoryProvider self-check (schema version, DB path, tenant,
+                              entitlement state, pinned key ids).
+sibyl logout                  Sign this computer out: revoke it on the server, remove credentials.json and
+                              entitlement.json (your memory.db is left untouched).
+sibyl memory list [category]  List stored entities, optionally filtered by category (--limit N).
+                              `sibyl memory` never needs an account: your local data is always yours to read.
+sibyl memory search <query>   Full-text search across entities, state, reference, and journal (--limit N).
+sibyl memory recall <cat> <name>
+                              Recall a single entity by category + name.
+sibyl memory adopt [--yes]    Move memory written on this computer before sign-in into your account
+                              (local, one transaction, nothing deleted; asks first if the store has
+                              held another account). `sibyl init` does this on the first sign-in.
+```
+
+## Migrate (guided onboarding)
+
+```bash
+$ sibyl migrate
+```
+
+`sibyl migrate` moves your accumulated agent memory into Sibyl without risking
+your existing files:
+
+1. **Back up first.** Every memory/agent file it finds (`CLAUDE.md`,
+   `AGENTS.md`, `.codex/config.toml`, `.hermes/*`, and similar) is copied to a
+   timestamped backup folder and byte-verified before anything else happens.
+2. **Wire Sibyl** into every detected harness — Claude Code (via
+   `claude mcp add --scope user`), Codex (via `~/.codex/config.toml`), Hermes.
+3. **Extract** — it prints a prompt you run in your own agent. The agent reads
+   only from the backup and writes structured memory through the `sibyl-memory`
+   tool. The extraction runs locally on your machine; Sibyl Labs never sees your
+   files or memory.
+4. **Verify** the new entries that landed in your local DB.
+5. **Optionally trim** the instruction files it found (`CLAUDE.md`, `AGENTS.md`,
+   `.cursorrules`, ...), one question per file, only if you confirm and only because
+   a verified backup of that file exists. Configuration files are never trimmed. Your
+   full pre-migration files are always preserved.
+
+Flags: `--backup-dir PATH` (default: home), `--no-debloat` (skip the trim
+step), `--yes` (skip the initial confirm; the trim step still asks separately).
+
+> No warranty. Keep your backup until you've confirmed everything migrated.
+> Sibyl Labs is not responsible for data loss.
+
+## Activation
+
+```bash
+$ sibyl init
+
+─ activation ───────────────────────────────────────────────
+two paths · pick whichever fits your device
+
+  Session          a1b2c3d4…e5f6
+  Code             437 480  (use this in the email panel)
+  Opening          https://auth.sibyllabs.org/a1b2c3d4-…
+
+  desktop wallet · or email + code
+  this terminal will pick up automatically when you bind.
+
+  ⠙ watching the network for your bind … 9:59 left
+```
+
+The browser opens the sign-in page. Sign in with your email and the code shown in the terminal, or with a desktop wallet (when the server offers it, a third path sends a small USDC amount from a mobile wallet). If you already have an account, `sibyl init` also prints an approve link on `account.sibyllabs.org`: open it on a computer that is already signed in and type the same code. The terminal picks up the moment the binding lands. Credentials are written to `~/.sibyl-memory/credentials.json` at mode 0600, and this computer's signed access file to `~/.sibyl-memory/entitlement.json` (0600).
+
+An account is required for agents to use memory (MCP, Hermes, LangGraph, the SDK). `sibyl init` is the sign-in; there is no separate login command. The access pass is re-checked about once a day (and at the end of a paid plan) and keeps working offline for up to 14 days. Memory written on this computer before you signed in moves into your account at that first sign-in (on this computer only); if the store has held another account, `sibyl init` leaves it and `sibyl memory adopt` asks first.
+
+## Email
+
+Every account needs a confirmed email for receipts, security notices, purchases and recovery.
+Your local memory works either way. Wallet activation stays available.
+
+```bash
+$ sibyl email add you@example.com
+  code sent to y***@e***.com. it expires in 10 minutes.
+  code from the email: 123456
+  ✓ Email confirmed. Your account is complete.
+```
+
+`sibyl email verify` confirms the address you activated with. Confirming from the terminal keeps
+this computer signed in and signs out any other computer that was set up with the address before
+you confirmed it.
+
+## Upgrade
+
+Free is 5 MB of local memory. Pro removes the cap: $12/month or $108/year (plus applicable tax by card), bought at
+`sibyllabs.org/checkout` or through `sibyl upgrade`. Holding 100,000 $SIBYL staked also gives Pro.
+
+```bash
+$ sibyl upgrade
+```
+
+`sibyl upgrade` shows your account and current tier, then opens the purchase page in your
+browser: the account billing page (`https://account.sibyllabs.org/billing`; sign in there and buy
+Pro) when the server offers it, otherwise a one-time exchange link. No token ever rides the URL.
+It then waits for the plan change. A card purchase made elsewhere can be linked with
+`sibyl claim <cs_...>`.
+
+When the tier changes, the CLI rewrites `credentials.json` and clears `tier_cache.json` so your next write picks up the new entitlement without delay.
+
+## Status
+
+```bash
+$ sibyl status
+
+P L U G I N
+  Version          cli 0.5.0 · client 0.9.0
+L O C A L
+  Credentials      ~/.sibyl-memory/credentials.json
+  Account          a1b2c3d4-e5f6-4789-8abc-def012345678
+  Tier             Free
+  Wallet           0xa1b2c3d4e5f60718293a4b5c6d7e8f9012345678
+  Email            you@example.com
+  Issued           2026-05-16 18:12 UTC
+  Platform         Linux (x86_64)
+  DB path          ~/.sibyl-memory/memory.db
+  DB size          1,247,300 bytes (1.19 MB · 23.8% of free cap)
+
+A C C E S S
+  Access           active · re-checks in 24h
+  Tier cache       free (checked 2026-05-16 18:12 UTC)
+
+S E R V E R
+  Tier             Free
+  Source           free
+  Cap bytes        5,242,880
+  Email            not confirmed · run sibyl email verify
+  Dashboard        https://account.sibyllabs.org
+
+L I F E C Y C L E
+  save             last never · 0 writes since · manual (automatic on Pro)
+  context          no always-load files found here
+  skills           not installed · sibyl skills install
+  reminders        on
+```
+
+`$SIBYL held`, `Threshold` and `Qualified` rows appear under `SERVER` when the server reports staking details.
+
+`Email`, `Account` and `Dashboard` rows appear when the server reports them. On a paid plan a `Plan` row under `Access` shows the billing date when the server sends it: `Pro · renews 8 Oct 2027` for a renewing card plan, `Pro · ends 8 Oct 2027` when the plan is set to end (a cancellation, or a fixed term). The `Tier` rows always show the tier of this computer's current access pass.
+
+`sibyl status` runs one access check-in when online (the check-in is the status). The `Access` row reads one of:
+
+| Row | Meaning | What to do |
+|---|---|---|
+| `active · re-checks in <h>h` | this computer is signed in; the access pass is checked again in about <h> hours (not a billing date) | nothing |
+| `offline · <n> days of grace left · connect once to renew` | not reached the server lately | connect to the internet once |
+| `paused · offline too long · connect to the internet, or run sibyl init` | offline more than 14 days | connect; if it stays paused, `sibyl init` |
+| `setup not finished · connect to the internet once to finish setup` | credentials from before 0.9.0 and no check-in yet | connect once |
+| `signed out · run sibyl init` | signed out, revoked, or the sign-in expired | `sibyl init` |
+| `under review · email sibyl@sibyllabs.org` | the account is under review | email us |
+
+When the server cannot be reached, the account rows come from the last check-in, labeled `as of <date>`. With no credentials at all, `sibyl status` says so and that agents cannot use memory until you run `sibyl init`; your local data is kept.
+
+If `LOCAL` and `SERVER` tiers diverge, run `sibyl refresh` to pick up the server plan (or `sibyl init --force` to re-activate).
+
+## Environment overrides
+
+For internal testing only:
+
+```bash
+SIBYL_API_BASE=https://staging.example.internal sibyl init
+SIBYL_ACTIVATE_BASE=https://staging.example.internal/plugin/activate sibyl init
+SIBYL_UPGRADE_BASE=https://staging.example.internal/plugin/upgrade sibyl upgrade
+SIBYL_ACCOUNT_BASE=https://account.staging.example.internal sibyl dashboard
+SIBYL_NONINTERACTIVE=1 sibyl init     # never prompt (same as a non-TTY shell)
+```
+
+## Security
+
+- `credentials.json` and `entitlement.json` are written atomically at mode 0600.
+- The access file is verified offline against a public key pinned in `sibyl-memory-client`; it is never printed.
+- `session_token` is never printed in full: only a short slice.
+- No token rides a browser URL: `sibyl dashboard` opens the account page bare, and `sibyl upgrade`
+  uses a one-time exchange link.
+- No memory content ever transits these endpoints. `sibyl status` reads only the size of `memory.db`; `sibyl memory list|search|recall|adopt` read your memory locally and send none of it anywhere.
+- Wallet operations happen in the browser. The CLI sees only the resulting tier change.
+
+## Save and debloat
+
+**Save.** At the end of a session, or after a big block of work, your agent writes what happened
+into Sibyl Memory through the plugin's own tools: the decisions made and why (journal), the
+people, projects and products touched (entities), what to pick up next time and the open
+warnings (session state), the ranked priorities, and it closes what died (archive). A delta
+marker means a second save in the same day captures only what changed. It may offer to turn a
+repeated pattern into a reusable skill; that is offered, never forced. Nothing in a save leaves
+your machine.
+
+**Debloat.** Sibyl measures the files your agent loads on every session start (`CLAUDE.md`,
+`AGENTS.md`, `.cursorrules` and the rest of the scan set), deterministically (`chars/4`,
+labeled `MEASURED~`), and when they are heavy, trims the accreted history out of them without
+losing a byte: the history moves out and a one-line pointer stays. On the free plan the history
+moves to a sibling `*-history` file. On Pro it is stored in Sibyl Memory as a reference document,
+so it stays searchable, and the measurement and trim run by themselves under a policy you set
+once.
+
+| | Free (activated account) | Pro |
+|---|---|---|
+| The procedures in `~/.sibyl-memory/skills/` (`SAVE.md`, `DEBLOAT.md`), `/sibyl-save` and `/sibyl-debloat` in Claude Code, skills in Hermes and Codex, a block in Codex's `AGENTS.md`, the `save` and `debloat` MCP prompts | yes | yes |
+| `sibyl save`, `sibyl debloat` (measure, plan, apply, undo) | yes | yes |
+| Reminders (one quiet line; `sibyl reminders off`) | yes | replaced by a one-line report of what ran |
+| Where trimmed history goes | a sibling `*-history` file | Sibyl Memory, plus a byte-verified backup |
+| Automatic debloat | no | yes: `propose` by default; a file is trimmed by itself only after you run `sibyl debloat auto <file>` (that file at its path, never the same name elsewhere) |
+| Automatic save by active time: once early (after 5 memory writes or a compaction), then about every 60 minutes of active work, only when there is something to save, at most 8 a session and 12 a day (`sibyl autosave every <30-240>` or `sibyl autosave off`). Claude Code: the Stop hook asks your agent to run the save procedure headless (a scripted `claude -p` run is never asked); Cursor, Codex and other MCP hosts: a `notice` on the next tool result; Hermes: a note in the next prefetch. A session capsule (counts only) at compaction and session end. Each automatic save is one extra model turn that reads and writes memory | no | yes |
+| Skill proposals: Sibyl finds repeated work in your journal (locally, no network), names up to 3 at a session start at most once a day, and creates nothing without a yes (`/sibyl-save curate`, or `sibyl skills proposals accept <id>`, which writes the skill for Claude Code, Codex and Hermes) | no (`/sibyl-save` still offers skills when you run it) | yes |
+
+The procedures are vendored, with attribution, from the public MIT repos
+[sibyl-save](https://github.com/Sibyl-Labs/sibyl-save) and
+[debloat](https://github.com/Sibyl-Labs/debloat); both stay standalone and account-free.
+
+Uninstalling: run `sibyl skills uninstall` first. It removes the Claude Code hooks in
+`~/.claude/settings.json`, the skill shims and the Codex block (files you edited are kept); then
+`pip uninstall` the packages. The hooks call this package's `sibyl` command: if the package goes
+first they exit quietly, but they stay in your settings until you reinstall and run
+`sibyl skills uninstall`, or delete the five `sibyl hook` entries by hand.
+
+Privacy: the lifecycle reads your instruction files to measure and trim them locally; no file
+content and no conversation content ever leaves your machine.
+
+Forks: a gate-stripped fork can run the lifecycle code locally (MIT allows it). It gains nothing
+hosted, and its trims land in a store the official path cannot recognize as Pro. No file, flag
+or environment variable turns the automation on for a free account.
+
+Commands: `sibyl save` (`--fact`, `--status`, `--capsule` on Pro), `sibyl debloat` (`--fyi`,
+`--json`, `plan`, `apply [<file>]`, `auto <file>`, `manual <file>`, `undo [<file>]`),
+`sibyl skills install|status|reset|uninstall`, `sibyl skills proposals [show|accept|reject|mute|unmute]`
+(Pro), `sibyl autosave [on|off|every <minutes>]`, `sibyl reminders on|off|quiet`. `sibyl setup`
+installs the procedures and wires them: Claude Code gets the two skills plus five hooks in
+`~/.claude/settings.json` (`sibyl hook <event>`, installed by setup, not for manual use; any
+other hook you have is left alone; each hook exits 0 quietly if the `sibyl` it names is gone),
+Codex gets a marked block in `~/.codex/AGENTS.md` and two skills in `~/.codex/skills/`, Hermes
+gets two skills in `$HERMES_HOME/skills/`. `sibyl debloat auto <file>` authorizes that one file
+at its path. On Pro the Stop hook asks the agent to save once early (after 5 memory writes or a
+compaction), then about every hour of active work (`sibyl autosave`). `sibyl migrate` now slims the instruction files it
+found (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, ...), one question per file.
+
+## License
+
+MIT.