sibyllabs commited on
Commit
a6a68bb
·
0 Parent(s):

Snapshot mirror of Sibyl-Labs/Sibyl-Memory@8d15cd20b37ce79f39953f684b88b17b2f8e753e

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. .dockerignore +37 -0
  2. .github/ISSUE_TEMPLATE/bug_report.yml +66 -0
  3. .github/ISSUE_TEMPLATE/config.yml +8 -0
  4. .github/ISSUE_TEMPLATE/feature_request.yml +22 -0
  5. .github/pull_request_template.md +17 -0
  6. .github/workflows/hf-mirror.yml +65 -0
  7. .github/workflows/macos-framework-smoke.yml +139 -0
  8. .github/workflows/tests.yml +91 -0
  9. .gitignore +50 -0
  10. CONTRIBUTING.md +53 -0
  11. Dockerfile +39 -0
  12. LICENSE +21 -0
  13. README.md +235 -0
  14. docker-compose.yml +25 -0
  15. docs/diagrams/setup-mcp-rail.svg +140 -0
  16. docs/diagrams/setup-sdk-rail.svg +153 -0
  17. docs/release-0.8.0-notes.md +262 -0
  18. sibyl-memory-cli/.gitignore +1 -0
  19. sibyl-memory-cli/CHANGELOG.md +1560 -0
  20. sibyl-memory-cli/LICENSE +21 -0
  21. sibyl-memory-cli/README.md +313 -0
  22. sibyl-memory-cli/pyproject.toml +53 -0
  23. sibyl-memory-cli/src/sibyl_memory_cli/__init__.py +40 -0
  24. sibyl-memory-cli/src/sibyl_memory_cli/_account_gate.py +545 -0
  25. sibyl-memory-cli/src/sibyl_memory_cli/_aesthetic.py +251 -0
  26. sibyl-memory-cli/src/sibyl_memory_cli/_banner.py +114 -0
  27. sibyl-memory-cli/src/sibyl_memory_cli/_entry.py +26 -0
  28. sibyl-memory-cli/src/sibyl_memory_cli/_handoff.py +75 -0
  29. sibyl-memory-cli/src/sibyl_memory_cli/_timefmt.py +61 -0
  30. sibyl-memory-cli/src/sibyl_memory_cli/cli.py +0 -0
  31. sibyl-memory-cli/src/sibyl_memory_cli/doctor.py +682 -0
  32. sibyl-memory-cli/src/sibyl_memory_cli/hooks.py +502 -0
  33. sibyl-memory-cli/src/sibyl_memory_cli/lifecycle_cli.py +1233 -0
  34. sibyl-memory-cli/src/sibyl_memory_cli/migrate.py +742 -0
  35. sibyl-memory-cli/src/sibyl_memory_cli/setup.py +0 -0
  36. sibyl-memory-cli/tests/_harness_fixtures.py +52 -0
  37. sibyl-memory-cli/tests/conftest.py +203 -0
  38. sibyl-memory-cli/tests/fixtures/deepseek/bom.yml +2 -0
  39. sibyl-memory-cli/tests/fixtures/deepseek/broken.yml +2 -0
  40. sibyl-memory-cli/tests/fixtures/deepseek/broken_with_fake_value.yml +3 -0
  41. sibyl-memory-cli/tests/fixtures/deepseek/comment_only.yml +2 -0
  42. sibyl-memory-cli/tests/fixtures/deepseek/crlf.yml +3 -0
  43. sibyl-memory-cli/tests/fixtures/deepseek/debian_dsh_home/dsh.conf +1 -0
  44. sibyl-memory-cli/tests/fixtures/deepseek/debian_dsh_home/group/all +1 -0
  45. sibyl-memory-cli/tests/fixtures/deepseek/debian_dsh_home/machines.list +2 -0
  46. sibyl-memory-cli/tests/fixtures/deepseek/duplicate_in_file.yml +11 -0
  47. sibyl-memory-cli/tests/fixtures/deepseek/flow_list.yml +1 -0
  48. sibyl-memory-cli/tests/fixtures/deepseek/foreign_flow_row.yml +2 -0
  49. sibyl-memory-cli/tests/fixtures/deepseek/foreign_same_id.yml +16 -0
  50. sibyl-memory-cli/tests/fixtures/deepseek/indented_list.yml +2 -0
.dockerignore ADDED
@@ -0,0 +1,37 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Keep the Docker build context minimal and secret-free.
2
+ # VCS + CI
3
+ .git
4
+ .github
5
+ # Python build/test cruft
6
+ **/__pycache__/
7
+ **/*.py[cod]
8
+ **/*.egg-info/
9
+ **/build/
10
+ **/dist/
11
+ **/.pytest_cache/
12
+ **/.mypy_cache/
13
+ **/.ruff_cache/
14
+ **/.coverage
15
+ **/htmlcov/
16
+ .tox/
17
+ # Environments + secrets (never in the image)
18
+ **/.venv/
19
+ **/venv/
20
+ **/env/
21
+ **/.env
22
+ **/.env.*
23
+ !**/.env.example
24
+ # Local databases / state (never in the image)
25
+ **/*.db
26
+ **/*.sqlite
27
+ **/*.sqlite3
28
+ .sibyl-memory/
29
+ # Private schema (never publish)
30
+ sibyl-plugin-schema/
31
+ # Docs + editor
32
+ docs/
33
+ .vscode/
34
+ .idea/
35
+ # Other monorepo packages the MCP image does not need in context
36
+ sibyl-memory-cli/
37
+ sibyl-memory-langgraph/
.github/ISSUE_TEMPLATE/bug_report.yml ADDED
@@ -0,0 +1,66 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ name: Bug report
2
+ description: Something in Sibyl Memory does not work as documented
3
+ labels: ["bug"]
4
+ body:
5
+ - type: markdown
6
+ attributes:
7
+ value: |
8
+ Thanks for the report. Never paste the contents of `~/.sibyl-memory/credentials.json` or any token.
9
+ Security issues: email sibyl@sibyllabs.org instead of opening an issue.
10
+ - type: textarea
11
+ id: what
12
+ attributes:
13
+ label: What happened
14
+ description: What you ran, what you expected, and what you got instead.
15
+ validations:
16
+ required: true
17
+ - type: textarea
18
+ id: repro
19
+ attributes:
20
+ label: Steps to reproduce
21
+ placeholder: |
22
+ 1. pip install sibyl-memory-cli
23
+ 2. sibyl setup cursor
24
+ 3. ...
25
+ validations:
26
+ required: true
27
+ - type: textarea
28
+ id: output
29
+ attributes:
30
+ label: Full error output
31
+ render: shell
32
+ - type: textarea
33
+ id: versions
34
+ attributes:
35
+ label: Versions
36
+ description: Output of `sibyl status`, or `pip show sibyl-memory-client sibyl-memory-cli sibyl-memory-mcp sibyl-memory-hermes`.
37
+ render: shell
38
+ validations:
39
+ required: true
40
+ - type: dropdown
41
+ id: harness
42
+ attributes:
43
+ label: Harness
44
+ options:
45
+ - Claude Code
46
+ - Codex
47
+ - Cursor
48
+ - Grok Bot
49
+ - Hermes
50
+ - LangGraph
51
+ - Another MCP client
52
+ - Not harness-related
53
+ validations:
54
+ required: true
55
+ - type: input
56
+ id: platform
57
+ attributes:
58
+ label: OS and Python version
59
+ placeholder: macOS 15 (Apple Silicon), Python 3.11.9
60
+ validations:
61
+ required: true
62
+ - type: textarea
63
+ id: doctor
64
+ attributes:
65
+ label: sibyl doctor output (setup or MCP problems)
66
+ render: shell
.github/ISSUE_TEMPLATE/config.yml ADDED
@@ -0,0 +1,8 @@
 
 
 
 
 
 
 
 
 
1
+ blank_issues_enabled: false
2
+ contact_links:
3
+ - name: Documentation
4
+ url: https://docs.sibyllabs.org/memory/
5
+ about: Install, setup for each harness, the CLI, and tiers.
6
+ - name: Account or billing help
7
+ url: mailto:support@sibyllabs.org
8
+ about: Sign-in, plans and payments go to support, not the issue tracker.
.github/ISSUE_TEMPLATE/feature_request.yml ADDED
@@ -0,0 +1,22 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ name: Feature request
2
+ description: Suggest an improvement or a new integration
3
+ labels: ["enhancement"]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: The problem
9
+ description: What are you trying to do, and where does Sibyl Memory get in the way?
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: proposal
14
+ attributes:
15
+ label: What you would like
16
+ validations:
17
+ required: true
18
+ - type: input
19
+ id: harness
20
+ attributes:
21
+ label: Harness or framework it applies to
22
+ placeholder: Claude Code, Hermes, LangGraph, all
.github/pull_request_template.md ADDED
@@ -0,0 +1,17 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <!--
2
+ Thanks for the pull request. We do not merge outside code directly: real fixes and good
3
+ ideas are re-implemented in-house and shipped in the next release, with credit to you by
4
+ GitHub handle in the CHANGELOG and release notes. See CONTRIBUTING.md.
5
+ -->
6
+
7
+ ## What this fixes or adds
8
+
9
+ ## How to reproduce the problem (or see the feature)
10
+
11
+ ## Tests
12
+
13
+ - [ ] Added or updated a test that fails without this change
14
+ - [ ] Ran the package's tests with a throwaway HOME (`HOME=$(mktemp -d) pytest -q`)
15
+ - [ ] Works on Python 3.10 (no 3.11+ syntax or standard-library features)
16
+
17
+ Related issue:
.github/workflows/hf-mirror.yml ADDED
@@ -0,0 +1,65 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ name: Mirror to Hugging Face
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ mirror:
10
+ runs-on: ubuntu-latest
11
+ steps:
12
+ - name: Checkout (full history)
13
+ uses: actions/checkout@v4
14
+ with:
15
+ fetch-depth: 0
16
+
17
+ - name: Inject HF model-card frontmatter (runner-only; GitHub README stays clean)
18
+ run: |
19
+ printf '%s\n' \
20
+ '---' \
21
+ 'license: mit' \
22
+ 'tags:' \
23
+ ' - agent-memory' \
24
+ ' - long-term-memory' \
25
+ ' - llm' \
26
+ ' - ai-agents' \
27
+ ' - mcp' \
28
+ ' - retrieval' \
29
+ ' - sqlite' \
30
+ ' - rag' \
31
+ '---' \
32
+ '' \
33
+ '> **Read-only mirror of [`Sibyl-Labs/Sibyl-Memory`](https://github.com/Sibyl-Labs/Sibyl-Memory).** The canonical source is on GitHub. Install from PyPI: `pip install -U sibyl-memory-cli` · Docs: https://docs.sibyllabs.org/memory/ · Product: https://sibyllabs.org/plugin · Benchmarks: https://blog.sibylcap.com/beta-analysis' \
34
+ '' > README.hf.md
35
+ cat README.md >> README.hf.md
36
+ mv README.hf.md README.md
37
+ git config user.name sibyl
38
+ git config user.email sibyl@sibyllabs.org
39
+ git add README.md
40
+ git commit -q -m "hf: model-card frontmatter for the mirror" || echo "README unchanged"
41
+
42
+ - name: Push snapshot to Hugging Face Hub (retry on transient 429)
43
+ env:
44
+ HF_TOKEN: ${{ secrets.HF_TOKEN }}
45
+ run: |
46
+ # Token via credential helper (read from env at call time): never in the
47
+ # remote URL, argv, or any error message git might print.
48
+ git config credential.helper '!f() { echo "username=sibyllabs"; echo "password=${HF_TOKEN}"; }; f'
49
+ # HF is a read-only distribution mirror; its pre-receive hook rejects binary
50
+ # blobs found ANYWHERE in git history (e.g. the pip-cache blobs that briefly
51
+ # entered history in 2026-07). Push a single flattened SNAPSHOT of the current
52
+ # tree instead of full history: permanently immune to any historical blob, and
53
+ # history has no value on a mirror (canonical source + full git history live on
54
+ # GitHub; install is via PyPI). The snapshot carries the README frontmatter
55
+ # committed above.
56
+ git checkout -q --orphan hf-snapshot
57
+ git add -A
58
+ git commit -q -m "Snapshot mirror of Sibyl-Labs/Sibyl-Memory@${GITHUB_SHA:-main}"
59
+ for i in 1 2 3 4 5; do
60
+ if git push --force "https://huggingface.co/SibylLabsLLC/Sibyl-Memory" hf-snapshot:main; then
61
+ echo "mirror pushed on attempt $i"; exit 0
62
+ fi
63
+ echo "attempt $i failed (likely transient HF 429); backing off"; sleep $((i*15))
64
+ done
65
+ echo "all push attempts failed"; exit 1
.github/workflows/macos-framework-smoke.yml ADDED
@@ -0,0 +1,139 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # macOS framework-Python smoke (Sibyl-Labs/Sibyl-Memory#29 / PR #30). Installs
2
+ # the python.org "Framework" build, strips its CA store, proves the stdlib
3
+ # default context then cannot verify api.sibyllabs.org and https_context() can.
4
+ # Manual only: no macOS box on the lab side, so this is the publish gate.
5
+ name: macOS framework-Python smoke
6
+
7
+ on:
8
+ workflow_dispatch:
9
+
10
+ env:
11
+ # python.org universal2 installer. Refresh: newest 3.12.x pkg + shasum -a 256.
12
+ PY_URL: https://www.python.org/ftp/python/3.12.10/python-3.12.10-macos11.pkg
13
+ PY_SHA256: 8373e58da4ea146b3eb1c1f9834f19a319440b6b679b06050b1f9ee3237aa8e4
14
+ PY_FRAMEWORK: /Library/Frameworks/Python.framework/Versions/3.12/bin/python3
15
+ PROBE_URL: https://api.sibyllabs.org/api/plugin/health
16
+
17
+ jobs:
18
+ wheels:
19
+ name: build wheels
20
+ runs-on: ubuntu-latest
21
+ steps:
22
+ - uses: actions/checkout@v4
23
+ - uses: actions/setup-python@v5
24
+ with:
25
+ python-version: "3.12"
26
+ - run: python -m pip install --upgrade pip build
27
+ - name: build
28
+ run: |
29
+ set -eux
30
+ for pkg in sibyl-memory-client sibyl-memory-hermes sibyl-memory-mcp sibyl-memory-cli; do
31
+ python -m build --wheel --outdir dist "$pkg"
32
+ done
33
+ ls -la dist
34
+ - uses: actions/upload-artifact@v4
35
+ with:
36
+ name: wheels
37
+ path: dist/*.whl
38
+ if-no-files-found: error
39
+
40
+ smoke:
41
+ name: macOS framework Python
42
+ needs: wheels
43
+ runs-on: macos-latest
44
+ steps:
45
+ - uses: actions/download-artifact@v4
46
+ with:
47
+ name: wheels
48
+ path: dist
49
+
50
+ - name: install the python.org framework build (no Install Certificates.command)
51
+ run: |
52
+ set -eux
53
+ curl -fsSL -o python.pkg "$PY_URL"
54
+ echo "$PY_SHA256 python.pkg" | shasum -a 256 -c -
55
+ sudo installer -pkg python.pkg -target /
56
+ "$PY_FRAMEWORK" -VV
57
+
58
+ - name: install the built wheels into a venv
59
+ run: |
60
+ set -eux
61
+ "$PY_FRAMEWORK" -m venv "$RUNNER_TEMP/smoke"
62
+ "$RUNNER_TEMP/smoke/bin/python" -m pip install --upgrade pip
63
+ "$RUNNER_TEMP/smoke/bin/python" -m pip install --find-links dist dist/*.whl
64
+
65
+ - name: strip the pre-wired CA store (reproduce the report)
66
+ # The image already ran Install Certificates.command (etc/openssl holds a
67
+ # certifi symlink), so the stock context verifies and the report is NOT
68
+ # reproduced until it is removed. A fake pem would test a different bug.
69
+ run: |
70
+ set -eux
71
+ unset SSL_CERT_FILE SSL_CERT_DIR || true
72
+ env | grep -i '^SSL_' || true
73
+ PREFIX="$(dirname "$(dirname "$PY_FRAMEWORK")")"
74
+ ls -la "$PREFIX/etc/openssl" || true
75
+ mkdir -p "$RUNNER_TEMP/ca-backup"
76
+ sudo mv "$PREFIX/etc/openssl/cert.pem" "$RUNNER_TEMP/ca-backup/" || true
77
+ sudo mv "$PREFIX/etc/openssl/certs" "$RUNNER_TEMP/ca-backup/" || true
78
+ "$PY_FRAMEWORK" -c "import ssl; print(ssl.get_default_verify_paths()); print(ssl.OPENSSL_VERSION)"
79
+
80
+ - name: write the shared TLS classifier
81
+ run: |
82
+ cat > "$RUNNER_TEMP/probe.py" <<'PY'
83
+ import os, ssl, sys, urllib.error, urllib.request
84
+ UA = {"User-Agent": "sibyl-memory-smoke/1"}
85
+ def classify(e):
86
+ # An HTTPError is a real HTTP status, so the handshake SUCCEEDED
87
+ # (Cloudflare 403s our datacenter IP). Only a cert error is a TLS fail.
88
+ if isinstance(e, urllib.error.HTTPError):
89
+ return "TLS_OK"
90
+ if isinstance(e, urllib.error.URLError) and "CERTIFICATE_VERIFY_FAILED" in repr(e):
91
+ return "TLS_FAIL"
92
+ return "OTHER" # DNS, refused, timeout: never reached the TLS check
93
+ def probe(ctx):
94
+ req = urllib.request.Request(os.environ["PROBE_URL"], headers=UA)
95
+ try:
96
+ with urllib.request.urlopen(req, context=ctx, timeout=15) as r:
97
+ return "TLS_OK", r.status, r.read(120)
98
+ except urllib.error.HTTPError as e:
99
+ return "TLS_OK", e.code, e.read(120)
100
+ except Exception as e:
101
+ return classify(e), None, repr(e)
102
+ stock = ssl.create_default_context()
103
+ if sys.argv[1] == "baseline":
104
+ cls, status, body = probe(stock)
105
+ print("BASELINE:", cls, "status:", status, body)
106
+ if cls == "TLS_OK":
107
+ raise SystemExit("BASELINE: the stock context VERIFIED, so this runner still has a wired CA store and is NOT reproducing the report")
108
+ raise SystemExit(0 if cls == "TLS_FAIL" else "BASELINE: WRONG failure: %s" % (body,))
109
+ import certifi
110
+ from sibyl_memory_client._trust import https_context
111
+ ctx = https_context()
112
+ print("certifi:", certifi.where(), "| fixed store:", ctx.cert_store_stats(), "| stock store:", stock.cert_store_stats())
113
+ cls, status, body = probe(ctx)
114
+ print("FIX:", cls, "status:", status, body)
115
+ if cls != "TLS_OK":
116
+ raise SystemExit("FIX: %s: %s" % (cls, body))
117
+ PY
118
+ - name: baseline, expected to FAIL with CERTIFICATE_VERIFY_FAILED
119
+ continue-on-error: true
120
+ run: '"$RUNNER_TEMP/smoke/bin/python" "$RUNNER_TEMP/probe.py" baseline'
121
+ - name: the fix, must SUCCEED
122
+ run: '"$RUNNER_TEMP/smoke/bin/python" "$RUNNER_TEMP/probe.py" fix'
123
+
124
+ - name: "the CLI must not report a server error 0"
125
+ run: |
126
+ set -eu
127
+ export PATH="$RUNNER_TEMP/smoke/bin:$PATH"
128
+ # `sibyl update` reads PyPI over HTTPS through the same trust context,
129
+ # so it is the command that actually exercises the fixed path.
130
+ sibyl update 2>&1 | tee cli.txt
131
+ sibyl status 2>&1 | tee -a cli.txt
132
+ if grep -q "server error: 0" cli.txt; then
133
+ echo "FAIL: the CLI still reports 'server error: 0'"
134
+ exit 1
135
+ fi
136
+ if grep -qi "CERTIFICATE_VERIFY_FAILED" cli.txt; then
137
+ echo "FAIL: the CLI still hits a certificate verification failure"
138
+ exit 1
139
+ fi
.github/workflows/tests.yml ADDED
@@ -0,0 +1,91 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Test suites of the five packages on every supported Python (review panel
2
+ # finding 9, 2026-11-14): nothing ran the tests on push, and Python 3.10, the
3
+ # declared floor, was never executed. Each package's own pytest runs with an
4
+ # empty HOME, so no test can read or write a real ~/.sibyl-memory, ~/.claude,
5
+ # ~/.codex, ~/.cursor, ~/.hermes or ~/.dsh.
6
+ name: tests
7
+
8
+ # push runs on the default branch only (main); a PR branch runs once, from
9
+ # pull_request, instead of twice.
10
+ on:
11
+ push:
12
+ branches: [main]
13
+ pull_request:
14
+
15
+ permissions:
16
+ contents: read
17
+
18
+ jobs:
19
+ pytest:
20
+ name: pytest (Python ${{ matrix.python-version }})
21
+ runs-on: ubuntu-latest
22
+ strategy:
23
+ fail-fast: false
24
+ matrix:
25
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
26
+ steps:
27
+ - uses: actions/checkout@v4
28
+
29
+ - uses: actions/setup-python@v5
30
+ with:
31
+ python-version: ${{ matrix.python-version }}
32
+
33
+ - name: install (editable, dependencies first)
34
+ run: |
35
+ set -eux
36
+ python -m pip install --upgrade pip
37
+ # client first: hermes, mcp, cli and langgraph all depend on it;
38
+ # hermes before mcp and cli, mcp before cli.
39
+ python -m pip install -e ./sibyl-memory-client
40
+ python -m pip install -e ./sibyl-memory-hermes
41
+ python -m pip install -e ./sibyl-memory-mcp
42
+ python -m pip install -e ./sibyl-memory-cli
43
+ python -m pip install -e ./sibyl-memory-langgraph
44
+ python -m pip install pytest
45
+ python -m pip list
46
+
47
+ - name: pytest per package (temp HOME)
48
+ run: |
49
+ set -u
50
+ status=0
51
+ for pkg in client hermes mcp cli langgraph; do
52
+ home="$(mktemp -d)"
53
+ echo "::group::sibyl-memory-$pkg"
54
+ extra=""
55
+ # needs the `claude` binary, which the runner does not have
56
+ if [ "$pkg" = "cli" ]; then
57
+ extra="--deselect tests/test_orchestrator.py::test_orchestrator_full_flow"
58
+ fi
59
+ (cd "sibyl-memory-$pkg" && HOME="$home" USERPROFILE="$home" \
60
+ python -m pytest -q -p no:cacheprovider $extra tests) || status=1
61
+ echo "::endgroup::"
62
+ rm -rf "$home"
63
+ done
64
+ exit $status
65
+
66
+ # The lowest declared mcp (sibyl-memory-mcp pins mcp>=1.19.0) on the lowest
67
+ # supported Python, for the mcp package only, with pydantic held below 2.12
68
+ # to match that mcp release (measured 2026-11-14: 284 passed).
69
+ mcp-floor:
70
+ name: pytest mcp (Python 3.10, mcp 1.19.0)
71
+ runs-on: ubuntu-latest
72
+ steps:
73
+ - uses: actions/checkout@v4
74
+
75
+ - uses: actions/setup-python@v5
76
+ with:
77
+ python-version: "3.10"
78
+
79
+ - name: install (lowest mcp)
80
+ run: |
81
+ set -eux
82
+ python -m pip install --upgrade pip
83
+ python -m pip install -e ./sibyl-memory-client -e ./sibyl-memory-mcp \
84
+ "mcp==1.19.0" "pydantic<2.12" pytest
85
+ python -m pip list
86
+
87
+ - name: pytest sibyl-memory-mcp (temp HOME)
88
+ run: |
89
+ home="$(mktemp -d)"
90
+ cd sibyl-memory-mcp
91
+ HOME="$home" USERPROFILE="$home" python -m pytest -q -p no:cacheprovider tests
.gitignore ADDED
@@ -0,0 +1,50 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.so
6
+ .Python
7
+ build/
8
+ dist/
9
+ *.egg-info/
10
+ *.egg
11
+ .eggs/
12
+ .pytest_cache/
13
+ .mypy_cache/
14
+ .ruff_cache/
15
+ .coverage
16
+ htmlcov/
17
+ .tox/
18
+
19
+ # Environments
20
+ .venv/
21
+ venv/
22
+ env/
23
+ .env
24
+ .env.*
25
+ !.env.example
26
+
27
+ # IDE
28
+ .vscode/
29
+ .idea/
30
+ *.swp
31
+ *.swo
32
+
33
+ # OS
34
+ .DS_Store
35
+ Thumbs.db
36
+
37
+ # Vercel
38
+ .vercel/
39
+
40
+ # Local databases / state
41
+ *.db
42
+ *.sqlite
43
+ *.sqlite3
44
+ ~/.sibyl-memory/
45
+
46
+ # Private schema (never publish to public repo)
47
+ sibyl-plugin-schema/
48
+
49
+ # pip HTTP cache (never commit)
50
+ .pipcache/
CONTRIBUTING.md ADDED
@@ -0,0 +1,53 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Contributing to Sibyl Memory
2
+
3
+ Thanks for looking. Bug reports, reproductions and ideas are the most useful things you can send, and they are always read.
4
+
5
+ ## How changes land
6
+
7
+ Sibyl Memory ships as a paid product as well as an open-source plugin family, so **we do not merge outside code directly**. When a pull request finds a real bug or a good idea, we re-implement it in-house, ship it in the next release, and credit you by GitHub handle in the CHANGELOG and the release notes. A pull request is still the clearest way to show a fix: the diff, the failing case and the test are what we work from.
8
+
9
+ Please open an issue first for anything larger than a small fix, so we can tell you whether it fits before you spend the time.
10
+
11
+ ## Reporting a bug
12
+
13
+ Use the bug report form. The most helpful reports include:
14
+
15
+ - the package versions (`sibyl status` prints them, or `pip show sibyl-memory-client sibyl-memory-cli sibyl-memory-mcp sibyl-memory-hermes`)
16
+ - your OS and Python version
17
+ - the harness (Claude Code, Codex, Cursor, Hermes, LangGraph, another MCP client)
18
+ - the exact command and the full error output
19
+ - the output of `sibyl doctor`, if the problem is with setup or the MCP server
20
+
21
+ Never paste the contents of `~/.sibyl-memory/credentials.json` or any token.
22
+
23
+ ## Security issues
24
+
25
+ Do not open a public issue. Email sibyl@sibyllabs.org with the details and a way to reach you.
26
+
27
+ ## Working on the code
28
+
29
+ The repo holds five packages, each with its own `pyproject.toml`, tests and CHANGELOG:
30
+
31
+ | Package | What it is |
32
+ | --- | --- |
33
+ | `sibyl-memory-client` | The SDK: local SQLite store, FTS5 search, the memory model |
34
+ | `sibyl-memory-cli` | The `sibyl` command: sign-in, setup for each harness, `doctor`, `memory` |
35
+ | `sibyl-memory-mcp` | The MCP server for Claude Code, Codex, Cursor and any MCP client |
36
+ | `sibyl-memory-hermes` | The Hermes memory provider |
37
+ | `sibyl-memory-langgraph` | A LangGraph `BaseStore` |
38
+
39
+ Setup (Python 3.10 or newer):
40
+
41
+ ```bash
42
+ python -m venv .venv && . .venv/bin/activate
43
+ pip install -e sibyl-memory-client -e sibyl-memory-cli -e sibyl-memory-mcp -e sibyl-memory-hermes pytest
44
+ cd sibyl-memory-cli && pytest -q
45
+ ```
46
+
47
+ Run the tests with a throwaway `HOME` (`HOME=$(mktemp -d) pytest -q`) so nothing touches your real `~/.sibyl-memory`, `~/.claude`, `~/.codex` or `~/.hermes`.
48
+
49
+ Every package supports Python 3.10 and newer. Do not use syntax or standard-library features that need 3.11 or 3.12 (for example, reusing an f-string's quote inside `{}`).
50
+
51
+ ## Good first issues
52
+
53
+ Issues labelled `good first issue` are small, self-contained and have a clear done state. Comment on one before starting so two people do not take the same one.
Dockerfile ADDED
@@ -0,0 +1,39 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # syntax=docker/dockerfile:1
2
+ # First-party Docker image for the Sibyl Memory MCP server (stdio transport).
3
+ # Non-root, pinned slim base, no secrets baked in. Storage lives on a mounted
4
+ # volume at /home/app/.sibyl-memory. See sibyl-memory-mcp/README.md "Docker".
5
+ # TODO: pin by digest before publish (no docker daemon in build env).
6
+ # Keep comments on their own line: a trailing "# ..." after FROM is parsed as
7
+ # extra FROM arguments and fails the build.
8
+ FROM python:3.12-slim-bookworm
9
+
10
+ # No build tools needed: sibyl-memory-mcp is pure Python and sqlite3 + FTS5
11
+ # ship in the stdlib. Keep the layer count and surface minimal.
12
+ ENV PYTHONUNBUFFERED=1 \
13
+ PYTHONDONTWRITEBYTECODE=1 \
14
+ PIP_NO_CACHE_DIR=1 \
15
+ PIP_DISABLE_PIP_VERSION_CHECK=1
16
+
17
+ # Non-root runtime user with a real home for the default ~/.sibyl-memory path.
18
+ RUN groupadd --gid 10001 app \
19
+ && useradd --uid 10001 --gid 10001 --create-home --home-dir /home/app app
20
+
21
+ # Install the MCP server from the local monorepo source (first-party build,
22
+ # not pulled from PyPI at image-build time). Copy only the mcp package, then
23
+ # pip install it, which pulls its declared deps (mcp, sibyl-memory-client,
24
+ # sibyl-memory-hermes) from PyPI.
25
+ WORKDIR /app
26
+ COPY sibyl-memory-mcp/ /app/sibyl-memory-mcp/
27
+ RUN pip install /app/sibyl-memory-mcp
28
+
29
+ # Memory dir on the mounted volume, owned by the non-root user, mode 0700.
30
+ RUN mkdir -p /home/app/.sibyl-memory \
31
+ && chown -R app:app /home/app/.sibyl-memory \
32
+ && chmod 700 /home/app/.sibyl-memory
33
+ VOLUME ["/home/app/.sibyl-memory"]
34
+
35
+ USER app
36
+ ENV HOME=/home/app
37
+
38
+ # stdio MCP server. Run attached with STDIN open (docker run -i), no TTY.
39
+ ENTRYPOINT ["sibyl-memory-mcp"]
LICENSE ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sibyl Labs LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
README.md ADDED
@@ -0,0 +1,235 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: mit
3
+ tags:
4
+ - agent-memory
5
+ - long-term-memory
6
+ - llm
7
+ - ai-agents
8
+ - mcp
9
+ - retrieval
10
+ - sqlite
11
+ - rag
12
+ ---
13
+
14
+ > **Read-only mirror of [`Sibyl-Labs/Sibyl-Memory`](https://github.com/Sibyl-Labs/Sibyl-Memory).** The canonical source is on GitHub. Install from PyPI: `pip install -U sibyl-memory-cli` · Docs: https://docs.sibyllabs.org/memory/ · Product: https://sibyllabs.org/plugin · Benchmarks: https://blog.sibylcap.com/beta-analysis
15
+
16
+ <div align="center">
17
+
18
+ ```
19
+ ███████╗██╗██████╗ ██╗ ██╗██╗
20
+ ██╔════╝██║██╔══██╗╚██╗ ██╔╝██║
21
+ ███████╗██║██████╔╝ ╚████╔╝ ██║
22
+ ╚════██║██║██╔══██╗ ╚██╔╝ ██║
23
+ ███████║██║██████╔╝ ██║ ███████╗
24
+ ╚══════╝╚═╝╚═════╝ ╚═╝ ╚══════╝
25
+
26
+ M E M O R Y
27
+ ```
28
+
29
+ **agentic memory infrastructure · file-based · zero embeddings**
30
+
31
+ [![PyPI · client](https://img.shields.io/pypi/v/sibyl-memory-client?label=client&color=8a6a2a)](https://pypi.org/project/sibyl-memory-client/)
32
+ [![PyPI · cli](https://img.shields.io/pypi/v/sibyl-memory-cli?label=cli&color=8a6a2a)](https://pypi.org/project/sibyl-memory-cli/)
33
+ [![PyPI · hermes](https://img.shields.io/pypi/v/sibyl-memory-hermes?label=hermes&color=8a6a2a)](https://pypi.org/project/sibyl-memory-hermes/)
34
+ [![PyPI · mcp](https://img.shields.io/pypi/v/sibyl-memory-mcp?label=mcp&color=8a6a2a)](https://pypi.org/project/sibyl-memory-mcp/)
35
+ [![PyPI · langgraph](https://img.shields.io/pypi/v/sibyl-memory-langgraph?label=langgraph&color=8a6a2a)](https://pypi.org/project/sibyl-memory-langgraph/)
36
+ [![License: MIT](https://img.shields.io/badge/license-MIT-15110a.svg)](./LICENSE)
37
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-15110a.svg)](https://www.python.org/downloads/)
38
+ [![LongMemEval](https://img.shields.io/badge/LongMemEval-95.6%25%20%23%E2%80%832-2e6b3a.svg)](https://blog.sibylcap.com/longmemeval-v2)
39
+
40
+ <sub><i>built by an autonomous agent · sibyl labs llc</i></sub>
41
+
42
+ </div>
43
+
44
+ ---
45
+
46
+ ## What this is
47
+
48
+ Five PyPI packages, one schema family, one architecture.
49
+
50
+ **Runs on** Linux, macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is not supported.
51
+
52
+ `sibyl-memory-client` is a local-first agentic memory SDK. SQLite-backed, five-tier hierarchical schema, FTS5 search, multi-tenant by design. No vector database. No embedding model. No external retrieval service. The memory lives on the agent's machine; the substrate is a single file on disk.
53
+
54
+ > **Privacy disclosure.** Your memory content never leaves the machine. The plugin talks to `api.sibyllabs.org` for these things only: activation (`sibyl init`); a daily account check-in that renews this computer's access (account id, this computer's sign-in token, plugin version, OS family; no memory content); a size check when a free account nears its cap (account id, sign-in token, the database's byte size and the proposed delta); and an aggregate count of memory operations (the MCP server and CLI send it unless you opt out with `SIBYL_MEMORY_TELEMETRY=0`; Hermes, since 0.6.0, only if you opt in with `SIBYL_MEMORY_TELEMETRY=1`). The size check and the count also carry this computer's signed access token (account id, tier, cap, device hash, account flags; no personal data). An account is required to use the memory tools; your local data is always readable with `sibyl memory`. Verified against the source in `sibyl-memory-client/src/sibyl_memory_client/` (`_entitlement.py`, `_capcheck.py`, `_heartbeat.py`).
55
+
56
+ The other four packages ride on top: `sibyl-memory-cli` for activation and tier management, `sibyl-memory-hermes` for Hermes Agent integration, `sibyl-memory-mcp` for any MCP-compatible client (Claude Code, Codex, Cursor, Continue), and `sibyl-memory-langgraph` as a LangGraph `BaseStore` adapter.
57
+
58
+ The architecture was benchmarked publicly on [LongMemEval Oracle](https://blog.sibylcap.com/longmemeval-v2) (ICLR 2025, University of Michigan, 500 questions) and placed **#2 overall at 95.6%**, tied with Chronos (PwC), beating Mastra, MemMachine, Hindsight, Mem0, Supermemory, Zep, and the Oracle baseline. It is the only file-based system in the top tier: running on a single 4 vCPU / 16 GB box, no vector infrastructure, no embedding fees.
59
+
60
+ This is the entire stack as it ships to production agents today.
61
+
62
+ ---
63
+
64
+ ## Packages
65
+
66
+ | Package | PyPI | Description |
67
+ |---|---|---|
68
+ | [`sibyl-memory-client`](./sibyl-memory-client) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-client)](https://pypi.org/project/sibyl-memory-client/) | Local-first agentic memory SDK. SQLite-backed five-tier hierarchical schema, FTS5 search, multi-tenant, with self-learning skill detection and local memory linter. Foundation of the plugin family. |
69
+ | [`sibyl-memory-cli`](./sibyl-memory-cli) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-cli)](https://pypi.org/project/sibyl-memory-cli/) | Command-line interface. `sibyl init` activates, `sibyl upgrade` opens the Pro / Elite upgrade flow, `sibyl status` shows current tier and DB stats, `sibyl whoami`, `sibyl devices`. |
70
+ | [`sibyl-memory-hermes`](./sibyl-memory-hermes) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-hermes)](https://pypi.org/project/sibyl-memory-hermes/) | Bundled memory payload for Hermes Agent v0.13+ (and any other Python orchestration that wants direct SDK access). |
71
+ | [`sibyl-memory-mcp`](./sibyl-memory-mcp) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-mcp)](https://pypi.org/project/sibyl-memory-mcp/) | MCP server. Wraps the local SQLite + FTS5 memory engine and exposes it to MCP-compatible agents (Claude Code, Codex, Cursor, Continue, anything that speaks MCP). |
72
+ | [`sibyl-memory-langgraph`](./sibyl-memory-langgraph) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-langgraph)](https://pypi.org/project/sibyl-memory-langgraph/) | LangGraph `BaseStore` adapter. Long-term, cross-thread store backed by the same SQLite + FTS5 engine — durable agent memory with no vector database and no embeddings. |
73
+
74
+ ---
75
+
76
+ ## Install
77
+
78
+ ```bash
79
+ pip install sibyl-memory-cli
80
+ sibyl init
81
+ ```
82
+
83
+ `sibyl init` opens a browser to activate your account, binds your wallet or email, and writes credentials to `~/.sibyl-memory/credentials.json` plus this computer's signed access file, `entitlement.json`. Free tier is the default; Pro and Elite unlock self-learning, the memory linter, and remove the local cap.
84
+
85
+ **An account is required.** Since client 0.9.0 every memory tool (MCP, Hermes, LangGraph, the SDK) needs an activated account holding a valid, server-signed entitlement. Without one the tools answer with a clear "run `sibyl init`" error instead of storing anything. The entitlement renews itself in the background about once a day and keeps working offline for up to 14 days. Your local memory is never deleted by any of this, and `sibyl memory list|search|recall` always reads it without an account. Memory written on this computer before you signed in moves into your account, on this computer, the first time you sign in (one local step, nothing uploaded); `sibyl memory adopt` does it on request, and asks first if the store has held another account. Upgrading needs one connection to finish setup: until this computer has checked in once, the tools answer "connect to the internet once to finish setup".
86
+
87
+ ### Open code, hosted account
88
+
89
+ The code in this repository is MIT licensed, including the whole local engine, so a fork can remove the account check. We say that plainly. Here is what such a fork keeps and what it cannot have:
90
+
91
+ | A fork keeps (local, always public under MIT) | A fork loses (held by the server; needs the entitlement or the live sign-in it comes from) |
92
+ |---|---|
93
+ | The SQLite schema, storage, FTS5 search, the verdict contract, the write-time normalizer, a local cap check it can edit away, unlimited local stores | Anything above the free cap on the official path (from the client cutoff, `/check-write` refuses without a live sign-in and a matching entitlement) |
94
+ | Reading and writing its own local database with any agent it wires up itself | Paid recognition anywhere: learner and linter authorization keyed to the entitlement tier, purchase claims, the billing portal, USDC subscriptions |
95
+ | The MIT right to redistribute its modified copy under its own name | Device management (`sibyl devices`, revoke, web approval), the account page, email verification, recovery, receipts and security notices |
96
+ | | Updates, support, the beta channel, and every hosted feature to come |
97
+ | | The name: the official packages, docs and installers point at accounts |
98
+
99
+ For direct SDK use:
100
+
101
+ ```bash
102
+ pip install sibyl-memory-client
103
+ ```
104
+
105
+ For Hermes integration:
106
+
107
+ ```bash
108
+ pip install sibyl-memory-cli
109
+ sibyl setup hermes # installs the plugin and sets memory.provider: sibyl
110
+ ```
111
+
112
+ For MCP (Claude Code, Codex, Cursor, Continue, ...):
113
+
114
+ ```bash
115
+ pip install sibyl-memory-mcp sibyl-memory-cli
116
+ sibyl setup claude-code # or: sibyl setup codex | cursor | grokbot
117
+ sibyl doctor # end-to-end check: start, list tools, save, recall, delete a test memory
118
+ # other MCP clients: sibyl setup --print-config prints a ready mcpServers block
119
+ ```
120
+
121
+ The Hermes plugin-catalog package lives in `sibyl-memory-hermes/hermes-catalog/`; the catalog listing is pending.
122
+
123
+ Full documentation at [docs.sibyllabs.org/memory](https://docs.sibyllabs.org/memory/).
124
+
125
+ ---
126
+
127
+ ## Architecture
128
+
129
+ ```
130
+ ┌─────────────────────────────────────────────────────────┐
131
+ │ sibyl-memory-cli sibyl-memory-mcp │
132
+ │ ┌──────────────┐ ┌──────────────┐ │
133
+ │ │ sibyl init │ │ MCP server │ │
134
+ │ │ sibyl status │ │ (stdio) │ │
135
+ │ │ sibyl whoami │ └──────┬───────┘ │
136
+ │ └──────┬───────┘ │ │
137
+ │ └────────────┬─────────────────┘ │
138
+ │ sibyl-memory-hermes │ sibyl-memory-langgraph │
139
+ │ ┌──────────────┐ │ ┌────────────────┐ │
140
+ │ │ Hermes hook │ │ │ LangGraph │ │
141
+ │ └──────┬───────┘ │ │ BaseStore │ │
142
+ │ │ │ └───────┬────────┘ │
143
+ │ │ │ │ │
144
+ │ │ │ │ │
145
+ │ └────────────┼─────────────┘ │
146
+ │ ▼ │
147
+ │ sibyl-memory-client (SDK) │
148
+ │ ┌────────────────────────┐ │
149
+ │ │ SQLite + FTS5 │ │
150
+ │ │ 5-tier schema │ │
151
+ │ │ self-learning skills │ │
152
+ │ │ multi-tenant │ │
153
+ │ └────────────────────────┘ │
154
+ └─────────────────────────────────────────────────────────┘
155
+ ```
156
+
157
+ Each package has its own `README.md` and `CHANGELOG.md` for the detail.
158
+
159
+ The five tiers, in case you're curious:
160
+
161
+ ```
162
+ HOT state/ live working state, rewritten in place
163
+ WARM entities/ single source of truth per (category, name)
164
+ COLD journal/ append-only event log
165
+ REFERENCE reference/ static knowledge, rarely changes
166
+ ARCHIVE archive/ retired entities, kept for audit
167
+ ```
168
+
169
+ Rule 43 (single source of truth per entity) is enforced at the schema level via a `UNIQUE (tenant_id, category, name)` constraint, not just a convention in the application code. Drift is impossible by construction.
170
+
171
+ ---
172
+
173
+ ## Provenance
174
+
175
+ Built by [SIBYL](https://x.com/sibylcap), the autonomous agent operating at [Sibyl Labs LLC](https://sibyllabs.org).
176
+
177
+ The agent has been operating in production since February 2026, ships code daily, holds an on-chain identity on Base (ERC-8004 agent ID 20880), runs an autonomous trading engine, an on-chain messaging protocol, an x402 payment rail, a token-gated chat demo, an advisory dashboard, and this memory product family. Everything verifiable on-chain.
178
+
179
+ Memory architecture is the proven core. Sibyl Labs LLC owns the IP, signs contracts, and holds the legal wrapper around the agent's work. The work itself is shipped by the agent, in sessions, through the operator (`@tradingtulips`). The PyPI releases, the CLI, the SDK, the CLI banner above: all of it is autonomous agent output.
180
+
181
+ The on-chain record is the resume. This repository is one chapter of it.
182
+
183
+ ---
184
+
185
+ ## Save and debloat
186
+
187
+ **Save.** At the end of a session, or after a big block of work, your agent writes what happened
188
+ into Sibyl Memory through the plugin's own tools: the decisions made and why (journal), the
189
+ people, projects and products touched (entities), what to pick up next time and the open
190
+ warnings (session state), the ranked priorities, and it closes what died (archive). A delta
191
+ marker means a second save in the same day captures only what changed. It may offer to turn a
192
+ repeated pattern into a reusable skill; that is offered, never forced. Nothing in a save leaves
193
+ your machine.
194
+
195
+ **Debloat.** Sibyl measures the files your agent loads on every session start (`CLAUDE.md`,
196
+ `AGENTS.md`, `.cursorrules` and the rest of the scan set), deterministically (`chars/4`,
197
+ labeled `MEASURED~`), and when they are heavy, trims the accreted history out of them without
198
+ losing a byte: the history moves out and a one-line pointer stays. On the free plan the history
199
+ moves to a sibling `*-history` file. On Pro it is stored in Sibyl Memory as a reference document,
200
+ so it stays searchable, and the measurement and trim run by themselves under a policy you set
201
+ once.
202
+
203
+ | | Free (activated account) | Pro |
204
+ |---|---|---|
205
+ | 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 |
206
+ | `sibyl save`, `sibyl debloat` (measure, plan, apply, undo) | yes | yes |
207
+ | Reminders (one quiet line; `sibyl reminders off`) | yes | replaced by a one-line report of what ran |
208
+ | Where trimmed history goes | a sibling `*-history` file | Sibyl Memory, plus a byte-verified backup |
209
+ | 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) |
210
+ | 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 |
211
+ | 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 |
212
+ | Skill signals (0.10): Sibyl also notices a tool sequence your agent repeats (in Claude Code the whole workflow, for example `Read -> Edit -> Bash`; in Codex, Cursor and Hermes the memory tools only) and an entity rewritten again and again, and proposes a skill for it the same way. It keeps one small local file, `~/.sibyl-memory/signals.json`: tool and MCP server names in plain text, argument names and entity names only as hashes, never a value, never a prompt or a file path; nothing leaves your computer. `sibyl skills signals` shows its size, `clear` deletes it, `off` stops it. In Claude Code a proposal from the workflow appears at the next session start at the earliest | no (nothing is recorded) | yes |
213
+
214
+ The procedures are vendored, with attribution, from the public MIT repos
215
+ [sibyl-save](https://github.com/Sibyl-Labs/sibyl-save) and
216
+ [debloat](https://github.com/Sibyl-Labs/debloat); both stay standalone and account-free.
217
+
218
+ Uninstalling: run `sibyl skills uninstall` first. It removes the Claude Code hooks in
219
+ `~/.claude/settings.json`, the skill shims and the Codex block (files you edited are kept); then
220
+ `pip uninstall` the packages. The hooks call this package's `sibyl` command: if the package goes
221
+ first they exit quietly, but they stay in your settings until you reinstall and run
222
+ `sibyl skills uninstall`, or delete the five `sibyl hook` entries by hand.
223
+
224
+ Privacy: the lifecycle reads your instruction files to measure and trim them locally; no file
225
+ content and no conversation content ever leaves your machine.
226
+
227
+ Forks: a gate-stripped fork can run the lifecycle code locally (MIT allows it). It gains nothing
228
+ hosted, and its trims land in a store the official path cannot recognize as Pro. No file, flag
229
+ or environment variable turns the automation on for a free account.
230
+
231
+ ## License
232
+
233
+ MIT. See [LICENSE](./LICENSE).
234
+
235
+ Copyright (c) 2026 Sibyl Labs LLC.
docker-compose.yml ADDED
@@ -0,0 +1,25 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Compose file for the Sibyl Memory MCP server (stdio transport).
2
+ # This is a stdio server, NOT a network service. Do NOT `docker compose up`:
3
+ # the server reads MCP over stdin and exits on EOF. Run it attached:
4
+ # docker compose run --rm sibyl-memory-mcp
5
+ # or point an MCP client's command at a `docker run -i --rm` wrapper (see
6
+ # sibyl-memory-mcp/README.md "Docker"). No secrets live in this file:
7
+ # credentials.json arrives only through the mounted volume at runtime.
8
+ services:
9
+ sibyl-memory-mcp:
10
+ build:
11
+ context: .
12
+ dockerfile: Dockerfile
13
+ image: sibyl-memory-mcp:local
14
+ # stdio server: keep STDIN open, no TTY. Client drives stdin.
15
+ stdin_open: true
16
+ tty: false
17
+ # Env passthrough only. No values are set here. Uncomment and set on the
18
+ # host env (or an untracked .env) if you need to override defaults.
19
+ environment:
20
+ - SIBYL_MEMORY_DB
21
+ - SIBYL_CREDENTIALS
22
+ volumes:
23
+ - sibyl-memory-data:/home/app/.sibyl-memory
24
+ volumes:
25
+ sibyl-memory-data:
docs/diagrams/setup-mcp-rail.svg ADDED
docs/diagrams/setup-sdk-rail.svg ADDED
docs/release-0.8.0-notes.md ADDED
@@ -0,0 +1,262 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Sibyl Memory 0.8.0 "Lucid" family: release notes
2
+
3
+ `sibyl-memory-client` 0.8.0 · `sibyl-memory-mcp` 0.2.0 · `sibyl-memory-cli` 0.4.0 ·
4
+ `sibyl-memory-hermes` 0.4.0 · `sibyl-memory-langgraph` 0.2.0
5
+
6
+ Branch `lang-core-verdict`. Every number below comes from a run recorded in this
7
+ repository. Nothing here is projected, rounded up, or inferred.
8
+
9
+ ---
10
+
11
+ ## What this release is
12
+
13
+ The query-time multilingual rescue layers that four evaluation cycles accreted in
14
+ `MemoryClient.search()` were removed and replaced by one versioned write-time
15
+ normalizer, and every search that returns zero rows now returns a machine-readable
16
+ cause alongside it.
17
+
18
+ **It improves the INDEX layer.** Stored text is rendered word-boundary clean at
19
+ write time, so a term can match at a word START rather than only as a free
20
+ substring, which is what inflected and non-spaced languages need.
21
+
22
+ **It does not solve default-path natural-language recall.** The first call on the
23
+ default path answers 32 of 155 natural paraphrases, the same as before. The other
24
+ 123 now say why, and 99 of them are recoverable by a caller that reads the verdict
25
+ and runs the taught two-retry loop. The 29 negation-phrased answerable questions
26
+ still return nothing on the default path; they now report `negation_abstain` or
27
+ `abstained_on`. `NEGATION_POLICY` is unchanged and answering a negated question
28
+ correctly still needs negation handling this engine does not have.
29
+
30
+ Search behaviour is byte-identical to the previous build (`ef98f5b`) on every
31
+ quality field of the full battery across three configurations. This release adds
32
+ explanation, not retrieval.
33
+
34
+ ---
35
+
36
+ ## Read these before you upgrade
37
+
38
+ ### 1. The two-retry bound is agent-side and unenforced
39
+
40
+ The verdict tells an agent that one word in its query blocked everything, and the
41
+ tool docstring, the Hermes tool schema and the Hermes system-prompt block all
42
+ teach: drop that word, call again, at most twice, then stop.
43
+
44
+ Nothing in the server enforces it. The server has no memory of a caller's previous
45
+ query and cannot count retries without becoming stateful.
46
+
47
+ An agent that ignores the bound and keeps stripping words reaches the
48
+ corpus-supported residue of its own query. Measured: 6 rows across the two
49
+ supported-class injection queries, worst case 7 rounds.
50
+
51
+ Two things make that acceptable, and both are measured:
52
+
53
+ - A query built from vocabulary the store does not contain returns zero rows at
54
+ any number of retries. Verified unbounded on all eight zero-support injection
55
+ queries.
56
+ - The residue an unbounded loop reaches is **byte-identical to what one ordinary
57
+ call returns with no loop at all**. `memory_search('contract')` returns the same
58
+ 3 rows the unbounded loop grinds down to. The loop grants no access the caller
59
+ did not already have, and the advice this replaces (`retry with tiers="entity"`)
60
+ returned those rows for the FULL unmodified injection query in a single step.
61
+
62
+ So the bound is a quality control, not an access boundary: it stops the loop from
63
+ answering a shorter question than the user asked.
64
+
65
+ **The appearance hazard.** An operator reading a non-compliant agent's transcript
66
+ will see rows returned after an injection-shaped prompt. Those rows are the answer
67
+ to `contract`. They are not the answer to the injection, and no injected word
68
+ appears in any returned body.
69
+
70
+ ### 2. First open after upgrade re-backfills the shadow, O(rows), under one lock
71
+
72
+ The stored rendering changed, so `_SHADOW_MARKER` was bumped. Every existing store
73
+ drops, recreates and re-backfills its search shadow on the next open. The marker
74
+ is in the code, so **the bump triggers this fleet-wide on upgrade**, not per-store
75
+ on demand.
76
+
77
+ Measured: **1.65 s at 10k rows, 27 s at 100k rows.**
78
+
79
+ It runs under one `BEGIN IMMEDIATE` write lock. A second process opening the same
80
+ store during the rebuild blocks. That lock-out is fixed (`busy_timeout` is widened
81
+ to 180 s for the whole span of schema-apply plus migration, which is exactly the
82
+ window a concurrent opener can be blocked for, then restored so the ordinary read
83
+ path keeps failing fast). The O(rows) shape itself is not removed.
84
+
85
+ Plan for it on large stores: the first open is the slow one, every open after it
86
+ is O(1).
87
+
88
+ ### 3. `empty_store` probe cost
89
+
90
+ `empty_store` is probed, never inferred, and only on the zero path.
91
+
92
+ - **Zero extra `COUNT(*)` on any store that has entities.** The engine reuses the
93
+ entities count it already takes for IDF weighting; a non-zero one proves the
94
+ store is non-empty and the probe is skipped.
95
+ - **Four extra `COUNT(*)` per zero on a store holding only journal / state /
96
+ reference rows.** That is the case where the probe is load-bearing: such a store
97
+ answers queries and must be reported `abstained_on`, never `empty_store`.
98
+ - Measured at 1 `COUNT(*)` per zero-result MCP call, the same as the previous
99
+ build. Not measured above 1400 entities.
100
+
101
+ ### 4. OPEN: the corroborated-class append is unbounded
102
+
103
+ On `client.search()` and on the MCP `tiers=` route, rows covering two or more of
104
+ the query's terms are appended without a budget. Rows covering exactly one term
105
+ are budgeted to the query's content-term count; rows covering two or more are not.
106
+
107
+ Consequence: boilerplate carrying two of the query's terms can append up to the
108
+ caller's limit. Measured worst case on the battery: 19 appended rows where 0.7.0
109
+ produces none.
110
+
111
+ This is reported, not decided. A per-coverage-level budget was built and measured
112
+ and is **not shippable**: it costs 35 answer-bearing rows across 7 LongMemEval
113
+ questions, because the distributions overlap (a legitimate level needs 12 rows at
114
+ 1 term, 9 at 2 and 7 at 4, while the sweep has 30 at 3), so no monotone
115
+ query-shape budget separates them and a tie-group bound fails identically.
116
+
117
+ The **default path is unaffected**. Behaviour is pinned by
118
+ `test_corroborated_class_is_NOT_bounded_open_finding`, so a future change to it is
119
+ a deliberate change, not a drift.
120
+
121
+ ### 5. SQLite floor: 3.34, verified and now enforced
122
+
123
+ The package carried two different floors, neither of them run: `shadow.py`
124
+ documented 3.34, `storage.py`'s recovery message told users to check for "3.38+
125
+ for json_valid", and the stage-2 trigger shape (the rendering is staged through
126
+ nested subqueries that read `new.` INSIDE a subquery) had only ever executed on
127
+ 3.45.1. `CREATE TRIGGER` failing outright was the failure mode nobody had ruled
128
+ out.
129
+
130
+ **Verified.** SQLite was built from the amalgamation at **3.34.1** and **3.44.2**
131
+ (FTS5 + JSON1) and statically linked into a scratch interpreter:
132
+
133
+ | version | trigger shape | shadow rows vs 3.45.1 | client suite |
134
+ |---|---|---|---|
135
+ | 3.34.1 | creates and fires on all four tiers | byte-identical | 476 passed, 12 skipped |
136
+ | 3.44.2 | creates and fires on all four tiers | byte-identical | 476 passed, 12 skipped |
137
+ | 3.45.1 | creates and fires on all four tiers | reference | 477 passed, 11 skipped |
138
+
139
+ `_STAGE_OPS`, the nesting-depth constant tuned against the trigger parser's
140
+ ceiling on 3.45.1, is inside the ceiling on 3.34.1 and 3.44.2 as well.
141
+
142
+ **Enforced.** `shadow.SQLITE_MIN_VERSION = (3, 34, 0)` is checked by
143
+ `assert_sqlite_supported()` at the top of `Storage._ensure_schema`, before the
144
+ schema apply and therefore before any migration write. Below it, a `SchemaError`
145
+ names the minimum, the found version and the reason. Previously the failure
146
+ surfaced from inside the v4 migration as "error in tokenizer constructor", which
147
+ named neither. The contradictory "3.38+" claim is deleted and a test asserts no
148
+ string in `storage.py` states a SQLite version.
149
+
150
+ **3.45 is a feature boundary, not a floor.** `remove_diacritics` reached the
151
+ `trigram` tokenizer in 3.45. Below it the shadow folds the non-decomposables in
152
+ `FOLD_MAP` (l-stroke, sharp s, o-slash, ae, d-stroke, dotless i, oe, thorn, eth)
153
+ but not decomposable diacritics, because that fold is the tokenizer's job. So
154
+ `Belzyce` does not find `Bełżyce` on 3.34 through 3.44. The store opens, writes,
155
+ migrates and searches, and the primary porter-unicode61 index is unaffected. That
156
+ one test is gated on the boundary with the version in its skip reason; a companion
157
+ test covering the non-decomposable half runs on every supported version.
158
+
159
+ Check what you are on:
160
+
161
+ ```
162
+ python -c "import sqlite3; print(sqlite3.sqlite_version)"
163
+ ```
164
+
165
+ ### 6. Two LongMemEval residuals at limit 10
166
+
167
+ `e982271f` and `gpt4_f420262c` are real losses at limit 10 and clean at limit 25.
168
+
169
+ - `e982271f` drops the session recording which venue was recommended LAST and
170
+ keeps an interchangeable venue card containing the gold string. Raising the
171
+ limit to 11, 12, 13 or 15 does not recover its row, so this needs a RANKING
172
+ change, not a holdback.
173
+ - `gpt4_f420262c` drops the EARLIEST session on an earliest-to-latest ordering
174
+ question. It closes at limit 11 via a holdback, which is a head override and is
175
+ excluded by the constraint this work ran under.
176
+
177
+ Both are recorded as known, deferred, with reasons.
178
+
179
+ ### 7. `tiers=` is a documented bypass, not a recovery
180
+
181
+ The previous MCP docstring taught `tiers="entity"` as the escape hatch from an
182
+ abstention. That advice is gone from the source.
183
+
184
+ `tiers=` has no abstention gate, and therefore no injection precision gate, which
185
+ is what the abstention gate IS. It remains supported and documented as the linker
186
+ bypass with its tradeoff stated. It is not the recovery for an `abstained_on`.
187
+ The recovery for an `abstained_on` is: drop the one token named in
188
+ `verdict.tokens[0]`, call again with every gate still armed, at most twice.
189
+
190
+ ### 8. Docker-image users must rebuild the image
191
+
192
+ A self-built `sibyl-memory-mcp` Docker image pins its dependencies at image build
193
+ time. **A `pip install -U` on the host does not reach inside the image.** Rebuild
194
+ the image to pick up 0.2.0 and the client 0.8.0 underneath it.
195
+
196
+ This is the same class of hazard the 0.1.14 dependency-floor raise addressed: an
197
+ MCP-only install path that is not going through the CLI's tighter floor can sit on
198
+ older code while reporting a clean install.
199
+
200
+ ### 9. The deprecated `diagnostics=` dict
201
+
202
+ `multi_record_search(..., diagnostics=<dict>)` still populates, with identical
203
+ keys and values on **every exit that previously wrote anything**. There is exactly
204
+ one observable difference: the `no significant tokens` exit now writes the five
205
+ standard keys where the previous build left the dict empty.
206
+
207
+ Prefer `result.verdict`. An optional channel is one a caller can forget, and
208
+ forgetting it is the whole defect this release closes: the MCP server never passed
209
+ `diagnostics=` at all, so the channel was unreachable from the surface that
210
+ matters most.
211
+
212
+ ---
213
+
214
+ ## Upgrade order
215
+
216
+ Client first, then the packages that depend on it. The dependency floors make a
217
+ partial upgrade fail loudly rather than silently mix an old client with new
218
+ adapters:
219
+
220
+ | package | version | floors |
221
+ |---|---|---|
222
+ | `sibyl-memory-client` | 0.8.0 | (none) |
223
+ | `sibyl-memory-hermes` | 0.4.0 | client >= 0.8.0 |
224
+ | `sibyl-memory-mcp` | 0.2.0 | client >= 0.8.0, hermes >= 0.4.0 |
225
+ | `sibyl-memory-cli` | 0.4.0 | client >= 0.8.0, hermes >= 0.4.0, mcp >= 0.2.0 (extra) |
226
+ | `sibyl-memory-langgraph` | 0.2.0 | client >= 0.8.0 |
227
+
228
+ Note that `pip install -U <one package>` uses pip's only-if-needed upgrade
229
+ strategy, which leaves an already-satisfying older sibling in place. The floors
230
+ above are what turn that into a resolvable upgrade rather than a silent no-op.
231
+
232
+ ---
233
+
234
+ ## Response-shape changes
235
+
236
+ - **MCP** `memory_search`: the response gains an additive `verdict` object on
237
+ every call, including every zero. Nothing was removed and no field changed
238
+ meaning. `count` and `verdict.returned` are reconciled after bounding, so they
239
+ cannot disagree.
240
+ - **Hermes** `sibyl_search`: returns `{"results": [...], "verdict": {...}}`.
241
+ `search_multi_record` and `search` return a `SearchResults` list subclass;
242
+ `len`, iteration, indexing, `== []`, `json.dumps`, `isinstance(x, list)`,
243
+ copy/deepcopy/pickle and slicing all behave as before (a slice correctly drops
244
+ the verdict).
245
+ - **CLI** `sibyl memory search`: the zero path prints a plain-language cause plus
246
+ a machine-readable `cause: <code>` line. The success path prints no extra
247
+ output.
248
+ - **langgraph** `SibylStore`: `BaseStore.search` still returns
249
+ `list[SearchItem]`; the canonical verdict of the most recent query-backed search
250
+ is exposed as `SibylStore.last_search_verdict`, and an empty FTS result is
251
+ logged at DEBUG with its cause.
252
+
253
+ ## What a verdict may carry
254
+
255
+ Numbers, enum values, and tokens from the caller's own query. Never stored-record
256
+ content: no body text, no snippet, no entity name, no category, no key. Token
257
+ strings are capped at 64 characters and 8 per list field, and the envelope key
258
+ order is fixed and JSON-serialisable, so the verdict composes with the MCP output
259
+ fence rather than becoming a second unfenced channel out of the store. A canary
260
+ sweep planting verdict-shaped content in bodies, entity keys, categories, nested
261
+ fields and three non-entity tiers, across four SDK entry points, the MCP tool over
262
+ real spawned stdio on both routes, and the Hermes provider, found **0 leaks**.
sibyl-memory-cli/.gitignore ADDED
@@ -0,0 +1 @@
 
 
1
+ .vercel
sibyl-memory-cli/CHANGELOG.md ADDED
@@ -0,0 +1,1560 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Changelog
2
+
3
+ All notable changes to `sibyl-memory-cli` are recorded here. Format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows
5
+ [SemVer](https://semver.org/).
6
+
7
+ ## [0.7.0] - 2026-11-14
8
+
9
+ ### Added
10
+ - `sibyl setup deepseek` (alias `dsh`) wires Sibyl Memory into DeepSeek Harness (developer
11
+ preview). It adds one `sibyl-memory` row to the home patch file (`$DSH_HOME/cordis.patch.yml`,
12
+ default `~/.dsh`), which covers every profile, or with `--dsh-profile <name>` to that one
13
+ profile's patch. The file is edited as text, never re-serialized, and every edit is proven by
14
+ parsing it: your own patches, comments and `!!js` values stay as written. DeepSeek Harness is
15
+ detected only by its `profiles/` folder or `cordis.patch.yml`; a `~/.dsh` that belongs to the
16
+ unrelated Debian `dsh` program is never detected or written, and no `dsh` binary is run. New
17
+ flags `--dsh-home` and `--dsh-profile`. Needs DeepSeek Harness on Node 24.9 or newer.
18
+ - `sibyl doctor` checks each harness's wiring (Hermes, Claude Code, Codex, Cursor, Grok Bot,
19
+ DeepSeek Harness) and reports ok, missing, stale, broken, foreign, duplicate, unreadable,
20
+ disabled, overridden or unverifiable. Read-only by default. `--fix` repairs stale or broken
21
+ entries only (it never adds a missing one and never touches another tool's entry); a missing
22
+ entry is a warning that names the `sibyl setup <target>` command. `--harness` limits the checks
23
+ (repeatable) and `--no-harness` skips them. `--json` adds `server_ok`, `harnesses`, `fix`,
24
+ `legacy_backups` and `later`, and `ok` is now the overall verdict. Exit 1 while wiring is still
25
+ stale or broken.
26
+
27
+ ### Changed
28
+ - Config backups now live in one place: `~/.sibyl-memory/backups/<harness>/` (folders 0700,
29
+ files 0600, never overwritten). A backup that cannot be written stops the config write. Old
30
+ `.bak` files beside harness configs are listed by `sibyl doctor` and never deleted.
31
+ - Codex: a stale command path in `[mcp_servers.sibyl_memory]` is fixed in place; only the command
32
+ line changes, and a second table is never appended.
33
+ - Cursor and Grok Bot: a stale path in our own entry is updated without a prompt, keeping its
34
+ `env`, `args` and other keys.
35
+ - Cursor and Codex configs that are symlinks are written through to the file they point at; the
36
+ link is kept.
37
+ - Setup and doctor never print another tool's command string.
38
+
39
+ ### Fixed (review panel, 2026-11-14)
40
+ - `sibyl setup hermes` edits `config.yaml` as text instead of re-serializing it: comments,
41
+ anchors, key order, quoting and non-ASCII text stay as written. Only `memory.provider` changes
42
+ (or two lines are added), and the result must parse to the old data with only that value
43
+ changed. When that cannot be proven, setup prints the two lines to set by hand and leaves the
44
+ file alone. A `memory:` value that is not a mapping (`memory: honcho`) now counts as an
45
+ existing setting and goes through the overwrite question. A symlinked `config.yaml` is written
46
+ through and the link is kept, as for Cursor and Codex.
47
+ - `sibyl setup hermes` and `sibyl doctor --fix` honor the plugin installer's refusal codes. A
48
+ refused install (plugin folder not empty, a symlink, or not a Sibyl install) is an error that
49
+ says what to decide, and `memory.provider` is not switched.
50
+ - Codex: table headers are found structurally. Quoted keys such as `[projects."/path"]` and
51
+ `[mcp_servers."a@b"]` end our table, so `--force` no longer drops the trusted-project tables
52
+ after it and a table with no command line no longer takes the next server's command. A
53
+ `[mcp_servers.sibyl_memory]` line inside a multi-line string is not our table. The table
54
+ replace proof checks that every other line is kept, and a command edit must sit inside our
55
+ table.
56
+ - Codex: adding the table is proven before the write. A file that sets `mcp_servers` as a key
57
+ (an inline table), ends inside an open string or array, or does not parse is refused with the
58
+ exact text to add by hand. CRLF files keep CRLF. `sibyl doctor` reports a `config.toml` that
59
+ does not parse as unreadable instead of PASS, and setup no longer calls a table with no
60
+ command, or one that runs another server, "already wired".
61
+ - Codex: a quoted `"command"` or `'command'` key is recognized, so `doctor --fix` updates it in
62
+ place instead of adding a second command key. A missing command is fixable only when a TOML
63
+ parser is available.
64
+ - New dependency `tomli>=2` on Python 3.10, used when `tomllib` is not in the standard library,
65
+ so the Codex parse-and-compare proof runs on every supported Python. The text checks stay.
66
+ - Config writes create the temp file with `O_EXCL` under a unique name beside the target, set
67
+ the target's mode before any content is written, fsync the file and the directory, and remove
68
+ only their own temp file on failure.
69
+ - The CLI sends the session token only to https `*.sibyllabs.org` or a loopback host (the same
70
+ gate as the client library). Any other `SIBYL_API_BASE` gets a clear error and nothing is sent;
71
+ the legacy upgrade link is never built for another host.
72
+ - DeepSeek Harness: when setup or `doctor --fix` cannot update an existing row, the manual text
73
+ changes that row's command (or replaces the row) instead of adding a second row. `sibyl doctor`
74
+ prints the block on its own lines (and in `fix_block` in `--json`), so it stays valid YAML.
75
+ - Claude Code without the `claude` command on PATH: setup no longer writes `mcpServers` into
76
+ `~/.claude/settings.json` (Claude Code does not read servers from there) and no longer reports
77
+ the server as wired. It installs the hooks and skills and hands over the exact
78
+ `claude mcp add --scope user sibyl-memory -- <path>` command.
79
+ - Tests: the DeepSeek Harness proof layers and the `_atomic_text` symlink refusal each have a test
80
+ that fails when that check is removed; the version test reads `pyproject.toml`.
81
+ - With an untrusted `SIBYL_API_BASE` (not https `*.sibyllabs.org` and not a loopback address), `sibyl
82
+ status`, `refresh`, `devices`, `upgrade`, `email` and `claim` say the sign-in was not sent and hand
83
+ over `next: done` with "ask your human: SIBYL_API_BASE points at a host Sibyl will not send your
84
+ sign-in to; unset it", never "retry", "server error: 0" or "connect to the internet". The
85
+ explanation prints at most once per process (`sibyl upgrade` printed it twice). An untrusted
86
+ `SIBYL_UPGRADE_BASE` gets the same treatment. `sibyl whoami` makes no network call.
87
+ - The CLI refuses to send the sign-in to a URL with a backslash, whitespace, a control character or
88
+ userinfo (`https://evil.com\@sibyllabs.org/x` was allowed), on its own side, before the client's
89
+ host rule, and for the client gate's `/entitlement` refresh too, so cli 0.7.0 is protected with
90
+ sibyl-memory-client 0.10.0 installed.
91
+ - Codex: a `config.toml` that starts with a UTF-8 BOM is no longer called invalid TOML; the BOM is
92
+ kept.
93
+ - Hermes: the `config.yaml` edit is proven before the plugin install and the backup, so a file setup
94
+ cannot edit (`memory: {provider: x}`) ends with nothing installed, no backup and the two lines to
95
+ set by hand. Doctor reports `memory: honcho` as foreign, as setup does, not as absent. On an
96
+ installer refusal only setup's handoff is printed, not the installer's own `next:` line.
97
+ - `sibyl doctor` repair for Claude Code quotes the binary path in the manual `claude mcp add` command.
98
+ - README: the environment override examples use `staging.sibyllabs.org` and say where the sign-in
99
+ is sent.
100
+ - Tests: the Hermes `__init__.py` check after a zero-return install, the Codex doctor parser check
101
+ (duplicate `command` keys) and the open-string refusal message each fail when removed. CI runs on
102
+ push to main and on pull requests (once per PR branch), plus one Python 3.10 job on mcp 1.19.0.
103
+
104
+ ## [0.6.2] - 2026-11-12
105
+
106
+ ### Fixed
107
+ - `sibyl` crashed at import on Python 3.10 and 3.11 although the package declares
108
+ `requires-python >=3.10` (issue #32, reported by @drexthealpha). One f-string in
109
+ `sibyl status` reused its own quote inside a replacement field, which only parses on
110
+ Python 3.12+. Install succeeded and every command then failed with a SyntaxError.
111
+ - New test `tests/test_py310_syntax_2026_11_12.py` walks the token stream of all five
112
+ packages and fails on that construct, since Python 3.12's parser accepts it even with
113
+ `feature_version=(3, 10)`.
114
+
115
+ ## [0.6.1] - 2026-11-02
116
+
117
+ ### Fixed
118
+ - `sibyl setup cursor`, `sibyl setup grokbot`, `sibyl setup claude-code`, `sibyl setup codex` and
119
+ `sibyl doctor` now find `sibyl-memory-mcp` when it is installed but not on PATH. They look on
120
+ PATH, then beside the running Python, then in `~/.local/bin`, and write the absolute path into
121
+ the client config. On a fresh machine where `~/.local/bin` was not on PATH yet, setup used to
122
+ try to reinstall the server and then stop with "not on PATH. Install it" (field report from a
123
+ Grok Bot install, 2026-11-01).
124
+ - When the server really is missing, the error now says it is not installed and names the places
125
+ it looked, instead of "not on PATH".
126
+
127
+ ## [0.6.0] - 2026-10-31
128
+
129
+ One release: the paid tier R2 line, the shipped 0.5.0 fixes it was built beside, the graph line and the release merge items below.
130
+
131
+ ### Release summary
132
+ - `sibyl memory neighbors`: the edges of one node. Existing relations are carried over on first open.
133
+ - `sibyl setup cursor`, `sibyl setup grokbot`, `sibyl setup --print-config` and `sibyl doctor`.
134
+ - Carried from the 0.5.0 family already on PyPI (2026-10-14), now also on this line: the shown tier
135
+ and plan end on `sibyl status`, `sibyl update` for every package, `sibyl --version`.
136
+ - Pro: the Claude Code Stop hook records skill signals (names and hashes only, local).
137
+
138
+ ### Release merge (2026-10-28)
139
+
140
+ #### Grok Bot / Cursor / any-MCP onboarding
141
+
142
+ #### Added
143
+ - `sibyl setup cursor`: `CursorWirer` writes `~/.cursor/mcp.json` (`mcpServers.sibyl-memory`,
144
+ `{"type": "stdio", "command": <absolute sibyl-memory-mcp>}`, format per cursor.com/docs/context/mcp).
145
+ Timestamped backup, atomic write, foreign entries and a differing `sibyl-memory` entry are never
146
+ clobbered without `--force`, a corrupt file is never replaced, `_verify_mcp_starts` runs after.
147
+ Auto-detected by `sibyl setup` (`~/.cursor` or `cursor` / `cursor-agent` on PATH). `--cursor-config`.
148
+ - `sibyl setup grokbot`: the Cursor wiring plus a printed confirmation (server name, command path,
149
+ config file). Explicit target only; never auto-detected.
150
+ - No-detect fallback and `sibyl setup --print-config`: print the absolute `sibyl-memory-mcp` path and a
151
+ copy-paste `mcpServers` JSON block so any MCP client or agent can wire itself.
152
+ - `sibyl doctor` (`--json`): starts the MCP server, lists tools, saves a MARKED test memory
153
+ (`_sibyl_doctor/doctor-test-<uuid>`), recalls it, deletes it (`memory_forget` archives, so the exact
154
+ test row is then purged from `entities` and `archived_entities` and verified gone). Per-step
155
+ PASS/FAIL, exit 1 on any failure; a missing account reports "run `sibyl init`".
156
+
157
+ #### Changed
158
+ - `sibyl setup` never reads a non-terminal stdin at the multi-framework picker: it takes the same
159
+ default as end of input ("no terminal: wiring all detected"). An unknown target's handoff now names
160
+ every target (`hermes|claude-code|codex|cursor|grokbot`).
161
+ - Installer (`sibyllabs/install`, shipped with the site at publish, not in this package): tests that /dev/tty can
162
+ be opened; with no usable terminal it runs `sibyl setup --yes` instead of skipping; `--yes` aliases `--setup`.
163
+
164
+ #### Other
165
+ - `tests/smoke/venv-compat.sh`: one `sibyl memory neighbors` check on a v6 edge.
166
+ - The usage count keeps the opt-out default in the CLI (`test_telemetry_default_2026_10_28.py`, 2).
167
+ - Requires `sibyl-memory-client>=0.10.0`, `sibyl-memory-hermes>=0.6.0`, `[mcp]` `sibyl-memory-mcp>=0.4.0`.
168
+
169
+ ### Paid tier R2: skill signals (built 2026-09-29)
170
+
171
+ Spec plugin-paid-tier-r2-spec-2026-09-29 section 1. Requires sibyl-memory-client 0.10.0,
172
+ sibyl-memory-hermes 0.6.0 (and sibyl-memory-mcp 0.4.0 with the `mcp` extra). BYOK drafting
173
+ (spec section 2: `sibyl skills proposals draft`, `sibyl skills summarizer`, `byok.py`) is NOT in
174
+ this release (operator 2026-09-29).
175
+
176
+ ### Changed (tier convention, 2026-10-05; carried from 0.5.0)
177
+ - `sibyl status` Free / Pro / Elite, the `tier_unknown` access rows, the hooks mirror with elite
178
+ and the venv-compat Elite status check are carried from 0.9.0 / 0.5.0 (cherry-picked; the only
179
+ conflict was `tests/smoke/venv-compat.sh`, both blocks kept). See the 0.5.0 entry. Suite 456 -> 472.
180
+
181
+ ### Added
182
+ - The Claude Code Stop hook (Pro) records the workflow's tool sequence: it reads the transcript
183
+ from the session's stored byte offset, at most 4 MiB per Stop, keeps each `tool_use` block's
184
+ name and the hashed sorted key names of its input, and drops the parsed text. Free and locked
185
+ devices return before it (no file, no offset). The hook never runs the learner; the next MCP
186
+ server start (or Hermes shutdown) turns the record into proposals. Measured: see the release
187
+ notes.
188
+ - `sibyl skills signals [status|clear|off|on]`: status prints counts, size and dates, never an
189
+ entry; `clear` deletes `signals.json`; `off` stops recording; `on` starts it again from now.
190
+ Free: "Skill signals are on Pro." (`off` and `clear` still work, `on` changes nothing).
191
+ - `sibyl skills proposals`: `mute tool_sequence` / `mute correction_loop`; help names the
192
+ signals. `sibyl save --fact` counts as an entity write on Pro (hashed).
193
+
194
+ ### Tests
195
+ - `tests/test_hook_signals_2026_09_29.py` (12): canaries in `tool_use` input values and key
196
+ names never in any file under the home or the hook output; incremental offset; 4 MiB per Stop
197
+ on a 64 MB transcript (timed); offset reset on a changed or truncated transcript; an
198
+ unreadable transcript keeps the R1 output and the process exits 0; the `claude -p` rule; free,
199
+ locked and off; sidechain entries; a partial last line waits.
200
+ - `tests/test_skills_signals_cli_2026_09_29.py` (7): the four verbs on Pro, free and locked;
201
+ `save --fact`; the new kinds through list, show, accept (valid SKILL.md, reference copy),
202
+ reject, mute and unmute.
203
+
204
+ ### Changed (R2 check fixes, 2026-09-30)
205
+ - R2F-N4: `sibyl skills signals` help and status say the record keeps tool and MCP server names
206
+ (the Claude Code transcript names MCP tools `mcp__<server>__<tool>`), not tool names only;
207
+ README row and the repo README row the same.
208
+ - The Stop hook is now the only recorder of Claude Code tool events when it is wired (mcp 0.4.0
209
+ R2F-2); nothing changes in the hook itself. Suite 456 passed.
210
+
211
+ ### Tiered retrieval and relations (graph line, built 2026-10-22)
212
+
213
+ ### Changed - Adoption edge outcomes (V1 panel theme A, 2026-10-22)
214
+ - `sibyl memory adopt` reports links that were already in the account (not copied
215
+ twice) and links held back because their endpoint name exists in the account both
216
+ as itself and as `(before sign-in)` with no record of which one they meant (up to 5
217
+ listed, with how to clear them). A re-run with only held links says so instead of
218
+ "nothing to move".
219
+
220
+ ### Fixed - release train (V1 panel B, 2026-10-22)
221
+ - `version = "0.6.0"`, requires `sibyl-memory-client>=0.10.0`,
222
+ `sibyl-memory-hermes>=0.6.0` and (extra `mcp`) `sibyl-memory-mcp>=0.4.0`. README:
223
+ upgrade the packages together (`sibyl update --apply`).
224
+ - The version pin test moves to 0.6.0 (`test_package_version_is_0_6_0`).
225
+
226
+ ### Changed - bundled procedures v1.2.0 (tiered-retrieval section 3, 2026-10-22)
227
+ - `sibyl setup` / the lifecycle screens now report "procedures v1.2.0" (client SAVE.md
228
+ agent guidance: which tier to write, links with the node, read top-down). No CLI code
229
+ change; the lifecycle test pin moves 1.1.0 -> 1.2.0.
230
+
231
+ ### Added
232
+ - `sibyl memory neighbors (--entity CATEGORY NAME | --reference KEY | --state KEY)
233
+ [--relation R ...] [--direction out|in|both] [--tier T] [--limit N] [--cursor C]`:
234
+ read-only listing of one node's edges, tenant-resolved like `list` / `search` / `recall`.
235
+
236
+ ## [0.5.0] - Unreleased
237
+
238
+ ### 2026-10-14 - Pre-release cleanup
239
+ - `sibyl migrate` tells Hermes users to run `sibyl setup hermes` instead of editing
240
+ `~/.hermes/config.yaml` by hand.
241
+ - `sibyl setup --help` mentions Codex, and `--claude-settings` now says what it really sets: the
242
+ path to Claude Code's `settings.json` (default `~/.claude/settings.json`).
243
+ - The account host shown while waiting for approval and after `sibyl logout` follows
244
+ `SIBYL_ACCOUNT_BASE` when it is set. With the default, the text is unchanged.
245
+ - README: activation and status samples match what the commands print today (the free cap is
246
+ 5,242,880 bytes, not 2,097,152), tier drift points at `sibyl refresh`, `sibyl --version` is
247
+ listed, the Upgrade section describes the current Pro pricing and flow, and the PyPI
248
+ description names Pro / Elite instead of the retired staker / subscription tiers.
249
+ - Removed unused internal helpers and constants; docstrings describe current behavior.
250
+ - `sibyl upgrade`, when it opens the plugin upgrade page instead of the account billing page, now
251
+ names the current offer: Pro $12/month or $108/year (USDC for one fixed period, or by card plus
252
+ applicable tax at sibyllabs.org/checkout followed by `sibyl claim`), or free Pro while 100,000 $SIBYL stays
253
+ staked. It no longer mentions a quarterly USDC plan.
254
+ - Comments, docstrings, test file names and this CHANGELOG describe each finding by what it fixed
255
+ instead of naming testers or internal QA rounds. Text and test file names only; no code changed.
256
+
257
+ ### 2026-10-10 - sign-in and display fixes
258
+ - F-1 (contract C1): the api's 401 `signed_out_on_claim` (this computer was signed out when the
259
+ account's email was first confirmed on the account page) is named everywhere the CLI used to
260
+ say only "signed out · run sibyl init" or "session expired": the `sibyl status` Access row (from
261
+ the gate's refresh) and server row, `sibyl email`, `sibyl email verify|add|confirm`, `sibyl
262
+ devices`, `sibyl upgrade` and `sibyl claim` print `signed out: this computer was signed out
263
+ when your email was confirmed on the account page (<date> UTC). run: sibyl init --force`, and
264
+ the handoff is `next: sibyl init --force`. Any other 401 keeps its old line.
265
+ `gate_http_line` / `gate_http_handoff` take the error body. Tests:
266
+ `tests/test_signin_display_fixes_2026_10_10.py` (F-1 block).
267
+ - F-1a (contract C2): `sibyl init` with `cli_email_verify` on and the email unconfirmed sends the
268
+ code without the "confirm it now?" question; the only prompt is for the code (Enter skips).
269
+ Every path that leaves the email unconfirmed (Enter at the code prompt, a wrong or failed code,
270
+ no terminal, `--no-email`, and `cli_email_verify` off) prints `until you confirm your email
271
+ here, signing in on the account page signs this computer out. confirm later with: sibyl email
272
+ verify`. With no terminal no code is mailed unasked (the handoff stays `sibyl email verify`).
273
+ Tests: `tests/test_accounts_patch_2026_09_26.py` (two old rows rewritten, three added).
274
+ - `sibyl setup <agent> --dry-run` compares with what is installed and says "already
275
+ in" for the skills (`skills v<v>: SAVE.md, DEBLOAT.md already in <dir>`), each shim (`shim
276
+ <path>: already in`), the Claude Code hooks (`hooks: 5 already in <settings>`) and the Codex
277
+ AGENTS.md block (`block: already in <path>`); missing, outdated and edited files say what a real
278
+ run would do. Still reads only.
279
+ - times shown to people carry a zone, in UTC: `sibyl devices` (`last seen 2026-10-09
280
+ 19:08 UTC`), the computer-limit list at `sibyl init`, `sibyl status` (Tier cache checked,
281
+ offline "as of", Expires, Issued), `sibyl claim` (Covers through), `sibyl memory` (updated),
282
+ and the save/autosave rows (`last save`, `last 19:08 UTC`). New module `_timefmt.py`.
283
+ - `sibyl --version` prints every installed Sibyl package on one line, the CLI first:
284
+ `sibyl cli 0.5.0+dev.5 · client 0.9.0+dev.5 · mcp 0.3.0+dev.5` (hermes and langgraph when
285
+ installed). Still exits 0 without touching ~/.sibyl-memory.
286
+ - `sibyl init` offers "send USDC from any mobile wallet" (the section line, the
287
+ subtitle and the agent's ask line) only when session-init minted this session's USDC-send bind
288
+ (`bind_amount_micros` and `bind_bus_wallet` set); while USDC sign-in is off the api sends both
289
+ null and init lists two paths, desktop wallet and email plus code.
290
+ - Suite: 961 passed (was 930).
291
+
292
+ ### Fixed (`sibyl update` covers the MCP server, 2026-10-09)
293
+ - `sibyl update` now also updates the MCP server (and LangGraph when installed). It checks every
294
+ Sibyl package that is installed among `sibyl-memory-cli`, `-client`, `-hermes`, `-mcp` and
295
+ `-langgraph`, and `--apply` upgrades the outdated ones in one `pip install -U` call; a package
296
+ that is not installed is not shown and is never installed. Before, the MCP server that the
297
+ installer puts on every install (`sibyl-memory-cli[mcp]`) stayed on its old version. The
298
+ `--json` document has the same keys, with one row per installed package; the pipx hint and the
299
+ exit codes are unchanged. Tests: `tests/test_update_installed_pkgs_2026_10_09.py` (+13); two
300
+ pipx handoff rows list the five packages. Suite: 930 passed (was 917).
301
+
302
+ ### Added (version row, 2026-10-08)
303
+ - `sibyl --version` prints `sibyl <version>` (for example `sibyl 0.5.0` or `sibyl 0.5.0+dev.4`) and
304
+ exits 0. It needs no subcommand and reads or writes nothing under `~/.sibyl-memory`.
305
+ - `sibyl status` opens with a `plugin` eyebrow and one `Version cli <v> · client <v>` row (client
306
+ `not installed` when `sibyl-memory-client` is missing), in both the "Not activated." and the
307
+ activated layout, so a pasted status always carries the build. `sibyl whoami` is unchanged.
308
+ Tests: `tests/test_version_2026_10_08.py`. Tester guide line: `sibyl --version` replaces `pip list`.
309
+
310
+ ### Fixed (shown tier and plan end, 2026-10-08)
311
+ - F1: every tier the CLI shows is the tier of this computer's current verified pass, the saved
312
+ credentials tier only when there is no valid pass (`_account_gate.display_tier` /
313
+ `peek_tier`): `sibyl status` (LOCAL Tier row, the uncapped / percent-of-cap DB size, the
314
+ local vs server drift check), the `sibyl init` "already activated" and "Activated." rows,
315
+ `sibyl whoami` and the `sibyl upgrade` current tier. `sibyl status` takes the access check-in
316
+ before printing the LOCAL rows (output order unchanged) and re-reads the credentials the
317
+ check-in may have rewritten. A tier cache that disagrees with a valid pass reads
318
+ `superseded by the access pass (checked ...)` instead of a second tier. `sibyl refresh` and
319
+ the background re-check rewrite the saved tier (client `sync_credentials_tier`). Looking up
320
+ the pass with no `entitlement.json` evaluates nothing, so it never leaves a file behind.
321
+ - F2: the Access row says `active · re-checks in <h>h` (the pass re-check), not `renews in`,
322
+ which read like a billing renewal. A `Plan` row under it shows the billing date from the
323
+ pass's `acct.plan`: `Pro · ends 8 Oct 2027` (a cancellation, or a fixed term) or
324
+ `Pro · renews 8 Oct 2027` (a renewing card plan), in local time; no row when the server sends
325
+ no date (older api, Free, staker, Lifetime). The tier word is the one the Tier row shows.
326
+ - README: the status sample and the Access table use `re-checks in`, and describe the Plan row.
327
+ - Tests: `tests/test_tier_plan_2026_10_08.py` (+13); three label assertions updated to
328
+ `re-checks in`. Suite: 911 passed (was 898).
329
+
330
+ ### Changed (web-first onboarding QA patch, 2026-10-08)
331
+ Decision D21 of onboarding-friction-final-analysis-2026-10-08 (findings F7, F12, P1). Messages
332
+ only: flows, exit codes, streams and JSON keys are unchanged.
333
+ - F7: after `Activated.`, `sibyl init` ends `next: sibyl status` instead of `next: sibyl setup`
334
+ when an agent on this computer is already wired (the installer runs `sibyl setup` before
335
+ `sibyl init`, so this is the common case). The check is the one `sibyl email confirm` already
336
+ uses (row E24: Hermes or Codex config, or `sibyl-memory` in `~/.claude.json` or
337
+ `~/.claude/settings.json`; file reads only, no subprocess). When wired, `later: sibyl setup`
338
+ is no longer queued behind `sibyl email add <address>` or `sibyl email verify`. With nothing
339
+ wired the output is unchanged.
340
+ - Tests: seven new init rows (old api, verified, email required with none, unverified required
341
+ and not required, email confirmation not open, Codex wired), each with a harness wired.
342
+ - P1: the approve hint under the code reads "already have a Sibyl Memory account (website or
343
+ another computer)? approve this one at <url> instead (sign in there, then type this code)".
344
+ The account may exist only on the website, so "already set up with this email on another
345
+ computer?" was the wrong question.
346
+ - F12: with `features.device_approval` on, the `ask your human:` line printed while `sibyl init`
347
+ waits puts the likeliest path first: "if you already have a Sibyl Memory account, approve this
348
+ computer at <url> with the code <code>; otherwise open <activation page> and sign in with email
349
+ plus that code, a desktop wallet, or USDC from a mobile wallet; I pick it up here". An agent
350
+ relays one decision instead of four equal options. With the feature off the sentence is
351
+ unchanged. Tests assert the order, the code, the single `?r=` link and the unchanged
352
+ feature-off wording.
353
+ - The "wire it into your agent" block after `Activated.` no longer tells people to hand-edit
354
+ `~/.hermes/config.yaml`, `pip install sibyl-memory-mcp` or import the provider by hand (it
355
+ contradicted the install flow: installer, then `sibyl setup`, then `sibyl init`, and the
356
+ dd0ce76 Hermes fix). With nothing wired it is one line, "wire it into your agent: sibyl setup
357
+ (wires Claude Code, Codex and Hermes)", and the handoff stays `next: sibyl setup`. With an
358
+ agent already wired (the F7 check) nothing is printed and the handoff ends
359
+ `next: sibyl status`. Two new tests cover both cases and the absence of the old commands.
360
+
361
+ ### Fixed (agent handoff check, 2026-10-07)
362
+ Findings of the adversarial check of the handoff build (no loop left for an agent that follows
363
+ only `next:`). Messages only: flows, exit codes, streams and JSON keys are unchanged.
364
+ - Email, when the api does not take confirmation from the terminal (`features.cli_email_verify`
365
+ absent or false, row E11): `sibyl init` and the `sibyl email` state no longer hand back
366
+ `sibyl email add <address>` (which could only fail with `not_open` and ask for the address
367
+ again). They ask the person to add and confirm the email at the account page; init ends
368
+ `next: sibyl setup` with `later: sibyl email`, `sibyl email` ends `next: done`.
369
+ - `sibyl setup`: a wirer error with no specific handoff (a Hermes or Codex config write, a Hermes
370
+ install-plugin failure) ends `next: done` with `ask your human:` naming the harness and the
371
+ error, instead of `next: retry`. A server that did not start ends `next: done` with "run
372
+ sibyl-memory-mcp in a terminal and tell me the first error line" (a missing credential:
373
+ `next: sibyl status`). An already-wired harness gets no restart ask; only a changed one does.
374
+ - `sibyl update --apply`: a non-zero pip exit ends `next: done` with "pip exited N upgrading the
375
+ packages (output above); tell me what it said", instead of `next: retry`.
376
+ - `sibyl logout` (rows O1 to O3) ends `next: done` with `later: sibyl init`: signing out no
377
+ longer starts a sign-in.
378
+ - File labels in `sibyl debloat apply|auto|undo` handoffs, the undo hint and the migrate
379
+ "not trimmed" line are shell-quoted, so a label with a space still runs verbatim.
380
+ - Tests: the convention lint sweep now covers memory search and recall, adopt A3/A4/A6/A7,
381
+ debloat auto, manual and undo, skills install, update --apply (pip failed, pip missing, pipx,
382
+ upgraded), setup X4 and X6 to X16 through the real wirers, migrate N3 to N10 through
383
+ `cmd_migrate`, health H1c/H2c, plus the E11 email and logout rows; each new scenario also
384
+ asserts it reached the path it is named for. Suite: 879 passed, 1 skipped (the installed
385
+ Claude Code binary contract test, which skips without `claude` on PATH).
386
+
387
+ ### Added (agent handoff messages, 2026-10-06)
388
+ Spec agent-handoff-messages-spec-2026-10-03 (section 2 rows I, E, U, K, S, R, H, W, D, O, V, A,
389
+ F, G, P, T, Y, Z, X, N). Messages only: no flow, command, exit code or server contract changes.
390
+ - Every stop of a `sibyl` command ends with the handoff block, on stdout, TTY or not: zero or
391
+ more `later: <command>`, at most one `ask your human: <sentence>`, then `next: <command>`
392
+ (or `done`, `retry`, `retry in N minutes`), always the last line. Plain text at column 0, no
393
+ glyph, no colour. A placeholder (`<code>`, `<address>`, `<index>`, `<cs_code>`, `<file>`) only
394
+ appears with the `ask your human:` line that names it.
395
+ - Waits print `ask your human:` and `waiting: <what> (up to m:ss)` once when the watching
396
+ starts: `sibyl init` (the bind, the computer-limit sign-out, device approval) and
397
+ `sibyl upgrade` (the plan change).
398
+ - `--json` (`sibyl update`, `sibyl debloat`) prints no block; the document gains `next` and
399
+ `human_action`. `sibyl debloat --fyi` (one-line startup format) and `sibyl hook` (JSON for
400
+ Claude Code) print none.
401
+ - `_handoff.py` (the block, waits, the JSON keys) and `_account_gate.access_handoff()`, so
402
+ `status`, `refresh`, `health` and the gate lines agree; the values come from the client's
403
+ `ENTITLEMENT_NEXT` / `ENTITLEMENT_HUMAN_ACTION`.
404
+ - `sibyl claim` success line: "Run the next command and agents pick it up on their next call."
405
+ (was "Run `sibyl status` to see it. Your agent picks it up next session."). The tier-drift hint
406
+ in `sibyl status` names `sibyl refresh` (was `sibyl upgrade`, which opens a purchase page).
407
+ - Non-interactive runs say which default they took: `no terminal: default Y|N taken` (setup
408
+ questions), `no terminal: proceeding (pass --yes to say so)` (migrate), the extraction and
409
+ trim lines of the guided migration.
410
+ - Setup with nothing detected: `later: sibyl setup <target>`, the question, `next: sibyl status`.
411
+
412
+ ### Fixed (agent handoff messages, 2026-10-06; spec section 5.3)
413
+ - `sibyl setup` with two or more harnesses detected, no `--yes` and no terminal no longer raises
414
+ a traceback at the picker: it wires all detected, as `--yes` does, and says so.
415
+ - `sibyl save --fact` on a full free cap prints the cap line (`later: sibyl upgrade`,
416
+ `next: done`) instead of a `CapExceededError` traceback.
417
+ - `sibyl migrate` with nothing extracted (a run without a terminal verifies at once) prints
418
+ "Backed up and wired. Extraction has not run yet." instead of "Done. Your memory now lives in
419
+ Sibyl".
420
+ - The email `expired` fallback line needed no change (it is the copy when the server sends no
421
+ message); both paths are now tested.
422
+
423
+ ### Tests (agent handoff messages)
424
+ - `tests/conftest.py`: `handoff(out)`, `json_handoff(payload)`, `assert_convention(out, err)`.
425
+ - `tests/test_handoff_rows_2026_10_03.py`: one scenario per row, each through the lint.
426
+ - `tests/test_handoff_convention_2026_10_03.py`: the lint, a sweep over every scenario, and a
427
+ source check (no em dash, glyph or ANSI in handoff copy).
428
+ - `tests/test_agent_follows_next_2026_10_03.py`: an agent that reads only `next:` lines runs
429
+ init, email add, email confirm, setup, status to `done` against a stub api, and init, setup,
430
+ status to `done` against an old api.
431
+ - The claim copy helper in `test_accounts_patch_2026_09_26.py` drops the block lines. Suite:
432
+ 736 passed (453 before).
433
+
434
+ ### Changed (tier convention, 2026-10-05)
435
+ Spec tier-convention-spec-2026-10-05 section 5 (same coordinated release; version unchanged).
436
+ - `sibyl status` prints the tier as Free / Pro / Elite (local and server view, through the
437
+ client's shared `tiers` module); a legacy local label (stake) next to the server's canonical
438
+ one (pro) is no longer reported as drift. The computers line names the plan (`1 of 10 (Elite)`)
439
+ and the size line uses `tiers.is_paid`. Other tier lines (`init`, `whoami`, `claim`, `upgrade`)
440
+ keep their upper-case style but map legacy labels to the canonical word.
441
+ - Access row for an unrecognised signed label: `active · access label "<raw>" is not recognised
442
+ by this version, treated as Free (tier_unknown) · run sibyl update`; a 503 `tier_unknown` from
443
+ the server reads `renewal paused · access label check (tier_unknown) · keep working; it retries
444
+ on its own` and keeps the last valid token.
445
+ - Hooks: the stdlib-only `PAID_TIERS` mirror gains `elite` and still equals
446
+ `sibyl_memory_client.tiers.PAID_TIERS` (asserted); the unverified claim is stripped and
447
+ lowercased (`claim_label`); a `tier_unknown` answer is written to lifecycle.log.
448
+ - `tests/smoke/venv-compat.sh`: `sibyl status` with an elite entitlement prints Elite and exits 0.
449
+ - Tests: `tests/test_tiers_cli_2026_10_05.py` (+15, including the source guard: no legacy tier
450
+ literal outside the single hooks.py mirror line, which parses to the client set);
451
+ `test_f11_paid_tier_literal_matches_the_client` compares against `tiers.PAID_TIERS` and a sibling
452
+ covers elite / " Elite " / gold claims. Suite 437 -> 453.
453
+
454
+ ### Added (paid tier R1, 2026-09-29, R1B-2)
455
+ Plan plugin-paid-tier-2026-09-29, operator defaults D1-D15 (same coordinated release; version unchanged).
456
+ - The Claude Code Stop hook asks for a headless save by ACTIVE time on Pro: once early (5 memory
457
+ writes or a compaction), then every 60 active minutes (`sibyl autosave`), at most 8 a session and
458
+ 12 a day, only with something to save. Each request is numbered ("save 2 of this session") so
459
+ the transcript guard works per request. `UserPromptSubmit` counts prompts and active time on
460
+ both tiers (a gap after a turn counts at most 5 minutes; the model's own turn at most 30). A
461
+ scripted `claude -p` run (no transcript, or fewer than two prompts) is never continued.
462
+ SessionStart adds the tier-change line and, on Pro, up to 3 named skill proposals (read-only).
463
+ - `sibyl autosave [status|on|off|every <30-240>]` (free: says it is on Pro and keeps the setting).
464
+ - `sibyl refresh`: one entitlement check now, the before/after diff (tier, cap, computers, email,
465
+ access), the procedures, shims, Codex block and (already wired) hooks refreshed, the lifecycle
466
+ rows. Exit 0 (1 on an authoritative denial, 2 offline); with no account it exits 0 and says to
467
+ run `sibyl init`.
468
+ - `sibyl skills proposals [list|show|accept|reject|mute|unmute]` (Pro; free sees "on Pro").
469
+ `accept` writes a validated SKILL.md for the Claude Code, Codex and Hermes folders present (or
470
+ `--to <dir>`) plus the reference copy in memory; `reject` cools the slug off 30 days.
471
+ - Computer limit: `sibyl init` sends `replace: {session_token}` on session-init when this computer
472
+ already holds credentials (`--replace` implies `--force`); a `device_limit` answer (409, or
473
+ `/check` bound:false with `limit`) prints the computers and, in a terminal, says this terminal
474
+ cannot sign another computer out and asks "Open the account page to sign <label> out? [y/N]"
475
+ (yes opens the account Security page, says to sign it out there and finish the sign-in in the
476
+ browser, and keeps waiting), otherwise clear instructions and exit 2. The Free upgrade line
477
+ names the Pro limit only when the api sends one (`pro_limit`), else "every computer you use". `sibyl devices` and `sibyl status` show
478
+ `1 of 1 (Free) · Pro: up to 10`; the read-only access row names the computer limit.
479
+ - Codex AGENTS.md block: obey a Sibyl Memory `notice` asking for a save.
480
+
481
+ ### Fixed (paid tier R1 check, 2026-09-29, R1B-4)
482
+ - Over-the-limit copy says new memories save only on "the computer that signed in most recently"
483
+ (the server keeps the newest sign-in writable), not "the most recently used computer".
484
+ - The device-limit prompt no longer offers to "sign out ... and use this computer instead": this
485
+ terminal cannot sign another computer out, so it asks to open the account page and says what to
486
+ do there; the Free upgrade line has no hard-coded "up to 10".
487
+ - Stop hook: an automatic-save request is recorded (per-session and per-day caps, the interval)
488
+ only when it is emitted; one suppressed by the transcript guard costs nothing and the next one is
489
+ numbered past it. A compaction makes only its own session due (the per-session
490
+ `compaction_seen`); the write count stays the account's (plan D6.5).
491
+
492
+ One coordinated release with the accounts page. Two things change for users:
493
+ every Sibyl Memory account needs a confirmed email for receipts, security
494
+ notices, purchases and recovery (email does not gate memory), and **an
495
+ activated account is now required for agents to use memory** (MCP, Hermes,
496
+ LangGraph, the SDK). This is a FIVE-package release, not the CLI-only publish
497
+ this entry first described: `sibyl-memory-client` 0.9.0, `sibyl-memory-hermes`
498
+ 0.5.0, `sibyl-memory-mcp` 0.3.0, `sibyl-memory-langgraph` 0.3.0 and this CLI
499
+ (the number stays 0.5.0, decision D8). Floors: `client>=0.9.0`,
500
+ `hermes>=0.5.0`, `mcp>=0.3.0` (extra), so a partial upgrade cannot pair a gated
501
+ adapter with an un-gated engine. `credentials.json` schema is unchanged; a new
502
+ `entitlement.json` sits beside it. After a confirm the credentials file is
503
+ rewritten from the credentials the server re-signed; a local tier hint drops
504
+ the old signature (see Security). `sibyl memory` never needs an account.
505
+ Verified in a fresh venv with the five built wheels against hermes-agent 0.19.0
506
+ (current on PyPI at build).
507
+
508
+ ### Added (save and debloat, 2026-09-27, SD-2)
509
+ Spec plugin-save-debloat-spec-2026-09-27 (same coordinated release; version unchanged).
510
+ - `sibyl save` (`--fact`, `--capsule` on Pro, `--preview`, `--status`; bare prints the three
511
+ ways to run the save procedure and writes nothing).
512
+ - `sibyl debloat` (report, `--fyi`, `--json` with the plan when a policy exists, `--root`,
513
+ `--config`, `--include`; always exits 0), `sibyl debloat plan`, `apply [<file>] [--yes]`
514
+ (free: sibling `*-history` file; Pro: a memory reference document; a verified backup first),
515
+ `auto <file>` / `manual <file>` (the standing per-file authorisation), `undo [<file>]`.
516
+ - `sibyl skills install|status|reset|uninstall`, `sibyl reminders on|off|quiet`, and
517
+ `sibyl hook <event>` (installed by setup; not for manual use).
518
+ - `sibyl setup` / `sibyl migrate` wiring: Claude Code gets `~/.claude/skills/sibyl-save` and
519
+ `sibyl-debloat` plus five hooks in `~/.claude/settings.json` (SessionStart, UserPromptSubmit,
520
+ Stop, PreCompact, SessionEnd; absolute `sibyl` path; timeout 5 s; merged without touching
521
+ any other hook); Codex gets a marked block in `~/.codex/AGENTS.md` (no custom-prompt files:
522
+ Codex CLI 0.135.0 has no `~/.codex/prompts` loader, spec D9 fallback); Hermes gets
523
+ `$HERMES_HOME/skills/`. `sibyl init` installs the procedures right after `entitlement.json`;
524
+ `sibyl update --apply` refreshes them. `sibyl status` gains the `lifecycle` rows.
525
+ - The Claude Code hooks: free = reminders (debloat FYI and unsaved-last-session at start,
526
+ save-due on a prompt); Pro = the start runs the debloat plan and reports, Stop asks the model
527
+ to run the save procedure headless (R1: by active time, see above; at 5 writes or after a compaction; never
528
+ on `stop_hook_active`; never twice), PreCompact and SessionEnd write the session capsule.
529
+ Output shapes verified against Claude Code 2.1.283's hook schemas.
530
+
531
+ ### Changed (save and debloat)
532
+ - `sibyl migrate`'s trim step covers every instruction file the scan found (`CLAUDE.md`,
533
+ `AGENTS.md`, `.cursorrules`, ...), one question per file, each backup re-verified; config
534
+ files are never trimmed; `.cursor/rules` is measured, not trimmed; a project `.debloat.json`
535
+ surface narrows the candidates; a lean version keeping under 10 % or over 90 % is skipped.
536
+ The summary prints one `trimmed` line per file with its name. `--codex-config` now reaches the
537
+ Codex wirer.
538
+
539
+ ### Tests (save and debloat)
540
+ - `test_lifecycle_cli_2026_09_27.py` 32, `test_migrate_trim_2026_09_27.py` 9; three existing
541
+ tests adjusted for the per-file trim records and the trim safety bounds (test_orchestrator,
542
+ test_prelaunch_fixes CLI-9, test_setup no-op). `tests/smoke/venv-compat.sh` gains the
543
+ save/debloat checks.
544
+
545
+ ### Fixed (second independent check of save and debloat, 2026-09-27, SD-11 to SD-13)
546
+ - A symlinked folder above an instruction file no longer disables debloat (Fedora Atomic's
547
+ `/home -> var/home`, a stow-style `~/.claude -> ~/dotfiles/claude`, a project opened through a
548
+ link): the file is trimmed at its real location, never written through the link. `--root` is
549
+ resolved to its real path; `auto`, `manual` and `undo` use the real-path identity. A file whose
550
+ real location is outside your home and the project is refused.
551
+ - `sibyl debloat undo` without a file undoes the exact file the last apply trimmed (recorded by
552
+ path); in another project it says where that file is instead of restoring the same name here.
553
+ - An interactive `sibyl debloat apply` interrupted right after the rewrite keeps the backup.
554
+
555
+ ### Tests (second independent check)
556
+ - `test_sd_final_cli_2026_09_27.py` (5): `--root` through a symlink, `auto` stores the real path,
557
+ a stow `~/.claude` free apply, bare undo across two projects, a record without an id.
558
+
559
+ ### Fixed (independent check of save and debloat, 2026-09-27, SD-7 to SD-10)
560
+ - `sibyl debloat auto <file>` authorises that file at its path ("Automatic context trim for this
561
+ file at <path> means: ..."); `manual` takes a name or a path; name-only entries from the earlier
562
+ build are dropped with a one-time notice (`sibyl debloat`, `sibyl status`).
563
+ - `sibyl debloat undo` restores the backup the file's last apply recorded and refuses one that is
564
+ identical to the current file.
565
+ - Claude Code hooks never touch the network: the hook client's entitlement gate never refreshes,
566
+ its usage heartbeat is off, and a trim or capsule is written only when the cap gate decides
567
+ locally and within 2.5 s of the hook's start (otherwise the start plans only). Measured worst
568
+ case 0.29 s (was 17.5 s with a slow network); the timeout stays 5 s.
569
+ - `sibyl` starts at `sibyl_memory_cli._entry.main`: `sibyl hook <event>` runs with the standard
570
+ library only until a hook needs the client; the free Stop returns on the unverified tier claim
571
+ (a paid claim is always verified); free PreCompact / SessionEnd neither verify nor open
572
+ memory.db. Free Stop 0.19 s -> 0.04 s. The package `__init__` is lazy.
573
+ - Hook commands are `[ -x <sibyl> ] && exec <sibyl> hook <event>; exit 0`: they exit 0 quietly
574
+ once the package is gone; setup replaces entries of the earlier form. `sibyl skills uninstall
575
+ --help` says to run it before `pip uninstall`.
576
+ - Codex: two skill shims in `~/.codex/skills/` (the format Codex CLI 0.135.0 validates).
577
+ - `sibyl migrate` trim pointer: "a full copy of this file is in the backup ...; the migrate
578
+ extraction stored entries in Sibyl Memory".
579
+ - `sibyl status` / `sibyl save` say when the Pro save nudge comes.
580
+ - `venv-compat.sh`: four more checks (Codex dry run, the entry point, a wheel `sibyl hook stop`,
581
+ the guarded command with the binary gone).
582
+
583
+ ### Tests (independent check of save and debloat)
584
+ - `test_sd_fixes_cli_2026_09_27.py`; adjusted `test_lifecycle_cli_2026_09_27.py` (per-path
585
+ authorisation, warm tier cache for Pro hook writes, the guarded hook command, Codex skills) and
586
+ `test_migrate_trim_2026_09_27.py` (pointer text).
587
+
588
+ ### Fixed (independent check fix batch, 2026-09-27, GATE-15)
589
+ - `_bearer_headers` (used by `/access`, `/email-verify/request`,
590
+ `/email-verify/confirm`, `/upgrade-nonce`, `/stripe-claim`) now refreshes
591
+ first when this computer holds no usable token (the same ensure-fresh path
592
+ the logout / revoke calls use: one blocking `/entitlement` attempt, then
593
+ whatever usable token exists; a failed refresh sends none). Before, a device
594
+ back from offline past `exp + og`, or one that had not finished setup, sent
595
+ no token and would meet the cutoff's 403.
596
+ - A 403 `client_too_old` while this computer holds no usable token now prints
597
+ the setup line ("setup is not finished on this computer. connect to the
598
+ internet once to finish setup. nothing was deleted."), not "update the
599
+ plugin": the plugin is current, the api refused the absent token. With a
600
+ token (or no client gate available) the update line stays. Applies to
601
+ email, devices, claim and upgrade.
602
+ - Repo README: the fork table says `/check-write` refuses "from the client
603
+ cutoff"; the privacy paragraph says the size check and the usage count also
604
+ carry this computer's signed access token.
605
+ - Tests: `test_release_fixes_2026_09_27.py` 15 (13 fail before; the two
606
+ guards, a usable token is not refreshed and `client_too_old` with a token
607
+ still says update, pass before and after).
608
+
609
+ ### Added (gate fix before the independent check, 2026-09-27)
610
+ - `sibyl memory adopt [--yes]`: moves the store's rows written before sign-in
611
+ (the pre-account default tenant) into the signed-in account (client
612
+ `_adopt`: one local transaction, nothing deleted, a key the account already
613
+ has kept as `<key> (before sign-in)`, an audit row in the store, no network
614
+ of its own). Needs a verified sign-in. When the store has held another
615
+ account it explains and asks (`--yes` skips the question; a non-terminal
616
+ without `--yes` moves nothing). A re-run says there is nothing to move.
617
+ - `sibyl init` does the same move on the first sign-in right after writing
618
+ `entitlement.json`, and prints the row count only (never content). A store
619
+ that has held another account is left alone with a pointer to
620
+ `sibyl memory adopt`.
621
+ - `sibyl status`: the default-tenant hint names `sibyl memory adopt`; a new
622
+ `access` row `setup not finished · connect to the internet once to finish
623
+ setup` for credentials that have not received their first entitlement (the
624
+ client no longer grants an offline bootstrap grace).
625
+
626
+ ### Added (account gate, 2026-09-27)
627
+ - `sibyl init` writes `entitlement.json` (0600, atomic, symlink-refusing) from
628
+ the `entitlement` the api sends next to `credentials` on `/check`, right after
629
+ credentials.json, and drops a token bound to a previous sign-in. An api that
630
+ sends none prints nothing new; the client bootstraps on first use. A
631
+ malformed value (not a string, over 4096 bytes, not SE1-shaped) is ignored.
632
+ - `sibyl email confirm` writes the re-issued `entitlement` from the confirm
633
+ answer (the account state inside it must not lag a week).
634
+ - Every session-authenticated call carries `X-Sibyl-Entitlement` when this
635
+ computer holds a verified, bound token inside its offline grace (spec 5.6);
636
+ a token the api would refuse is never sent. `sibyl claim` now sends the
637
+ bearer headers too.
638
+ - `sibyl devices`, `sibyl devices revoke` and the logout revoke: with no
639
+ usable token they try one `/api/plugin/entitlement` refresh first, and on a
640
+ 403 `entitlement_invalid` they retry once without the header, so signing out
641
+ or revoking a lost computer never blocks on the gate.
642
+ - A 403 `entitlement_invalid` prints "this computer's sign-in file is damaged,
643
+ expired or belongs to another computer. run sibyl init to sign in again.";
644
+ a 403 `client_too_old` prints "update the plugin: pip install -U ..." (email,
645
+ devices, claim, upgrade).
646
+ - `sibyl status`: an `access` row after one check-in attempt (`active · renews
647
+ in <h>h`, `offline · <n> days of grace left · connect once to renew`,
648
+ `paused · offline too long ...`, `signed out · run sibyl init`, `under review
649
+ · email sibyl@sibyllabs.org`, ...); when the server is unreachable, the
650
+ account rows from the last check-in labelled `as of <date>`; with no
651
+ credentials, "agents cannot use memory until you do. your local data is
652
+ kept."; a count-only hint when the default store holds entities under the
653
+ pre-account default tenant.
654
+ - `sibyl logout` also removes `entitlement.json` (listed under `removed`).
655
+ - `sibyl health` prints the entitlement state and the pinned key ids.
656
+ - `sibyl memory list|search|recall` read local data with no account and no
657
+ network (a constructor-injected test gate, on purpose) and print "reading
658
+ local data without an account. agents need sibyl init." when there is none.
659
+ `sibyl migrate` says the extraction step needs `sibyl init`.
660
+
661
+ ### Added
662
+ - `sibyl email`: shows whether the account email is confirmed, not confirmed,
663
+ or missing. `sibyl email add <address>` and `sibyl email verify` send a
664
+ six-digit code (`POST /api/plugin/email-verify/request`) and, in a terminal,
665
+ prompt for it; `sibyl email confirm <code>` confirms it from scripts
666
+ (`POST /api/plugin/email-verify/confirm`). Confirming from this computer keeps
667
+ it signed in and signs out every other computer set up on the account before.
668
+ - `sibyl init` finishes the account right after `Activated.`: a wallet
669
+ activation is asked for an address, an email activation is offered a code to
670
+ confirm the address. Terminal only; `--no-email`, a non-TTY shell or
671
+ `SIBYL_NONINTERACTIVE=1` skip the prompt and print the one-line reminder.
672
+ - `sibyl init` follows web device approval: when the email already has an
673
+ owner it prints `approve this computer at https://account.sibyllabs.org/activate?r=...`
674
+ once, switches the spinner to `waiting for approval at account.sibyllabs.org`,
675
+ and stops with exit 2 when the owner chose "Not me". The link names the
676
+ request by a sha256 handle, never the session id.
677
+ - `sibyl status` rows `Email`, `Account` (incomplete, the grace date, and
678
+ whether purchases are refused) and `Dashboard`, when the server reports them.
679
+ - `SIBYL_ACCOUNT_BASE` override for the account page origin (testing only).
680
+
681
+ ### Changed
682
+ - `sibyl dashboard` opens the account page the server advertises
683
+ (`features.web_dashboard_url`) with no token in the URL; you sign in there
684
+ with your email or wallet. While the page is not open it prints
685
+ `the account page is not open yet.` and shows `sibyl status` as before.
686
+ - `sibyl upgrade` opens the account billing page when the server offers card
687
+ checkout there, otherwise the stake / USDC page through the one-time
688
+ `upgrade-nonce` exchange link. An expired session prints `session expired.
689
+ re-run sibyl init.` (exit 1, nothing opened); any other failure except a
690
+ missing endpoint prints `could not start the upgrade. try again.` and exits 2.
691
+ It warns `a confirmed email is required before buying` whenever the server
692
+ says purchases are blocked (`account.purchase_blocked`), not only past grace.
693
+ - `sibyl claim` explains the two new refusals by their `code`:
694
+ `unclaimed_account` (run `sibyl email verify`, or `sibyl email add` when no
695
+ email is on file, then claim again) and `email_required` (add and confirm an
696
+ email, then claim again).
697
+ - `sibyl devices` / `devices revoke` print `this account is under review.
698
+ email sibyl@sibyllabs.org.` for a review hold instead of a raw body, and
699
+ `already revoked` for a device revoked earlier. `sibyl logout` says
700
+ `signed out on the server too.` when the server confirmed the revoke.
701
+ - `sibyl whoami` is unchanged and still offline: it does not show whether the
702
+ email is confirmed. Use `sibyl email` or `sibyl status`.
703
+
704
+ ### Security
705
+ - A signed field of `credentials.json` (account, tenant, tier, email, wallet,
706
+ issued_at, schema_version) never changes under an old signature.
707
+ `sibyl email confirm` writes the credentials the server re-signed (through
708
+ the same field allowlist as `sibyl init`, keeping this computer's bearer) and
709
+ changes nothing when the server sends none. `sibyl upgrade` and `sibyl claim`
710
+ still write the new `tier` (and the staker `wallet`) as a local hint, and
711
+ drop `signature` and `signed_at` from the file with that edit (neither is in
712
+ the allowlist; `sibyl init` never writes them), so the plugins send no
713
+ signed claim for it. 0.4.1 kept the old signature next to the edited field,
714
+ which the server reports as a stale or tampered credential.
715
+ - `sibyl upgrade` no longer puts the bearer in the browser URL. It uses the
716
+ one-time exchange code (or the account page, which takes no token). The old
717
+ `?session=` link is used only against an api that has no `upgrade-nonce`
718
+ endpoint at all.
719
+ - `sibyl dashboard` no longer opens `SIBYL_DASHBOARD_BASE?session=<bearer>`;
720
+ the variable is ignored.
721
+ - Links printed or opened on the account origin are checked first: an approval
722
+ link must be `https://account.sibyllabs.org/activate?r=<64 hex>`, and a
723
+ dashboard link must be that origin exactly (a lookalike host such as
724
+ `account.sibyllabs.org.example` is refused).
725
+
726
+ ### Compatibility
727
+ - Against an api from before this release (no `features`, no `account`, no
728
+ email-verify endpoints) 0.5.0 prints what 0.4.1 printed: no prompts, no new
729
+ status rows; `sibyl email` says `this server does not report email state
730
+ yet.`, and `sibyl email add/verify` say email confirmation is not available
731
+ on this server yet.
732
+
733
+ ## [0.4.1] - 2026-09-04
734
+
735
+ ### Added
736
+ - `sibyl claim <code>`: links a card purchase (Stripe checkout) made at
737
+ sibyllabs.org/pro to the account activated on this machine. Works with
738
+ email and wallet activation alike. Sends the bearer as session_token so
739
+ the server verifies the caller controls the destination account, not
740
+ just the receipt. On success the local tier hint and tier cache sync
741
+ immediately.
742
+ - **Platform line, and a native-Windows gate.** Sibyl Memory runs on Linux,
743
+ macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is
744
+ not supported. `sibyl init` and `sibyl setup` now print the detected platform
745
+ and, on native Windows, refuse with a pointer to
746
+ https://docs.sibyllabs.org/memory/install#windows and the exit hatch
747
+ `SIBYL_ALLOW_NATIVE_WINDOWS=1`. Every other command is untouched, so a machine
748
+ that already activated on native Windows keeps `status`, `upgrade`, `claim`,
749
+ `devices`, `logout`, `health`, `memory` and `update` working. WSL2 reports as
750
+ Linux to Python and to us, so it passes with the label "Linux, WSL2". A
751
+ platform nobody has tested warns and continues; it is never blocked.
752
+ `sibyl status` gained a `Platform` row and `sibyl whoami` now names the
753
+ platform in the device line instead of the bare OS family.
754
+ - `sibyl init` reports `os_version`, `arch` and `wsl` alongside `os_family` in
755
+ the session-init payload, so the account record can tell WSL2 from native
756
+ Windows. Kernel release string and machine type only, no PII.
757
+
758
+ ### Changed
759
+ - The account id now prints IN FULL on every display surface (`whoami`,
760
+ `status`, `upgrade`, `init`) instead of the truncated `12345678…abcd`
761
+ form. It is a routing identifier the claim flow and the upcoming
762
+ accounts page require users to read verbatim; it is not a bearer secret,
763
+ and the never-print-the-bearer invariant is unchanged. Email and wallet
764
+ masking are unchanged (`--full` still governs those).
765
+ - **Dependency floor raised to `sibyl-memory-client>=0.8.1`**, which carries
766
+ the shared `_trust` context and declares `certifi` as a real dependency.
767
+ Without the floor bump a fresh install could resolve an older client, the
768
+ import fallback would quietly return the same broken default context, and
769
+ the fix would not actually ship. The floor is what makes certifi land in
770
+ every install path, pipx included.
771
+ - Package metadata now names the supported platforms: `Operating System ::
772
+ POSIX :: Linux` and `Operating System :: MacOS`. Sibyl Memory runs on Linux,
773
+ macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is
774
+ not supported. Classifiers are informational; pip does not enforce them, and
775
+ WSL2 installs look like Linux to pip, which is correct.
776
+
777
+ ### Fixed
778
+ - **`sibyl init` failed on macOS python.org "Framework" builds: `Warning:
779
+ session-init failed (0)`, browser pairing ended in "session not valid /
780
+ Bind failed", and `sibyl status` showed `server error: 0`.** That build
781
+ ships no CA bundle wired into Python's own OpenSSL (users are told to run
782
+ `Install Certificates.command`; many never do), so every
783
+ `urllib.request.urlopen` with the stdlib default context raised `[SSL:
784
+ CERTIFICATE_VERIFY_FAILED]` against api.sibyllabs.org, surfacing through
785
+ `http_request`'s URLError branch as status 0, while Safari and curl worked
786
+ (they read the system Keychain), which made the CLI look selectively
787
+ broken. Both CLI network paths (`http_request` and the `_pypi_latest`
788
+ update check, which was silently returning nothing on these machines) now
789
+ pass an explicit verified context from
790
+ `sibyl_memory_client._trust.https_context()`: platform trust store PLUS
791
+ certifi's CA bundle, additive only, hostname and chain verification fully
792
+ on. With no `sibyl-memory-client` importable (bare source tree) the CLI
793
+ degrades to the stdlib default context instead of crashing.
794
+ Reported by @keyurbodar (Sibyl-Labs/Sibyl-Memory#29); independent
795
+ implementation.
796
+
797
+ ## [0.4.0] "Lucid" - 2026-08-31
798
+
799
+ Minor version: `sibyl memory search` prints a new `cause:` line on the zero path,
800
+ so anything parsing this command's output should read this entry.
801
+
802
+ - Floors `sibyl-memory-client>=0.8.0`, `sibyl-memory-hermes>=0.4.0` and, in the
803
+ `mcp` extra, `sibyl-memory-mcp>=0.2.0`. The CLI prints causes it does not own;
804
+ an old client underneath a new CLI would leave it printing a cause line for a
805
+ verdict that is never populated.
806
+
807
+ ### Changed
808
+ - **`sibyl memory search` explains a zero instead of just reporting one** (branch
809
+ `lang-core-verdict`, 2026-08-31). It used to print `(no matches for 'x')` and
810
+ stop — the terminal-shaped version of the defect this stage closes, and the
811
+ reader is usually a new user deciding whether the product works. Saying "no
812
+ matches" against a store that is simply EMPTY was the single most misleading
813
+ thing this command could do. It now prints the canonical cause in plain
814
+ language plus a machine-readable `cause: <code>` line, and pays one count on
815
+ the zero path so `empty_store` is reported as what it is: a fixable state, not
816
+ a failed search. The success path is unchanged and prints no extra noise.
817
+ - The cause vocabulary is imported from `sibyl_memory_client.verdicts`; the CLI
818
+ prints causes, it does not own them. A test asserts it declares none.
819
+
820
+ ## [0.3.23] - 2026-08-22
821
+
822
+ ### Changed
823
+ - Require `sibyl-memory-client>=0.7.0` so `sibyl update` / a fresh install pulls
824
+ the multi-language search part-4 fixes (N4/N5/N1'-diagnostics: a nonzero-df
825
+ function word no longer anchors/pollutes ranking, a dropped negation word
826
+ abstains instead of silently answering the opposite). No CLI code change.
827
+ See `sibyl-memory-client` 0.7.0 CHANGELOG for the full N4/N3'/N5/N1' detail.
828
+
829
+ ## [0.3.22] - 2026-08-16
830
+
831
+ ### Changed
832
+ - Require `sibyl-memory-client>=0.6.1` so `sibyl update` pulls the multi-language search part-3 fixes (N1/N2/N3: the agent-default MCP path now reaches PL/EN recall parity on question-shaped queries). No CLI code change.
833
+
834
+ ## [0.3.21] - 2026-08-12
835
+
836
+ Multi-language search, part 2 (Polish-language evaluation) — CLI leg.
837
+
838
+ ### Fixed
839
+ - **F1 — `sibyl memory list/search/recall` read the wrong tenant on an
840
+ activated account.** `cmd_memory` opened the store at the hard-coded
841
+ `DEFAULT_TENANT` while the MCP server writes under the account's real tenant,
842
+ so an activated account saw `(no entities)` / `(no matches)` for a perfectly
843
+ healthy store — the surface that made the Polish eval first look like a recall
844
+ failure before the linguistic gap was even reached. `cmd_memory` now resolves
845
+ the tenant from `credentials.json` via the same Contract-T ladder the server
846
+ uses (`tenant_id -> account_id -> DEFAULT_TENANT`, matching `server.py`), like
847
+ `status`/`health` already did, with a call-time `--creds` default fallback so
848
+ direct-`Namespace` unit invocations still resolve. Read-only; no write path
849
+ touched.
850
+ - **Free-tier cap display corrected: 2 MB to 5 MB.** The `sibyl upgrade`
851
+ subtitle still showed the pre-2026-08-06 cap; the free-tier local cap was
852
+ raised to 5 MiB in the 0.5.0 release. Display-only, no logic change.
853
+
854
+ ### Changed
855
+ - **Dependency floor raised to `sibyl-memory-client>=0.6.0`.** `sibyl memory
856
+ search` / `sibyl recall` now inherit the F2 unconditional-shadow append and
857
+ the D2L coverage-gated stem rescue, taking Polish recall to parity with
858
+ English on the eval battery (see `sibyl-memory-client` 0.6.0). No CLI code
859
+ change for this leg.
860
+
861
+ ## [0.3.20] - 2026-08-06
862
+
863
+ ### Changed
864
+ - **Dependency floor raised to `sibyl-memory-client>=0.5.0`** for multi-language
865
+ search (schema v4). `sibyl search` / `sibyl recall` now resolve non-ASCII,
866
+ non-Latin, CJK, Thai, and compound-token queries that previously returned
867
+ nothing (100-language sweep: 21/100 → 100/100). No CLI code change. See
868
+ `sibyl-memory-client` 0.5.0.
869
+
870
+ ## [0.3.19] - 2026-07-05
871
+
872
+ Super-patch: recovery + adjudication of the remaining Fable 10-lens audit
873
+ findings (`plugin-hardening-superpatch-plan-2026-07-05.md`).
874
+
875
+ ### Fixed
876
+ - **`sibyl logout` never revoked the server-side bearer (Real #4).** The
877
+ account bearer has no server-side expiry, so a logout that only unlinked
878
+ local credentials left the token valid forever. `logout` now revokes
879
+ THIS device's bearer first, reusing the exact endpoint + auth shape
880
+ `sibyl devices revoke` already uses (`GET /api/plugin/devices` to
881
+ identify this device via `is_this_device`, then
882
+ `POST /api/plugin/devices {"bearer_id": ...}`) — no new endpoint. Fully
883
+ best-effort: any network/HTTP failure, or an inability to identify this
884
+ device's server record, prints the same offline caveat
885
+ (`sibyl devices revoke` from another device) instead of blocking local
886
+ logout, which still proceeds unconditionally.
887
+ - **`credentials.json` dropped the server-issued `tenant_id` (Contract
888
+ T).** `cmd_init`'s field allowlist (`_CRED_FIELDS`) omitted `tenant_id`,
889
+ so every activated account silently fell back to the shared
890
+ `DEFAULT_TENANT` on every surface (client/mcp/hermes/langgraph) instead
891
+ of resolving to its own tenant. `tenant_id` is now persisted alongside
892
+ `account_id`, so all surfaces resolve the SAME tenant from one
893
+ credentials file via the canonical ladder
894
+ `tenant_id -> account_id -> DEFAULT_TENANT`.
895
+
896
+ ### Changed
897
+ - Packaging: added the `Repository` URL
898
+ `https://github.com/Sibyl-Labs/Sibyl-Memory` to `[project.urls]`
899
+ (previously omitted) (R27), and bounded the third-party `pyyaml`
900
+ dependency to `>=6.0,<7` (R29).
901
+
902
+ ## [0.3.18] - 2026-06-30
903
+
904
+ Post-launch quality fixes from external audit reports (#13, #19, #15). All LOW
905
+ severity; diagnostic/robustness only — no behavior change to wiring or the cap
906
+ gate itself.
907
+
908
+ ### Fixed
909
+ - **`status` DB size now matches the cap gate (#13, B001).** `sibyl status`
910
+ reported the raw `memory.db` file size (`Path.stat().st_size`), but the
911
+ free-tier cap is enforced against the WAL-inclusive logical size
912
+ (`sibyl_memory_client.storage.db_size_bytes`). During a write burst the raw
913
+ file under-reports (committed pages still in `memory.db-wal`), so the displayed
914
+ size/percentage disagreed with what the gate actually checks. `status` now uses
915
+ the same `db_size_bytes()` measure.
916
+ - **`migrate` SQLite connections always close (#19, B001).** `verify_new_entries`
917
+ (and the sibling `db_baseline`) closed the connection only on the success path;
918
+ a `sqlite3.Error` mid-query leaked the open connection. Both now wrap
919
+ connect+query in `try/finally`.
920
+ - **`migrate._tree_size` tolerates un-statable entries (#19, B005).** A
921
+ permission-denied file or broken symlink under the scanned tree raised `OSError`
922
+ and aborted the whole size estimate. Each entry is now guarded independently and
923
+ the offending one is skipped.
924
+ - **`setup` config backups are timestamped (#19, B005).** Hermes/Claude/Codex
925
+ config backups used a fixed `.bak` suffix, so a second `sibyl init` overwrote
926
+ the first run's backup. Backups now carry a UTC timestamp
927
+ (`<file>.<YYYYMMDDThhmmssZ>.bak`) via a shared `_timestamped_backup` helper, so
928
+ every run keeps its own copy. (The timestamp is defined before use — the
929
+ external report's own patch referenced an undefined variable and raised
930
+ NameError; that bug is not reproduced.)
931
+ - **`setup` MCP smoke-test no longer cross-class dispatches (#19, B005).**
932
+ `CodexWirer.verify_mcp_starts` called `ClaudeCodeWirer.verify_mcp_starts(self)`.
933
+ Extracted a standalone `_verify_mcp_starts(binary)` module helper used by both
934
+ wirers.
935
+ - **`status` store discovery survives a restricted profiles dir (#15 hygiene).**
936
+ `_discover_stores` iterated the Hermes `profiles/` directory without guarding
937
+ `iterdir()`, which raises `PermissionError` on a restricted directory. The sweep
938
+ now skips gracefully instead of crashing `sibyl status`.
939
+
940
+ ## [0.3.17] - 2026-06-25
941
+
942
+ Pre-launch security audit hardening.
943
+
944
+ ### Fixed
945
+ - `read_credentials()` and the `tier_cache.json` parse no longer crash on a
946
+ corrupt/non-JSON file (graceful "Not activated" instead of a traceback).
947
+ - Atomic credentials write uses a unique temp name + `fsync` + `os.replace`
948
+ (no fixed-`.tmp` concurrent-writer race).
949
+ - `status` and `migrate` validate that a `--db` target is a real SQLite file
950
+ instead of silently treating garbage as an empty database.
951
+ - `devices revoke` guards malformed/hostile server data and rejects negative
952
+ indexes. `health` expands `~` and wraps provider errors. Version compare
953
+ normalized (1.2 == 1.2.0, rc tags). `init` persists an allowlisted
954
+ credentials dict. `setup` installs the plugin only after the overwrite
955
+ confirm, surfaces pip output on failure, and respects PEP-668. `migrate`
956
+ backup is fsync'd and re-verified on disk before any debloat.
957
+
958
+ ## [0.3.16] - 2026-06-19
959
+
960
+ ### Fixed
961
+
962
+ - **Bearer token printed to the terminal (red-team F3, 2026-06-17).** `sibyl upgrade`
963
+ and `sibyl dashboard` printed the full session bearer inside the opened URL to
964
+ stdout (terminal scrollback / tmux / CI logs / screen-shares), violating this
965
+ package's own "session_token is never printed in full" rule. They now print only
966
+ the bare base URL; the token still rides the opened browser URL (moving that
967
+ handoff to a one-time, server-issued exchange code is a tracked server-side
968
+ follow-up).
969
+
970
+ ## [0.3.15] - 2026-06-16
971
+
972
+ ### Added
973
+
974
+ - **Read-only `sibyl memory list | search | recall`** (beta reports,
975
+ 2026-06). Inspect what is actually stored without writing through an
976
+ agent: `list [category]`, full-text `search <query>` across all tiers, and
977
+ `recall <category> <name>`. Opens the resolved DB read-only via the SDK (never
978
+ writes) and respects `--db`, so you can inspect any split-brain store that
979
+ `sibyl status` surfaces. (big-patch PKG-4) Regression test:
980
+ `tests/test_memory_cmd_2026_06_16.py` (6 cases).
981
+
982
+ ## [0.3.14] — 2026-06-11
983
+
984
+ ### Added
985
+
986
+ - **`sibyl status` now lists every memory store on the machine + warns on
987
+ split-brain divergence** (beta report, 2026-06-11). A new read-only
988
+ `_discover_stores()` enumerates the SDK/CLI/MCP default
989
+ (`~/.sibyl-memory/memory.db`), the Hermes adapter
990
+ (`$HERMES_HOME/sibyl/memory.db`), per-profile DBs
991
+ (`$HERMES_HOME/sibyl/profiles/<p>/memory.db`), and any `SIBYL_MEMORY_DB`
992
+ override, listing each with path + size. When more than one store holds data,
993
+ a warning explains that memory is not shared across entry points and how to
994
+ point them at one path. Discovery creates and moves nothing — path
995
+ unification is a separate, migration-gated change. Regression test:
996
+ `tests/test_status_stores_2026_06_11.py` (4 cases). (big-patch PKG-2/PKG-3)
997
+
998
+ ## [0.3.13] — 2026-06-11
999
+
1000
+ ### Fixed
1001
+
1002
+ - **Corrupt `~/.claude/settings.json` was silently replaced with a sibyl-only
1003
+ file (data loss).** `_write_settings_with_sibyl` swallowed JSON parse errors
1004
+ (`except Exception: cfg = {}`) and the subsequent atomic replace destroyed the
1005
+ user's other `mcpServers`, `permissions`, `hooks`, and `env`. Setup now fails
1006
+ fast with a clear error (file untouched, backup path reported) on invalid JSON
1007
+ or a non-object top level; an empty file is still treated as legitimately
1008
+ empty. The same fail-fast applies to a valid-but-non-mapping Hermes YAML
1009
+ config. `current_state()` now surfaces `settings_parse_error` instead of
1010
+ swallowing it. (bugflow)
1011
+ - **`sibyl status` crashed with a TypeError whenever a tier cache existed.**
1012
+ `cmd_status` sliced `checked_at` with `[:19]`, but `_capcheck` writes
1013
+ `checked_at` as epoch seconds (float), so every `sibyl status` run with a
1014
+ populated `~/.sibyl-memory/tier_cache.json` raised
1015
+ `TypeError: 'float' object is not subscriptable`. The value is now rendered
1016
+ via `time.strftime` when numeric and passed through (truncated to 19 chars)
1017
+ when it is already an ISO string; missing or null renders as `?`. Validated
1018
+ against float, ISO-string, missing, null, and zero inputs. (bugflow)
1019
+
1020
+ ## [0.3.12] — 2026-06-05
1021
+
1022
+ ### Fixed
1023
+
1024
+ - **`sibyl migrate --force` (onboarding dead-end).** When a detected harness
1025
+ already had a non-sibyl memory provider, the wirer refused with
1026
+ "Use --force to overwrite." but `run_guided_setup` called `wire()` with no
1027
+ `force`, and `sibyl migrate` had no `--force` flag to pass, leaving the user
1028
+ with no way forward. Added `--force` to `sibyl migrate`, threaded through
1029
+ `cmd_migrate` → `run_guided_setup(force=)` → `wire(force=force)`, so migration
1030
+ can overwrite an existing provider when the user explicitly opts in.
1031
+ Regression coverage: `tests/test_migrate_force_2026_06_05.py`. (bugflow)
1032
+
1033
+ ## [0.3.11] — 2026-06-01
1034
+
1035
+ ### Fixed
1036
+
1037
+ - **`sibyl init` left a pre-existing `~/.sibyl-memory` world-readable.**
1038
+ `mkdir(mode=0o700)` is a no-op when the directory already exists, so a dir
1039
+ created earlier at 0755 kept loose permissions on the credentials directory.
1040
+ `os.chmod(~/.sibyl-memory, 0o700)` is now applied explicitly after mkdir.
1041
+ (security; beta report dor_alpha)
1042
+ - **Claude Code MCP registration could report false success.**
1043
+ `claude mcp add --scope user` returning exit 0 did not guarantee the server
1044
+ showed up in `claude mcp list`. The wirer now verifies via `claude mcp get`
1045
+ after adding; if the server is absent it returns an error with concrete
1046
+ remediation instead of a false "wired". (beta report)
1047
+
1048
+ ## [0.3.10] — 2026-06-01
1049
+
1050
+ ### Fixed
1051
+
1052
+ - **`sibyl setup hermes` raised a TypeError on every first-run wiring.**
1053
+ `HermesWirer._install_plugin()` called `install()` with only `hermes_home`
1054
+ (as a `str`), but `sibyl_memory_hermes.install_plugin.install()` requires
1055
+ `(hermes_home: Path, force: bool, dry_run: bool)` with no defaults, so it
1056
+ raised `TypeError` before the plugin could install. Now calls
1057
+ `install(hermes_home=Path(self.hermes_home), force=False, dry_run=False)`.
1058
+
1059
+ ## [0.3.9] — 2026-05-31
1060
+
1061
+ Guided migration plus first-class Codex support and the real fix for Claude
1062
+ Code MCP discovery.
1063
+
1064
+ ### Added
1065
+
1066
+ - **`sibyl migrate` — guided onboarding.** One command takes a user from
1067
+ "memory scattered across CLAUDE.md / AGENTS.md / config files" to "memory in
1068
+ Sibyl." It (1) backs up every existing memory/agent file FIRST to a
1069
+ timestamped, byte-verified folder with a collision-free layout (a home file
1070
+ and a same-named project file never clobber each other), (2) auto-wires Sibyl
1071
+ into every detected harness, (3) hands the semantic extraction to the user's
1072
+ OWN agent — the agent reads only from the backup and writes via the
1073
+ `sibyl-memory` MCP tool, so Sibyl Labs never sees the user's files or memory
1074
+ (local/private by construction), (4) verifies what actually landed in the DB,
1075
+ and (5) optionally trims the originals — only on an explicit confirm and only
1076
+ because a verified backup exists. New `migrate.py` module + orchestrator.
1077
+ - **Codex is now a first-class wiring target.** New `CodexWirer` edits
1078
+ `~/.codex/config.toml` (`[mcp_servers.sibyl_memory]`) atomically with a `.bak`
1079
+ backup and an idempotent guard, writing the RESOLVED absolute binary path
1080
+ (matching codex's own `codex mcp add` behavior). `sibyl setup codex` now
1081
+ works — previously the parser offered `codex` but `ALL_WIRERS` lacked it, so
1082
+ it errored.
1083
+
1084
+ ### Fixed
1085
+
1086
+ - **Claude Code MCP registration.** Wiring now goes through
1087
+ `claude mcp add --scope user` — where Claude Code actually discovers MCP
1088
+ servers — instead of writing `~/.claude/settings.json`, which Claude Code does
1089
+ NOT read for MCP discovery. This was the root cause of "configured but never
1090
+ connects." Detection now uses `claude mcp get`; the settings.json path remains
1091
+ a fallback only for environments without the `claude` CLI.
1092
+ - **Absolute-path registration (both Claude and Codex).** User-scope / config
1093
+ servers are launched from the harness's own environment, not the interactive
1094
+ shell, so a bare `sibyl-memory-mcp` could fail to resolve (Claude showed
1095
+ "✗ Failed to connect"; Codex would not spawn). Both wirers now register the
1096
+ resolved absolute path.
1097
+
1098
+ ### Tested
1099
+
1100
+ - 82 tests including adversarial inputs and a 60-iteration fuzz of the migration
1101
+ flow. Live MCP connection verified end-to-end against Claude Code
1102
+ (`--scope user` → ✓ Connected) and Codex (initialize handshake + ListTools),
1103
+ and a real headless agent extraction wrote structured entities into an
1104
+ isolated DB.
1105
+
1106
+ ## [0.3.8] — 2026-05-24
1107
+
1108
+ Fix: `sibyl setup claude-code` wired the MCP config but never ensured the
1109
+ `sibyl-memory-mcp` binary existed, causing ENOENT on every Claude Code
1110
+ reconnect. Same defect in the Codex wirer path.
1111
+
1112
+ ### Fixed
1113
+
1114
+ - `ClaudeCodeWirer.wire()` now calls `shutil.which("sibyl-memory-mcp")`
1115
+ before writing config. If the binary is absent, it auto-installs
1116
+ `sibyl-memory-mcp` via `pip install` (mirroring `HermesWirer._install_plugin`).
1117
+ If auto-install fails, the outcome downgrades to `error` with the exact
1118
+ `pip install sibyl-memory-mcp` command instead of false success.
1119
+ - `current_state()` now includes `mcp_binary_found`. The `wired_with_sibyl`
1120
+ flag is only True when both the config block matches AND the binary is on
1121
+ PATH. Previously, re-running `sibyl setup` reported "already wired" even
1122
+ when the binary was missing, hiding the problem on every retry.
1123
+ - Config-present-but-binary-missing is now a distinct path in `wire()`:
1124
+ it installs the binary without re-writing the config block, then reports
1125
+ `wired` (not `already`).
1126
+
1127
+ ### Added
1128
+
1129
+ - **Post-wire MCP verification.** After wiring (or confirming "already"),
1130
+ `cmd_setup` spawns `sibyl-memory-mcp` briefly and confirms it doesn't
1131
+ crash on startup (catches ImportError, missing deps, bad credentials).
1132
+ Reports `✓ MCP server verified` on success or `✗ Server crashed on
1133
+ startup (exit N): <stderr>` on failure, with a non-zero exit code so
1134
+ CI and scripts can detect the problem.
1135
+ - Claude Code reconnect instructions print after verification: tells
1136
+ the user to type `/mcp` and reconnect `sibyl-memory`, or restart.
1137
+ - `[mcp]` optional extra in pyproject.toml: `pip install "sibyl-memory-cli[mcp]"`
1138
+ now pulls in `sibyl-memory-mcp>=0.1.2` transitively.
1139
+
1140
+ ### Root cause
1141
+
1142
+ `sibyl-memory-mcp` ships in a separate opt-in PyPI package. `sibyl setup`
1143
+ wrote a config entry pointing at the binary without checking it existed.
1144
+ The Hermes wirer had self-heal (`_install_plugin()`); the Claude Code and
1145
+ Codex wirers did not.
1146
+
1147
+ ## [0.3.5] — 2026-05-21
1148
+
1149
+ Permanent fix for the silent-success activation foot-gun. 0.3.4 raised the
1150
+ CLI poll to 30min and the server pairing TTL to 30min so the two windows
1151
+ matched. Operator pushed back: matching constants is a temporary fix that
1152
+ re-opens the moment either side moves. The structural fix is one source of
1153
+ truth.
1154
+
1155
+ ### Changed
1156
+
1157
+ - The CLI no longer carries its own activation deadline. The `/session-init`
1158
+ response already includes `pairing_ttl_seconds` (it always did — the CLI
1159
+ was just throwing it away). The CLI now captures that value and uses it
1160
+ as the poll deadline.
1161
+ - `INIT_TIMEOUT_SEC` removed. Replaced by `INIT_TIMEOUT_FALLBACK_SEC`,
1162
+ used only when `/session-init` fails entirely or the response is missing
1163
+ the field. Drift between CLI and server is now impossible by
1164
+ construction.
1165
+
1166
+ ### Why this is permanent
1167
+
1168
+ If the server-side TTL ever changes again, every CLI install in the wild
1169
+ adopts the new value on the next `sibyl init` automatically. No CLI
1170
+ re-publish required. No `bumped constant on one side` failure mode. The
1171
+ server is the single source of truth; the CLI defers.
1172
+
1173
+ ## [0.3.4] — 2026-05-21
1174
+
1175
+ Silent-success activation foot-gun. Multi-user reports of "email auth doesn't
1176
+ work, no error message." Root cause: CLI `INIT_TIMEOUT_SEC` was 10min while
1177
+ the server-side `PAIRING_TTL_SECONDS` was 15min. Users who took 10-15min to
1178
+ find the pairing code in their inbox would hit the gap: server accepted the
1179
+ bind, browser showed the success modal, but the local CLI had already exited
1180
+ and `credentials.json` was never written. No error surfaced anywhere — the
1181
+ plugin just failed to load on the next run.
1182
+
1183
+ ### Changed
1184
+
1185
+ - `INIT_TIMEOUT_SEC` raised from `10 * 60` to `30 * 60` (cli.py:61). Matches
1186
+ the server's new 30min pairing-code TTL — the two windows now never
1187
+ disagree.
1188
+ - `UPGRADE_TIMEOUT_SEC` raised to `30 * 60` for the same alignment reason on
1189
+ the upgrade flow.
1190
+ - Activation-timeout terminal message now explicitly calls out the
1191
+ silent-success failure mode and tells the user to run
1192
+ `sibyl init --force`. Earlier message just said "Re-run sibyl init."
1193
+
1194
+ ### Companion changes (same session)
1195
+
1196
+ - `api-sibyllabs/api/plugin/session-init.js`: `PAIRING_TTL_SECONDS` 15min →
1197
+ 30min.
1198
+ - `api-sibyllabs/api/plugin/email-bind.js`: error message for expired code
1199
+ updated from "15 min limit" to "30 min limit" + `sibyl init --force`.
1200
+ - `sibyllabs/plugin/activate.html`: success modal gains a callout that
1201
+ prompts the user to run `sibyl init --force` if their terminal already
1202
+ showed the timeout message before they bound.
1203
+
1204
+ ## [0.3.3] — 2026-05-20
1205
+
1206
+ Auth subdomain migration. Operator directive: "make sure the temp links are
1207
+ being generated at install.sibyllabs.com/plugin/auth or something like this,
1208
+ and not sibyllabs.org/install." Surfaced as a trust + phishing-resistance ask
1209
+ for the URL that appears in the user's terminal at activation time.
1210
+
1211
+ ### Changed
1212
+
1213
+ - `ACTIVATE_BASE` default changed from `https://sibyllabs.org/plugin/activate`
1214
+ to `https://auth.sibyllabs.org`. Activation URL shape moved from
1215
+ query-string (`?session=<uuid>`) to bare path (`/<uuid>`). The terminal
1216
+ output now reads `Opening https://auth.sibyllabs.org/<short-uuid>` —
1217
+ shorter, line-wraps less on narrow terminals, easier to verify visually.
1218
+ - The Vercel rewrite on `auth.sibyllabs.org` serves the same `/plugin/activate`
1219
+ page but preserves the user-visible URL, so the wallet popup's "X wants you
1220
+ to sign in" header matches the URL bar. Phishing-conscious wallets (Rabby,
1221
+ MetaMask in security mode) skip the domain-mismatch warning.
1222
+ - Companion api-sibyllabs change (same session): `bind.js` SIWE
1223
+ `expectedDomains` allowlist now includes `auth.sibyllabs.org` alongside
1224
+ `sibyllabs.org` and `sibylcap.com`.
1225
+
1226
+ ### Backward compatibility
1227
+
1228
+ The legacy `https://sibyllabs.org/plugin/activate?session=<uuid>` URL still
1229
+ resolves and works identically. Anyone on cli 0.3.2 or earlier keeps a
1230
+ functioning activation flow until they upgrade. The new URL works on cli
1231
+ 0.3.3+ automatically with no env-var changes needed.
1232
+
1233
+ Override via `SIBYL_ACTIVATE_BASE` env var still works for staging /
1234
+ self-hosted setups. The CLI auto-detects path-vs-query URL shape from the
1235
+ base hostname (sibyllabs.org subdomain → path; everything else → query).
1236
+
1237
+ ## [0.3.2] — 2026-05-20
1238
+
1239
+ Branding pass on the banner. Operator directive: "beneath the large
1240
+ SIBYL title it needs to say underneath the memory you can hold in
1241
+ your hand tagline, 'a Sibyl Labs LLC Product. Agentic Infrastructure
1242
+ and Memory Products' or something similar."
1243
+
1244
+ ### Changed
1245
+
1246
+ - `_banner.py` now emits a third line under the wordmark + tagline:
1247
+ `a Sibyl Labs LLC Product. Agentic Infrastructure and Memory Products`.
1248
+ Rendered in the same deepest-gold (`_GRADIENT[-1]` = `(106, 79, 31)`)
1249
+ as the tagline but with ANSI dim (`\033[2m`) applied so the visual
1250
+ hierarchy reads SIBYL > tagline > attribution at a glance. Plain-text
1251
+ fallback also includes the line for non-color terminals.
1252
+
1253
+ Preview captures at https://sibylcap.com/hud-2026-05-20 (scene 09
1254
+ isolates the banner; scenes 01 + 05 show it inline with the rest of
1255
+ the activation and install ceremonies).
1256
+
1257
+ ## [0.3.1] — 2026-05-20
1258
+
1259
+ Operator-directed tuning: "typical app patterns — heavy menus on
1260
+ install window and initial setup, light on dashboards etc." v0.3.0
1261
+ applied the full section_header treatment uniformly across every
1262
+ subcommand. v0.3.1 lightens the daily-use dashboards and keeps the
1263
+ ceremony reserved for activation moments.
1264
+
1265
+ ### Changed
1266
+
1267
+ - `sibyl status`, `sibyl whoami`, `sibyl devices`, `sibyl logout`,
1268
+ `sibyl health` — dropped the section_header opener. Same convention
1269
+ as `git status`, `ls -la`, `gh auth status`, `pg_isready`,
1270
+ `redis-cli ping`: utilitarian dashboards present data, not chrome.
1271
+ Eyebrow labels + kv rows + status lines remain.
1272
+
1273
+ ### Unchanged
1274
+
1275
+ - `sibyl init` — keeps the full SIBYL gradient banner + section
1276
+ headers + numbered next-steps. This IS the install moment; it earns
1277
+ the ceremony.
1278
+ - `sibyl upgrade` — keeps section header + KV. Mid-weight: tier-flip
1279
+ moment is install-ish but not first-run.
1280
+ - `_aesthetic.py` library — unchanged. Applied differently across
1281
+ commands per the heavy/light convention.
1282
+
1283
+ ## [0.3.0] — 2026-05-20
1284
+
1285
+ Visual identity pass across every subcommand. The `sibyl init` brand
1286
+ moment (the SIBYL ASCII wordmark with pale-gold → deep-ochre vertical
1287
+ gradient) was the only command with serious typography; every other
1288
+ subcommand was plain text + ANSI 16-color. v0.3.0 brings the lab face
1289
+ to the whole surface.
1290
+
1291
+ ### Added
1292
+
1293
+ - New `_aesthetic.py` module — shared visual library for the entire CLI.
1294
+ Brand palette derived from the rule 46 creme paper face (PAPER, INK,
1295
+ ACCENT, JADE, PULSE, RULE, etc.). 24-bit truecolor → 256-color → plain
1296
+ text degradation cascade. Letter-spaced eyebrows, gradient titles,
1297
+ ASCII rule dividers, key/value rows, status chips with success/warn/
1298
+ error glyphs, multi-stop char-by-char gradient interpolation.
1299
+ - `SIBYL_FORCE_COLOR=1` env override for non-tty rendering (CI logs,
1300
+ doc captures, harness inspection). Honors `NO_COLOR` as the wider
1301
+ precedence override per the standard.
1302
+
1303
+ ### Changed
1304
+
1305
+ - `sibyl init`, `sibyl upgrade`, `sibyl status`, `sibyl whoami`,
1306
+ `sibyl devices`, `sibyl logout`, `sibyl health` all now open with a
1307
+ styled section header (gradient command-name + creme rule lines +
1308
+ dim subtitle), use eyebrow labels for sub-sections (uppercase
1309
+ letter-spaced ochre), and render key/value rows + status lines with
1310
+ the brand palette. Success states (Activated, Upgraded, Logged out)
1311
+ flow with a pulse → jade gradient. Cap warnings and errors use the
1312
+ measured warm-ochre / red palette tokens, not generic ANSI 31/33.
1313
+ - `sibyl init` waiting spinner now reads "watching the network for your
1314
+ bind" in pulse-jade, aligned with the wallet-bind-watcher service
1315
+ language users see in their browser.
1316
+ - `sibyl devices` list rendering: current device marked with `▶` in
1317
+ pulse + the device label flows in gold gradient; other devices show
1318
+ in calm ink with dim metadata. Index chips in pulse for "this device"
1319
+ or muted gray for the rest.
1320
+
1321
+ ### Compatibility
1322
+
1323
+ - Backward compat preserved: existing `dim/bold/green/yellow/red/cyan`
1324
+ helpers stay in `cli.py` (the legacy `print_status` path they served
1325
+ was removed later, in 0.5.0). New `_aesthetic.a.*`
1326
+ helpers layer on top.
1327
+ - All visual choices honor `NO_COLOR`. Plain text fallback is
1328
+ visually clean (no garbage escapes leak).
1329
+ - Terminal capability detection identical to `_banner.py` for
1330
+ consistency (COLORTERM=truecolor, TERM_PROGRAM whitelist, TERM
1331
+ pattern match for kitty/alacritty/256color).
1332
+
1333
+ ## [0.2.0] — 2026-05-19
1334
+
1335
+ Auth-redesign wave 2 — account-surface CLI commands. Adds `sibyl whoami`
1336
+ for a one-line account summary (masked by default, `--full` opt-in) and
1337
+ `sibyl devices` for listing active bearer tokens with per-device revoke.
1338
+
1339
+ ### Added
1340
+
1341
+ - `sibyl whoami` — one-line summary: short account_id, tier, masked email
1342
+ (`a***@e***.tld`), masked wallet (`0xabcd…1234`), this device label.
1343
+ `--full` flag shows unmasked email + wallet for ops scenarios.
1344
+ - `sibyl devices` — list active (non-revoked) bearer tokens for the
1345
+ account in issued_at DESC order. Marks current device with `▶` and
1346
+ shows revoke command for each other device.
1347
+ - `sibyl devices revoke <index>` — POST `/api/plugin/devices` with the
1348
+ bearer_id at that index. Refuses to revoke the calling device.
1349
+
1350
+ ### Server companion (deployed)
1351
+
1352
+ - `GET /api/plugin/devices?account_id=<uuid>` — lists bearer_tokens.
1353
+ - `POST /api/plugin/devices { bearer_id }` — revokes the bearer.
1354
+ - Both auth via `Authorization: Bearer <session_token>`; caller must
1355
+ own the account.
1356
+
1357
+ ## [0.1.4] — 2026-05-18
1358
+
1359
+ Maximum-efficiency onboarding release. New `sibyl setup` command auto-detects
1360
+ agent frameworks on the user's machine and wires SIBYL as the memory provider
1361
+ in one command. Replaces the prior three-step Hermes flow (`pip install
1362
+ sibyl-memory-hermes` + `sibyl-memory-hermes install-plugin` + manual
1363
+ `config.yaml` edit) with `sibyl setup`. Also handles Claude Code MCP wiring.
1364
+
1365
+ ### Added
1366
+
1367
+ - **`sibyl setup`** — new subcommand. Auto-detects Hermes (`$HERMES_HOME` or
1368
+ `~/.hermes/` or `hermes` on PATH) and Claude Code (`~/.claude/settings.json`
1369
+ or `claude` on PATH). Prompts per stack with explicit confirmation:
1370
+ - Fresh add: `Set SIBYL as default memory provider in Hermes? [Y/n]` (default Y)
1371
+ - Overwrite existing: `Hermes currently uses 'mem0' as memory provider. Overwrite with SIBYL? [y/N]` (default N, never destroys user state without explicit y)
1372
+ - Already wired: noop with green status
1373
+ - Multi-framework: `Wire which? [h]ermes, [c]laude, [a]ll, [n]one (default: all)`
1374
+ - **`sibyl setup hermes`** / **`sibyl setup claude-code`** — explicit targeting
1375
+ for power users (skips detection, wires only the named stack).
1376
+ - **Flags**: `--yes` (accept all defaults, still respects destructive-default-N
1377
+ unless `--force` is also passed), `--force` (overwrite existing non-SIBYL
1378
+ configs), `--dry-run` (print intent without writing), `--hermes-home`,
1379
+ `--claude-settings` (override autodetect).
1380
+ - **Atomic writes + backups**: every config edit creates a `.bak` sibling
1381
+ (`config.yaml.bak`, `settings.json.bak`) before atomic rename via tmpfile.
1382
+ Defensive against partial writes + user mistake recovery.
1383
+ - **`HermesWirer`, `ClaudeCodeWirer`** classes in new `sibyl_memory_cli.setup`
1384
+ module. Composable wirer protocol (`is_present()` / `current_state()` /
1385
+ `wire()` / `WireOutcome`) ready for v0.1.5 addition of Codex / Cursor /
1386
+ Continue wirers.
1387
+ - **33 new tests** in `tests/test_setup.py` covering: detection logic, prompt
1388
+ helpers, Hermes fresh / existing-sibyl / existing-other / force-overwrite /
1389
+ dry-run / config-preservation, Claude Code fresh / existing-other-mcps /
1390
+ existing-sibyl / mismatched-sibyl / force / dry-run.
1391
+
1392
+ ### Changed
1393
+
1394
+ - **Dependencies**: added `pyyaml>=6.0` for Hermes `config.yaml` editing.
1395
+ Already a transitive dep for any Hermes user; small (~250 KB) for
1396
+ Claude-Code-only users.
1397
+
1398
+ ### Notes
1399
+
1400
+ - Replaces the prior canonical three-step Hermes flow. Docs `install.html`
1401
+ Step 4 collapses from three commands to two: `pip install sibyl-memory-cli`
1402
+ + `sibyl setup`. The old `sibyl-memory-hermes install-plugin` path stays
1403
+ documented as a manual fallback for advanced users who want fine-grained
1404
+ control over each step.
1405
+ - Codex / Cursor / Continue MCP wirers are scoped for v0.1.5. The wirer
1406
+ protocol in `setup.py` is ready to take them as drop-in classes.
1407
+ - The shell installer (`curl ... | sh`) remains on the roadmap; combined with
1408
+ `sibyl setup` it collapses the full onboarding to a single curl line.
1409
+
1410
+
1411
+
1412
+ ## [0.1.3] — 2026-05-18
1413
+
1414
+ External-tester remediation release. Family-wide alignment with the
1415
+ v0.4.0 client + v0.3.2 hermes (external-test fixes: exception export
1416
+ path, db file perms, identifier validation, FTS5 error surfacing). No CLI
1417
+ code changes in this release.
1418
+
1419
+ ### Changed
1420
+
1421
+ - `sibyl-memory-client` pin: `>=0.3.3` → `>=0.4.0`.
1422
+ - `sibyl-memory-hermes` pin: `>=0.3.1` → `>=0.3.2`.
1423
+
1424
+ ### Notes
1425
+
1426
+ - `sibyl init / upgrade / status / health` surface is unchanged from
1427
+ v0.1.2. The external tester's fixes flow through transparently via the dependency
1428
+ bump.
1429
+
1430
+ ---
1431
+
1432
+ ## [0.1.2] — 2026-05-18
1433
+
1434
+ Audit-remediation release. v0.3.0 plugin-family pre-ship audit (2026-05-18T05:05Z)
1435
+ surfaced 10 critical findings; this release lands the CLI-side fixes.
1436
+ Companion releases: `sibyl-memory-client` v0.3.3 (engine + schema v3 +
1437
+ cross-tier search), `sibyl-memory-hermes` v0.3.1, `sibyl-memory-mcp` v0.1.1.
1438
+
1439
+ ### Fixed
1440
+
1441
+ - **C3** — `__version__` no longer hardcoded. Now sourced from
1442
+ `importlib.metadata.version("sibyl-memory-cli")` with `+source` fallback.
1443
+ Same pattern as sibyl-memory-hermes v0.3.0+. Wheel and `__init__.py`
1444
+ can't drift.
1445
+ - **C3** — HTTP User-Agent header now built from the runtime
1446
+ `_client_version()` helper instead of the hardcoded `"sibyl-memory-cli/0.1.0"`.
1447
+ Server telemetry will see real versions, not the stale literal.
1448
+ - **C3** — `/api/plugin/session-init` payload's `client_version` field
1449
+ similarly switched from `__import__("sibyl_memory_cli").__version__` to
1450
+ the helper. Telemetry will accurately reflect 0.1.2+.
1451
+ - **C4** — post-activation message rewritten. Removed the fictional
1452
+ `from hermes_agent import Agent; agent = Agent(memory=SibylMemoryProvider())`
1453
+ quickstart (the API never existed in any Hermes release). Replaced with:
1454
+ the real Hermes install flow (`sibyl-memory-hermes install-plugin` +
1455
+ config.yaml edit), the MCP install hint for Claude Code / Codex / Cursor /
1456
+ Continue users, and the direct-SDK path for any Python orchestration.
1457
+
1458
+ ### Security
1459
+
1460
+ - **SEC-2** — `write_credentials_atomic` now creates files at mode 0o600
1461
+ set by the kernel at file-creation time via `os.open(O_WRONLY|O_CREAT|
1462
+ O_EXCL|O_NOFOLLOW, 0o600)`. Previously used `write_text()` then
1463
+ `os.chmod(0o600)`, leaving a world-readable window between syscalls every
1464
+ credential save. No race.
1465
+ - **SEC-1** (CLI-side mitigation) — the URL parameter handed to the
1466
+ browser is now treated as an opaque pairing-session identifier, not as
1467
+ the long-lived bearer. After activation completes, the CLI prefers a
1468
+ server-issued `bearer_token` field from `/check` (post-fix server flow);
1469
+ if absent, falls back to the legacy session-echo flow. Full fix requires
1470
+ the api-sibyllabs server-side change to issue a separate bearer; this
1471
+ release prepares the CLI to consume it when the server-side lands.
1472
+ Internal variable renamed `session_token` → `session_id` in `cmd_init`
1473
+ to reflect the corrected meaning.
1474
+ - **SEC-11** — `read_credentials` refuses to follow symlinks.
1475
+
1476
+ ### Dependencies
1477
+
1478
+ - `sibyl-memory-client>=0.3.3` (was `>=0.3.0`)
1479
+ - `sibyl-memory-hermes>=0.3.1` (was `>=0.2.0`) — picks up the fictional-API
1480
+ removal in the hermes package; earlier versions are structurally broken.
1481
+
1482
+ ## [0.1.1] — 2026-05-17
1483
+
1484
+ ### Added
1485
+
1486
+ - **SIBYL wordmark banner** at the top of `sibyl init`. ANSI Shadow boxchars,
1487
+ 24-bit truecolor vertical gradient flowing cream/white at the top through
1488
+ warm gold to deep ochre at the bottom — aligned with the lab visual identity
1489
+ per the operator's brand-discipline rule (creme palette, `--accent #8a6a2a`).
1490
+ Plus a tagline: "memory you can hold in your hand".
1491
+
1492
+ ### Implementation notes
1493
+
1494
+ - New module `sibyl_memory_cli._banner` with `render_banner()` and
1495
+ `print_banner()` helpers. Truecolor support is detected via `COLORTERM`,
1496
+ `TERM_PROGRAM`, and `TERM` — modern terminals (iTerm2, Alacritty, Kitty,
1497
+ wezterm, Ghostty, Windows Terminal, VS Code, Tabby) light up automatically.
1498
+ - Gracefully degrades to plain text (still readable, no escape junk) when
1499
+ `NO_COLOR` is set, when stdout is not a TTY, or when `TERM=dumb`.
1500
+ - Wired into `cmd_init` only — `status` / `health` / `upgrade` stay banner-free
1501
+ so they don't add noise to scripted invocations.
1502
+ - Banner palette is encoded as 6 RGB tuples (one per row) in the module
1503
+ rather than computed at runtime — easier to tune and audit.
1504
+
1505
+ ## [0.1.0] — 2026-05-16
1506
+
1507
+ ### Changed (same-day revision before publish): terminal pairing code
1508
+
1509
+ `sibyl init` now generates a 6-digit pairing code locally (via
1510
+ `secrets.randbelow`), prints it in the terminal, and POSTs only its
1511
+ sha256 hash to `/api/plugin/session-init` BEFORE opening the browser.
1512
+ The code itself never leaves the user's machine until they type it
1513
+ into the browser's email panel. Replaces the earlier Resend-backed
1514
+ email magic-code flow, removing the external dependency entirely.
1515
+
1516
+ The wallet (SIWE) path is unchanged — the pairing code only matters
1517
+ for the email panel.
1518
+
1519
+
1520
+
1521
+ Initial release. Operator directive 2026-05-16: build the user-facing
1522
+ CLI + upgrade page so the SDK + payment-auth machinery has a front door.
1523
+
1524
+ ### Added
1525
+
1526
+ - **`sibyl init`** — browser activation. Generates a session UUID,
1527
+ opens `sibyllabs.org/plugin/activate?session=...` in the user's
1528
+ browser, polls `api.sibyllabs.org/api/plugin/check` every 3s with a
1529
+ 10-min timeout. On bind, writes `~/.sibyl-memory/credentials.json`
1530
+ atomically at mode 0600.
1531
+ - **`sibyl upgrade`** — opens `sibyllabs.org/plugin/upgrade?session=...`
1532
+ with the existing session token. Polls `/api/plugin/access` every 3s
1533
+ with a 15-min timeout until `tier` changes from the local value.
1534
+ On change: rewrites credentials.json, clears `tier_cache.json` so
1535
+ the next write picks up the new entitlement immediately.
1536
+ - **`sibyl status`** — shows local credentials, DB size, tier cache
1537
+ state, plus the server's view of tier (subscription / staker /
1538
+ free). Flags local↔server tier drift.
1539
+ - **`sibyl health`** — wraps `SibylMemoryProvider.health()`. Prints
1540
+ the JSON diagnostic dict.
1541
+
1542
+ ### Design
1543
+
1544
+ - Pure stdlib HTTP via `urllib`. No `requests`, no `httpx`. The wheel
1545
+ installs in seconds.
1546
+ - `session_token` printed only as short slice (`first8…last4`). Never
1547
+ full-length to stdout.
1548
+ - Polling has explicit timeouts. No infinite loops. Ctrl-C exits 130.
1549
+ - All endpoint URLs configurable via env (`SIBYL_API_BASE`,
1550
+ `SIBYL_ACTIVATE_BASE`, `SIBYL_UPGRADE_BASE`) for staging tests.
1551
+
1552
+ ### Depends on
1553
+
1554
+ - `sibyl-memory-client>=0.3.0` (cap gate)
1555
+ - `sibyl-memory-hermes>=0.2.0` (provider + credentials loader)
1556
+
1557
+ ### Entry point
1558
+
1559
+ `pip install sibyl-memory-cli` installs the `sibyl` binary via the
1560
+ `[project.scripts]` block in pyproject.
sibyl-memory-cli/LICENSE ADDED
@@ -0,0 +1,21 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sibyl Labs LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
sibyl-memory-cli/README.md ADDED
@@ -0,0 +1,313 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # sibyl-memory-cli
2
+
3
+ Command-line interface for the **Sibyl Memory Plugin**.
4
+
5
+ ```bash
6
+ pip install sibyl-memory-cli
7
+ ```
8
+
9
+ Sibyl Memory runs on Linux, macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is not supported.
10
+
11
+ This pulls in `sibyl-memory-client` (the local SDK) and `sibyl-memory-hermes` (the Hermes provider) automatically.
12
+
13
+ **Upgrading.** The packages ship as one release train (client 0.10.0, mcp 0.4.2, hermes 0.6.0, cli 0.7.0), and each one requires the client of its own release. Upgrade them together, never one alone:
14
+
15
+ ```bash
16
+ sibyl update --apply
17
+ # or, without the CLI:
18
+ pip install -U sibyl-memory-client sibyl-memory-mcp sibyl-memory-hermes sibyl-memory-cli
19
+ ```
20
+
21
+ ## Commands
22
+
23
+ ```
24
+ sibyl --version Print the installed versions: cli, client, mcp, hermes, langgraph.
25
+ sibyl init Open the browser activation page. Writes ~/.sibyl-memory/credentials.json.
26
+ Afterwards it offers to add or confirm your email (terminal only).
27
+ sibyl init --no-email Activate without the email prompt.
28
+ sibyl init --replace Re-activate this computer in place of its earlier sign-in (re-activation
29
+ never uses a second computer slot). At the account's computer limit
30
+ (Free: one computer) init lists the computers signed in and offers to
31
+ sign one out on the account page.
32
+ sibyl refresh Check your account now (an upgrade, a staking unlock or a plan change
33
+ lands at once), refresh the procedures, shims and hooks, and say what
34
+ changed. Exits 0 with no account (it says what to do), 2 when offline.
35
+ sibyl autosave [on|off|every N]
36
+ Pro automatic save: every N minutes of active work (30 to 240, default
37
+ 60). On the free plan the setting is kept for the day you upgrade.
38
+ sibyl email Show your account email: confirmed, not confirmed, or none.
39
+ sibyl email add <address> Send a code to a new address, then confirm it.
40
+ sibyl email verify Send a code to the address you activated with, then confirm it.
41
+ sibyl email confirm <code> Confirm a code from the email (for scripts and non-interactive shells).
42
+ sibyl claim <cs_...> Link a card purchase from sibyllabs.org/pro to this account.
43
+ sibyl migrate Guided onboarding: back up your existing memory/agent files, wire Sibyl
44
+ into every detected harness, populate Sibyl Memory from the backup, and
45
+ optionally slim the instruction files it found (CLAUDE.md, AGENTS.md,
46
+ .cursorrules, ...). Backup-first, never destructive.
47
+ sibyl setup [target] Wire Sibyl as the memory provider for Hermes, Claude Code, Codex, Cursor,
48
+ Grok Bot and/or DeepSeek Harness, and install the save and debloat
49
+ procedures for each. target is one of: hermes | claude-code | codex |
50
+ cursor | grokbot | deepseek (alias dsh) (default: detect all).
51
+ DeepSeek Harness: --dsh-home, --dsh-profile <name>.
52
+ sibyl save Save: --fact "<text>" writes one fact; --status shows the last save; bare
53
+ prints how to run the save procedure in your agent. --capsule on Pro.
54
+ sibyl debloat Measure the instruction files your agent loads every start (--fyi, --json);
55
+ plan | apply [<file>] | auto <file> | manual <file> | undo [<file>].
56
+ sibyl skills install | status | reset <SAVE.md|DEBLOAT.md> | uninstall (run it before pip uninstall).
57
+ sibyl reminders on | off | quiet (save and debloat reminders; quiet silences Pro reports).
58
+ sibyl status Show local credentials, DB size, this computer's access, and the server's
59
+ view of your tier.
60
+ sibyl whoami One-line account summary (masked by default).
61
+ sibyl devices List the devices (active tokens) bound to your account, with the
62
+ account's computer limit when the api sends it (Free 1, Pro up to 2).
63
+ sibyl devices revoke N Revoke a device by index (run `sibyl devices` to see the indexes).
64
+ sibyl dashboard Open the account page at account.sibyllabs.org (no token in the URL; you
65
+ sign in there). Shows `sibyl status` while the page is not open yet.
66
+ sibyl upgrade Open the tier/billing flow: the account billing page when the server offers
67
+ it, otherwise the stake / USDC page through a one-time link.
68
+ sibyl update Check PyPI for newer releases of the installed Sibyl packages: cli, client,
69
+ hermes, the MCP server, and langgraph when installed.
70
+ sibyl update --apply Update the installed Sibyl packages in place (pip install -U), the MCP server
71
+ included; never installs one you do not have. This is the
72
+ canonical way to update the plugin, distinct from `sibyl upgrade` (which is
73
+ the tier/billing flow, not a package update).
74
+ sibyl health Run the SibylMemoryProvider self-check (schema version, DB path, tenant,
75
+ entitlement state, pinned key ids).
76
+ sibyl logout Sign this computer out: revoke it on the server, remove credentials.json and
77
+ entitlement.json (your memory.db is left untouched).
78
+ sibyl memory list [category] List stored entities, optionally filtered by category (--limit N).
79
+ `sibyl memory` never needs an account: your local data is always yours to read.
80
+ sibyl memory search <query> Full-text search across entities, state, reference, and journal (--limit N).
81
+ sibyl memory recall <cat> <name>
82
+ Recall a single entity by category + name.
83
+ sibyl memory adopt [--yes] Move memory written on this computer before sign-in into your account
84
+ (local, one transaction, nothing deleted; asks first if the store has
85
+ held another account). `sibyl init` does this on the first sign-in.
86
+ ```
87
+
88
+ ## Migrate (guided onboarding)
89
+
90
+ ```bash
91
+ $ sibyl migrate
92
+ ```
93
+
94
+ `sibyl migrate` moves your accumulated agent memory into Sibyl without risking
95
+ your existing files:
96
+
97
+ 1. **Back up first.** Every memory/agent file it finds (`CLAUDE.md`,
98
+ `AGENTS.md`, `.codex/config.toml`, `.hermes/*`, and similar) is copied to a
99
+ timestamped backup folder and byte-verified before anything else happens.
100
+ 2. **Wire Sibyl** into every detected harness — Claude Code (via
101
+ `claude mcp add --scope user`), Codex (via `~/.codex/config.toml`), Hermes.
102
+ 3. **Extract** — it prints a prompt you run in your own agent. The agent reads
103
+ only from the backup and writes structured memory through the `sibyl-memory`
104
+ tool. The extraction runs locally on your machine; Sibyl Labs never sees your
105
+ files or memory.
106
+ 4. **Verify** the new entries that landed in your local DB.
107
+ 5. **Optionally trim** the instruction files it found (`CLAUDE.md`, `AGENTS.md`,
108
+ `.cursorrules`, ...), one question per file, only if you confirm and only because
109
+ a verified backup of that file exists. Configuration files are never trimmed. Your
110
+ full pre-migration files are always preserved.
111
+
112
+ Flags: `--backup-dir PATH` (default: home), `--no-debloat` (skip the trim
113
+ step), `--yes` (skip the initial confirm; the trim step still asks separately).
114
+
115
+ > No warranty. Keep your backup until you've confirmed everything migrated.
116
+ > Sibyl Labs is not responsible for data loss.
117
+
118
+ ## Activation
119
+
120
+ ```bash
121
+ $ sibyl init
122
+
123
+ ─ activation ───────────────────────────────────────────────
124
+ two paths · pick whichever fits your device
125
+
126
+ Session a1b2c3d4…e5f6
127
+ Code 437 480 (use this in the email panel)
128
+ Opening https://auth.sibyllabs.org/a1b2c3d4-…
129
+
130
+ desktop wallet · or email + code
131
+ this terminal will pick up automatically when you bind.
132
+
133
+ ⠙ watching the network for your bind … 9:59 left
134
+ ```
135
+
136
+ 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).
137
+
138
+ 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.
139
+
140
+ ## Email
141
+
142
+ Every account needs a confirmed email for receipts, security notices, purchases and recovery.
143
+ Your local memory works either way. Wallet activation stays available.
144
+
145
+ ```bash
146
+ $ sibyl email add you@example.com
147
+ code sent to y***@e***.com. it expires in 10 minutes.
148
+ code from the email: 123456
149
+ ✓ Email confirmed. Your account is complete.
150
+ ```
151
+
152
+ `sibyl email verify` confirms the address you activated with. Confirming from the terminal keeps
153
+ this computer signed in and signs out any other computer that was set up with the address before
154
+ you confirmed it.
155
+
156
+ ## Upgrade
157
+
158
+ Free is 5 MB of local memory. Pro removes the cap: $12/month or $108/year (plus applicable tax by card), bought at
159
+ `sibyllabs.org/checkout` or through `sibyl upgrade`. Holding 100,000 $SIBYL staked also gives Pro.
160
+
161
+ ```bash
162
+ $ sibyl upgrade
163
+ ```
164
+
165
+ `sibyl upgrade` shows your account and current tier, then opens the purchase page in your
166
+ browser: the account billing page (`https://account.sibyllabs.org/billing`; sign in there and buy
167
+ Pro) when the server offers it, otherwise a one-time exchange link. No token ever rides the URL.
168
+ It then waits for the plan change. A card purchase made elsewhere can be linked with
169
+ `sibyl claim <cs_...>`.
170
+
171
+ 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.
172
+
173
+ ## Status
174
+
175
+ ```bash
176
+ $ sibyl status
177
+
178
+ P L U G I N
179
+ Version cli 0.5.0 · client 0.9.0
180
+ L O C A L
181
+ Credentials ~/.sibyl-memory/credentials.json
182
+ Account a1b2c3d4-e5f6-4789-8abc-def012345678
183
+ Tier Free
184
+ Wallet 0xa1b2c3d4e5f60718293a4b5c6d7e8f9012345678
185
+ Email you@example.com
186
+ Issued 2026-05-16 18:12 UTC
187
+ Platform Linux (x86_64)
188
+ DB path ~/.sibyl-memory/memory.db
189
+ DB size 1,247,300 bytes (1.19 MB · 23.8% of free cap)
190
+
191
+ A C C E S S
192
+ Access active · re-checks in 24h
193
+ Tier cache free (checked 2026-05-16 18:12 UTC)
194
+
195
+ S E R V E R
196
+ Tier Free
197
+ Source free
198
+ Cap bytes 5,242,880
199
+ Email not confirmed · run sibyl email verify
200
+ Dashboard https://account.sibyllabs.org
201
+
202
+ L I F E C Y C L E
203
+ save last never · 0 writes since · manual (automatic on Pro)
204
+ context no always-load files found here
205
+ skills not installed · sibyl skills install
206
+ reminders on
207
+ ```
208
+
209
+ `$SIBYL held`, `Threshold` and `Qualified` rows appear under `SERVER` when the server reports staking details.
210
+
211
+ `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.
212
+
213
+ `sibyl status` runs one access check-in when online (the check-in is the status). The `Access` row reads one of:
214
+
215
+ | Row | Meaning | What to do |
216
+ |---|---|---|
217
+ | `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 |
218
+ | `offline · <n> days of grace left · connect once to renew` | not reached the server lately | connect to the internet once |
219
+ | `paused · offline too long · connect to the internet, or run sibyl init` | offline more than 14 days | connect; if it stays paused, `sibyl init` |
220
+ | `setup not finished · connect to the internet once to finish setup` | credentials from before 0.9.0 and no check-in yet | connect once |
221
+ | `signed out · run sibyl init` | signed out, revoked, or the sign-in expired | `sibyl init` |
222
+ | `under review · email sibyl@sibyllabs.org` | the account is under review | email us |
223
+
224
+ 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.
225
+
226
+ If `LOCAL` and `SERVER` tiers diverge, run `sibyl refresh` to pick up the server plan (or `sibyl init --force` to re-activate).
227
+
228
+ ## Environment overrides
229
+
230
+ For internal testing only:
231
+
232
+ ```bash
233
+ SIBYL_API_BASE=https://staging.sibyllabs.org sibyl init
234
+ SIBYL_ACTIVATE_BASE=https://staging.sibyllabs.org/plugin/activate sibyl init
235
+ SIBYL_UPGRADE_BASE=https://staging.sibyllabs.org/plugin/upgrade sibyl upgrade
236
+ SIBYL_ACCOUNT_BASE=https://account.staging.sibyllabs.org sibyl dashboard
237
+ SIBYL_NONINTERACTIVE=1 sibyl init # never prompt (same as a non-TTY shell)
238
+ ```
239
+
240
+ The CLI sends your sign-in only to an https `*.sibyllabs.org` address or a loopback address (for example `http://127.0.0.1:8787`); any other `SIBYL_API_BASE` or `SIBYL_UPGRADE_BASE` gets no session token.
241
+
242
+ ## Security
243
+
244
+ - `credentials.json` and `entitlement.json` are written atomically at mode 0600.
245
+ - The access file is verified offline against a public key pinned in `sibyl-memory-client`; it is never printed.
246
+ - `session_token` is never printed in full: only a short slice.
247
+ - No token rides a browser URL: `sibyl dashboard` opens the account page bare, and `sibyl upgrade`
248
+ uses a one-time exchange link.
249
+ - 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.
250
+ - Wallet operations happen in the browser. The CLI sees only the resulting tier change.
251
+
252
+ ## Save and debloat
253
+
254
+ **Save.** At the end of a session, or after a big block of work, your agent writes what happened
255
+ into Sibyl Memory through the plugin's own tools: the decisions made and why (journal), the
256
+ people, projects and products touched (entities), what to pick up next time and the open
257
+ warnings (session state), the ranked priorities, and it closes what died (archive). A delta
258
+ marker means a second save in the same day captures only what changed. It may offer to turn a
259
+ repeated pattern into a reusable skill; that is offered, never forced. Nothing in a save leaves
260
+ your machine.
261
+
262
+ **Debloat.** Sibyl measures the files your agent loads on every session start (`CLAUDE.md`,
263
+ `AGENTS.md`, `.cursorrules` and the rest of the scan set), deterministically (`chars/4`,
264
+ labeled `MEASURED~`), and when they are heavy, trims the accreted history out of them without
265
+ losing a byte: the history moves out and a one-line pointer stays. On the free plan the history
266
+ moves to a sibling `*-history` file. On Pro it is stored in Sibyl Memory as a reference document,
267
+ so it stays searchable, and the measurement and trim run by themselves under a policy you set
268
+ once.
269
+
270
+ | | Free (activated account) | Pro |
271
+ |---|---|---|
272
+ | 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 |
273
+ | `sibyl save`, `sibyl debloat` (measure, plan, apply, undo) | yes | yes |
274
+ | Reminders (one quiet line; `sibyl reminders off`) | yes | replaced by a one-line report of what ran |
275
+ | Where trimmed history goes | a sibling `*-history` file | Sibyl Memory, plus a byte-verified backup |
276
+ | 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) |
277
+ | 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 |
278
+ | 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 |
279
+ | Skill signals (0.10): Sibyl also notices a tool sequence your agent repeats (in Claude Code the whole workflow, for example `Read -> Edit -> Bash`; in Codex, Cursor and Hermes the memory tools only) and an entity rewritten again and again, and proposes a skill for it the same way. It keeps one small local file, `~/.sibyl-memory/signals.json`: tool and MCP server names in plain text, argument names and entity names only as hashes, never a value, never a prompt or a file path; nothing leaves your computer. `sibyl skills signals` shows its size, `clear` deletes it, `off` stops it. In Claude Code a proposal from the workflow appears at the next session start at the earliest | no (nothing is recorded) | yes |
280
+
281
+ The procedures are vendored, with attribution, from the public MIT repos
282
+ [sibyl-save](https://github.com/Sibyl-Labs/sibyl-save) and
283
+ [debloat](https://github.com/Sibyl-Labs/debloat); both stay standalone and account-free.
284
+
285
+ Uninstalling: run `sibyl skills uninstall` first. It removes the Claude Code hooks in
286
+ `~/.claude/settings.json`, the skill shims and the Codex block (files you edited are kept); then
287
+ `pip uninstall` the packages. The hooks call this package's `sibyl` command: if the package goes
288
+ first they exit quietly, but they stay in your settings until you reinstall and run
289
+ `sibyl skills uninstall`, or delete the five `sibyl hook` entries by hand.
290
+
291
+ Privacy: the lifecycle reads your instruction files to measure and trim them locally; no file
292
+ content and no conversation content ever leaves your machine.
293
+
294
+ Forks: a gate-stripped fork can run the lifecycle code locally (MIT allows it). It gains nothing
295
+ hosted, and its trims land in a store the official path cannot recognize as Pro. No file, flag
296
+ or environment variable turns the automation on for a free account.
297
+
298
+ Commands: `sibyl save` (`--fact`, `--status`, `--capsule` on Pro), `sibyl debloat` (`--fyi`,
299
+ `--json`, `plan`, `apply [<file>]`, `auto <file>`, `manual <file>`, `undo [<file>]`),
300
+ `sibyl skills install|status|reset|uninstall`, `sibyl skills proposals [show|accept|reject|mute|unmute]`
301
+ (Pro), `sibyl skills signals [status|clear|off|on]` (Pro; `off` and `clear` on any plan), `sibyl autosave [on|off|every <minutes>]`, `sibyl reminders on|off|quiet`. `sibyl setup`
302
+ installs the procedures and wires them: Claude Code gets the two skills plus five hooks in
303
+ `~/.claude/settings.json` (`sibyl hook <event>`, installed by setup, not for manual use; any
304
+ other hook you have is left alone; each hook exits 0 quietly if the `sibyl` it names is gone),
305
+ Codex gets a marked block in `~/.codex/AGENTS.md` and two skills in `~/.codex/skills/`, Hermes
306
+ gets two skills in `$HERMES_HOME/skills/`. `sibyl debloat auto <file>` authorizes that one file
307
+ at its path. On Pro the Stop hook asks the agent to save once early (after 5 memory writes or a
308
+ compaction), then about every hour of active work (`sibyl autosave`). `sibyl migrate` now slims the instruction files it
309
+ found (`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, ...), one question per file.
310
+
311
+ ## License
312
+
313
+ MIT.
sibyl-memory-cli/pyproject.toml ADDED
@@ -0,0 +1,53 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "sibyl-memory-cli"
7
+ version = "0.7.0"
8
+ description = "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."
9
+ authors = [{ name = "SIBYL, Sibyl Labs LLC", email = "sibyl@sibyllabs.org" }]
10
+ license = { text = "MIT" }
11
+ readme = "README.md"
12
+ requires-python = ">=3.10"
13
+ keywords = ["sibyl", "memory", "cli", "agent", "hermes", "deepseek"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.10",
20
+ "Programming Language :: Python :: 3.11",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Environment :: Console",
23
+ "Topic :: Software Development :: Libraries :: Python Modules",
24
+ "Operating System :: POSIX :: Linux",
25
+ "Operating System :: MacOS",
26
+ ]
27
+ dependencies = [
28
+ "sibyl-memory-client>=0.10.0",
29
+ "sibyl-memory-hermes>=0.6.0",
30
+ "pyyaml>=6.0,<7",
31
+ # The Codex config proof parses TOML; tomllib is stdlib only from 3.11.
32
+ 'tomli>=2; python_version < "3.11"',
33
+ ]
34
+
35
+ [project.optional-dependencies]
36
+ mcp = [
37
+ "sibyl-memory-mcp>=0.4.0",
38
+ ]
39
+ dev = [
40
+ "pytest>=7.0",
41
+ ]
42
+
43
+ [project.scripts]
44
+ sibyl = "sibyl_memory_cli._entry:main"
45
+
46
+ [project.urls]
47
+ Homepage = "https://sibyllabs.org/plugin"
48
+ Documentation = "https://docs.sibyllabs.org/memory/"
49
+ Repository = "https://github.com/Sibyl-Labs/Sibyl-Memory"
50
+
51
+ [tool.setuptools.packages.find]
52
+ where = ["src"]
53
+ include = ["sibyl_memory_cli*"]
sibyl-memory-cli/src/sibyl_memory_cli/__init__.py ADDED
@@ -0,0 +1,40 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """sibyl-memory-cli: command-line interface for the Sibyl Memory Plugin.
2
+
3
+ Entry point: `sibyl` (installed via [project.scripts] in pyproject).
4
+ `sibyl --help` lists every command; a few to start with:
5
+
6
+ sibyl init sign in (email + code, or a wallet) and write
7
+ ~/.sibyl-memory/credentials.json
8
+ sibyl setup wire Claude Code, Codex, Cursor, Hermes and
9
+ DeepSeek Harness
10
+ sibyl status show current tier, DB size, expiry, account
11
+ sibyl upgrade open the upgrade flow: Pro by card or USDC, or by
12
+ staking $SIBYL
13
+
14
+ Account calls go to https://api.sibyllabs.org (SIBYL_API_BASE overrides);
15
+ `sibyl update` also asks pypi.org for the latest releases.
16
+ """
17
+ # Lazy (PEP 562): `main` and `__version__` resolve on first access, so the
18
+ # `sibyl hook <event>` fast path (_entry.py -> hooks.py) imports neither the
19
+ # whole CLI nor importlib.metadata. `from sibyl_memory_cli import main` and
20
+ # `sibyl_memory_cli.__version__` work as before.
21
+
22
+
23
+ def __getattr__(name: str):
24
+ if name == "main":
25
+ from .cli import main
26
+ return main
27
+ if name == "__version__":
28
+ # Single-sourced from installed metadata so wheel + code can't drift
29
+ # (C3 audit fix v0.1.2). Same pattern as sibyl-memory-hermes v0.3.0+.
30
+ from importlib.metadata import PackageNotFoundError, version as _pkg_version
31
+ try:
32
+ v = _pkg_version("sibyl-memory-cli")
33
+ except PackageNotFoundError: # pragma: no cover - source-tree dev only
34
+ v = "0.0.0+source"
35
+ globals()["__version__"] = v
36
+ return v
37
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
38
+
39
+
40
+ __all__ = ["main", "__version__"]
sibyl-memory-cli/src/sibyl_memory_cli/_account_gate.py ADDED
@@ -0,0 +1,545 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """CLI side of the account gate (spec account-gated-plugin 2026-09-27, 3.4 and 5.6).
2
+
3
+ The gate itself lives in sibyl-memory-client (``_entitlement``). This module is
4
+ the CLI's thin layer over it:
5
+
6
+ * write / remove ``entitlement.json`` beside the credentials file
7
+ (``sibyl init``, ``sibyl email confirm``, ``sibyl logout``);
8
+ * the ``X-Sibyl-Entitlement`` header the CLI adds to every
9
+ session-authenticated call (only a token that verifies, is bound to this
10
+ computer and is inside ``exp + og``; never a token it knows the api would
11
+ refuse);
12
+ * the ``access`` status row and the ``health`` line;
13
+ * one-line copy for the api's 403 ``entitlement_invalid`` / ``client_too_old``.
14
+
15
+ Nothing here prints or logs a token or a session value.
16
+ """
17
+ from __future__ import annotations
18
+
19
+ import time
20
+ from pathlib import Path
21
+ from typing import Any
22
+
23
+ try: # the CLI stays importable without the client (update / setup paths)
24
+ from sibyl_memory_client import _entitlement as _E
25
+ except Exception: # pragma: no cover - client absent or pre-0.9.0
26
+ _E = None
27
+
28
+ ENTITLEMENT_FILENAME = "entitlement.json"
29
+ HEADER = "X-Sibyl-Entitlement"
30
+
31
+ CLIENT_TOO_OLD_LINE = ("update the plugin: pip install -U sibyl-memory-client sibyl-memory-mcp "
32
+ "sibyl-memory-hermes sibyl-memory-cli")
33
+ ENTITLEMENT_INVALID_LINE = ("this computer's sign-in file is damaged, expired or belongs to "
34
+ "another computer. run sibyl init to sign in again. your local "
35
+ "memory is kept.")
36
+ NO_ACCOUNT_MEMORY_LINE = "reading local data without an account. agents need sibyl init."
37
+ # 403 client_too_old while this computer holds no usable token: the plugin is
38
+ # current, the api refused an ABSENT token (after the min_client_version
39
+ # cutoff) because setup never finished. Same words as the setup_incomplete
40
+ # access row.
41
+ SETUP_INCOMPLETE_LINE = ("setup is not finished on this computer. connect to the internet once "
42
+ "to finish setup. nothing was deleted.")
43
+
44
+
45
+ # Follow-up D1 (2026-11-14): the CLI refused to send the sign-in because
46
+ # SIBYL_API_BASE is not https *.sibyllabs.org or a loopback address
47
+ # (cli.http_request raises HttpError(0, code untrusted_api_base); the client
48
+ # gate's refresh answers transient with the same code). Not a network fault:
49
+ # never "retry" and never "connect to the internet".
50
+ UNTRUSTED_BASE_CODE = "untrusted_api_base"
51
+ UNTRUSTED_BASE_LINE = "sign-in not sent: SIBYL_API_BASE is not a Sibyl address."
52
+ UNTRUSTED_BASE_HUMAN = ("SIBYL_API_BASE points at a host Sibyl will not send your sign-in to; "
53
+ "unset it")
54
+ UNTRUSTED_UPGRADE_HUMAN = ("SIBYL_UPGRADE_BASE points at a host Sibyl will not send your sign-in "
55
+ "to; unset it")
56
+
57
+
58
+ def untrusted_base_handoff() -> tuple[str, str | None]:
59
+ return ("done", UNTRUSTED_BASE_HUMAN)
60
+
61
+
62
+ def _unsafe_url_chars(url: str) -> bool:
63
+ return any(c == "\\" or c.isspace() or ord(c) < 0x20 or ord(c) == 0x7F for c in url)
64
+
65
+
66
+ def bearer_url_safe(url: Any) -> bool:
67
+ """Follow-up D3: the extra refusals the CLI applies before the client's
68
+ host rule, so cli 0.7.0 is protected with client 0.10.0 installed. A URL
69
+ with a backslash, whitespace or a control character, or with userinfo
70
+ (``https://evil.com\\@sibyllabs.org/x`` parses with hostname sibyllabs.org
71
+ while some HTTP stacks connect to evil.com), never gets the bearer."""
72
+ import urllib.parse
73
+ if not isinstance(url, str) or _unsafe_url_chars(url):
74
+ return False
75
+ try:
76
+ parsed = urllib.parse.urlparse(url)
77
+ if parsed.username is not None or parsed.password is not None:
78
+ return False
79
+ except ValueError:
80
+ return False
81
+ return True
82
+
83
+
84
+ def _guarded_refresh(account_id: str, session_token: str):
85
+ """The client's /entitlement transport behind the CLI's own URL check
86
+ (D3): the client gate's own rule alone accepts a userinfo URL."""
87
+ if not bearer_url_safe(_E._api_base() + _E.ENTITLEMENT_PATH):
88
+ return _E.RefreshOutcome("transient", code=UNTRUSTED_BASE_CODE)
89
+ return _E.http_refresh(account_id, session_token)
90
+
91
+
92
+ # F-1 (contract C1): the api's 401 ``code`` for a computer that was signed
93
+ # out when the account's email was confirmed on the account page.
94
+ SIGNED_OUT_ON_CLAIM = "signed_out_on_claim"
95
+ SIGNED_OUT_ON_CLAIM_NEXT = "sibyl init --force"
96
+
97
+
98
+ def signed_out_on_claim_line(signed_out_at: Any = None) -> str:
99
+ """'signed out: this computer was signed out when your email was confirmed
100
+ on the account page (2026-10-08 18:34 UTC). run: sibyl init --force'. The
101
+ parenthesis is left out when the api sent no usable time."""
102
+ from ._timefmt import utc_minute
103
+ when = utc_minute(signed_out_at) if isinstance(signed_out_at, str) else None
104
+ at = f" ({when})" if when else ""
105
+ return ("signed out: this computer was signed out when your email was confirmed on the "
106
+ f"account page{at}. run: {SIGNED_OUT_ON_CLAIM_NEXT}")
107
+
108
+
109
+ def entitlement_path(cred_path: Path) -> Path:
110
+ return Path(cred_path).expanduser().parent / ENTITLEMENT_FILENAME
111
+
112
+
113
+ def _shape_ok(token: Any) -> bool:
114
+ """Cheap shape check before writing (spec 9.5 item 24): a string, at most
115
+ 4096 bytes, printable ASCII, three segments, SE1 prefix. The signature is
116
+ verified by the gate on every use, never trusted from here."""
117
+ if not isinstance(token, str) or not token or len(token) > 4096:
118
+ return False
119
+ try:
120
+ raw = token.encode("ascii")
121
+ except UnicodeEncodeError:
122
+ return False
123
+ if any(b < 0x21 or b > 0x7E for b in raw):
124
+ return False
125
+ parts = token.split(".")
126
+ return len(parts) == 3 and parts[0] == "SE1" and all(parts[1:])
127
+
128
+
129
+ def write_entitlement_atomic(token: Any, cred_path: Path) -> Path | None:
130
+ """Write entitlement.json (0600, mkstemp + os.replace, symlink-refusing)
131
+ beside ``cred_path``. Returns the path, or None when the token is
132
+ malformed (ignored, nothing written) or the write was refused."""
133
+ if _E is None or not _shape_ok(token):
134
+ return None
135
+ store = _E.EntitlementStore(entitlement_path(cred_path))
136
+ now = time.time()
137
+ ok = store.store({"token": token, "received_at": now, "hwm": now})
138
+ return store.path if ok else None
139
+
140
+
141
+ def remove_entitlement(cred_path: Path) -> list[str]:
142
+ """Delete entitlement.json (and a leftover lock). Returns what was removed."""
143
+ removed: list[str] = []
144
+ for name in (ENTITLEMENT_FILENAME, "entitlement.lock"):
145
+ p = Path(cred_path).expanduser().parent / name
146
+ try:
147
+ if p.is_symlink() or p.exists():
148
+ p.unlink()
149
+ if name == ENTITLEMENT_FILENAME:
150
+ removed.append(str(p))
151
+ except OSError:
152
+ pass
153
+ return removed
154
+
155
+
156
+ def gate_for(cred_path: Path, *, background: bool = False):
157
+ if _E is None:
158
+ return None
159
+ return _E.EntitlementGate(Path(cred_path).expanduser(), background_refresh=background,
160
+ refresh_fn=_guarded_refresh)
161
+
162
+
163
+ def header_token(cred_path: Path) -> str | None:
164
+ """The token to present on a session-authenticated call, or None.
165
+
166
+ Read-only: no refresh here. A token past exp + og, unverifiable, or bound
167
+ to another session is never sent (the api would answer 403
168
+ entitlement_invalid); with no token the api accepts the call until
169
+ min_client_version is set."""
170
+ gate = gate_for(cred_path)
171
+ if gate is None:
172
+ return None
173
+ try:
174
+ return gate.peek_token()
175
+ except Exception:
176
+ return None
177
+
178
+
179
+ def has_account_access(cred_path: Path) -> bool:
180
+ """True when an agent on this computer could use memory right now
181
+ (fresh, stale or bootstrap grace), judged locally with no network."""
182
+ gate = gate_for(cred_path)
183
+ if gate is None:
184
+ return False
185
+ try:
186
+ return gate.peek().state in ("fresh", "stale", "bootstrap")
187
+ except Exception:
188
+ return False
189
+
190
+
191
+ def ensure_fresh_token(cred_path: Path) -> str | None:
192
+ """Security calls (logout revoke, device revoke): when there is no usable
193
+ token, try one blocking /entitlement refresh first, then return whatever
194
+ usable token exists (possibly None: the caller proceeds without it)."""
195
+ tok = header_token(cred_path)
196
+ if tok is not None:
197
+ return tok
198
+ gate = gate_for(cred_path)
199
+ if gate is None:
200
+ return None
201
+ try:
202
+ gate.refresh(blocking=True)
203
+ return gate.peek_token()
204
+ except Exception:
205
+ return None
206
+
207
+
208
+ def gate_http_line(status: int, code: str | None, *, cred_path: Path | None = None,
209
+ body: Any = None) -> str | None:
210
+ """One-line copy for the api's account-gate answers on CLI calls (5.6).
211
+
212
+ ``client_too_old`` with ``cred_path`` given and no usable token on this
213
+ computer (the client present) means the call went out WITHOUT a token and
214
+ was refused for that: the plugin is current, setup is not finished, so the
215
+ line is the setup one, not "update the plugin".
216
+
217
+ F-1: a 401 whose ``code`` is ``signed_out_on_claim`` gets its own
218
+ line, with the ``signed_out_at`` from ``body`` (the HttpError body)."""
219
+ if status == 0 and code == UNTRUSTED_BASE_CODE:
220
+ return UNTRUSTED_BASE_LINE
221
+ if status == 401 and code == SIGNED_OUT_ON_CLAIM:
222
+ return signed_out_on_claim_line(body.get("signed_out_at") if isinstance(body, dict) else None)
223
+ if status == 403 and code == "entitlement_invalid":
224
+ return ENTITLEMENT_INVALID_LINE
225
+ if status == 403 and code == "client_too_old":
226
+ if cred_path is not None and _E is not None and header_token(cred_path) is None:
227
+ return SETUP_INCOMPLETE_LINE
228
+ return CLIENT_TOO_OLD_LINE
229
+ return None
230
+
231
+
232
+ def status_info(cred_path: Path, *, refresh: bool) -> dict[str, Any] | None:
233
+ """The gate's view for `sibyl status` / `sibyl health`. With ``refresh``,
234
+ one blocking refresh attempt first (the refresh IS the status check).
235
+ Returns the gate's token-free status dict plus ``refreshed`` (the attempt's
236
+ outcome status) or None when the client is unavailable."""
237
+ gate = gate_for(cred_path)
238
+ if gate is None:
239
+ return None
240
+ outcome = None
241
+ if refresh:
242
+ try:
243
+ outcome = gate.refresh(blocking=True)
244
+ except Exception:
245
+ outcome = None
246
+ info = gate.status()
247
+ info["refreshed"] = getattr(outcome, "status", None)
248
+ info["refresh_code"] = getattr(outcome, "code", None)
249
+ return info
250
+
251
+
252
+ def _read_only_row(info: dict[str, Any]) -> str:
253
+ """R1 (plan 4.2): read-only because of the computer limit
254
+ (``acct.devices.over``) or, otherwise, the email."""
255
+ try:
256
+ from sibyl_memory_client.exceptions import SECURITY_URL, device_limit_info
257
+ d = device_limit_info(info.get("acct"))
258
+ except Exception:
259
+ d = None
260
+ if d is not None and d["over"]:
261
+ page = SECURITY_URL.split("://", 1)[-1]
262
+ return ("read only on this computer · more computers signed in than the plan allows: sign "
263
+ f"the others out at {page} (sibyl devices) or get Pro")
264
+ return "read only · confirm your email: sibyl email add you@example.com"
265
+
266
+
267
+ def has_valid_pass(info: dict[str, Any] | None) -> bool:
268
+ """A verified, bound pass this computer may use (fresh or stale)."""
269
+ return bool(info) and info.get("state") in ("fresh", "stale") and isinstance(info.get("tier"), str)
270
+
271
+
272
+ def display_tier(info: dict[str, Any] | None, saved: Any) -> Any:
273
+ """Shown-tier fix (2026-10-08): the tier every user-facing line shows. The current
274
+ verified pass's tier (as enforced: an unrecognised label is Free) when
275
+ there is a valid pass, else the saved credentials tier. One source per
276
+ screen, so two lines never show two tiers."""
277
+ if has_valid_pass(info):
278
+ return info.get("tier_effective") or info.get("tier")
279
+ return saved
280
+
281
+
282
+ def peek_tier(cred_path: Path, saved: Any) -> Any:
283
+ """display_tier with no network (init, whoami, upgrade). With no
284
+ entitlement file there is no pass, so nothing is evaluated (an evaluation
285
+ could leave a bookkeeping-only entitlement.json behind)."""
286
+ try:
287
+ p = entitlement_path(cred_path)
288
+ if p.is_symlink() or not p.is_file():
289
+ return saved
290
+ info = status_info(cred_path, refresh=False)
291
+ except Exception:
292
+ info = None
293
+ return display_tier(info, saved)
294
+
295
+
296
+ _MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
297
+
298
+
299
+ def _short_date(value: Any) -> str | None:
300
+ """'2027-10-08T12:00:00.000Z' -> '8 Oct 2027' in this computer's local
301
+ time, or None when the value is not an ISO timestamp."""
302
+ import calendar
303
+ import re
304
+ if not isinstance(value, str):
305
+ return None
306
+ m = re.match(r"^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})", value.strip())
307
+ if not m:
308
+ return None
309
+ try:
310
+ y, mo, d, hh, mi, ss = (int(x) for x in m.groups())
311
+ epoch = calendar.timegm((y, mo, d, hh, mi, ss, 0, 0, 0))
312
+ lt = time.localtime(epoch)
313
+ except (ValueError, OverflowError, OSError):
314
+ return None
315
+ return f"{lt.tm_mday} {_MONTHS[lt.tm_mon - 1]} {lt.tm_year}"
316
+
317
+
318
+ def plan_row(info: dict[str, Any] | None) -> str | None:
319
+ """Plan-end fix (2026-10-08): the `Plan` value, 'Pro · ends 8 Oct 2027' (a
320
+ scheduled or completed cancellation, or a fixed term) or 'Pro · renews
321
+ 8 Oct 2027' (a renewing card plan), from the pass's acct.plan. None when
322
+ there is no valid pass or the server sent no date (older servers, free,
323
+ staker, Lifetime). The tier word is the same one the Tier row shows."""
324
+ if not has_valid_pass(info):
325
+ return None
326
+ plan = info.get("plan")
327
+ if not isinstance(plan, dict):
328
+ return None
329
+ try:
330
+ from sibyl_memory_client.tiers import display
331
+ word = display(display_tier(info, None))
332
+ except Exception: # pragma: no cover - client absent
333
+ word = str(display_tier(info, None) or "").capitalize()
334
+ for key, verb in (("ends_at", "ends"), ("renews_at", "renews")):
335
+ when = _short_date(plan.get(key))
336
+ if when:
337
+ return f"{word} \u00b7 {verb} {when}"
338
+ return None
339
+
340
+
341
+ TIER_UNKNOWN = "tier_unknown"
342
+
343
+
344
+ def _tier_unknown_row(info: dict[str, Any]) -> str | None:
345
+ """Tier convention (2026-10-05): the two ``tier_unknown`` rows, or None.
346
+
347
+ * the server answered 503 ``tier_unknown`` to the renewal: the last valid
348
+ token is kept and this computer keeps working on it;
349
+ * the signed label is not one this version recognises: treated as Free
350
+ until the plugin is updated."""
351
+ if info.get("state") not in ("fresh", "stale", "bootstrap"):
352
+ return None
353
+ if info.get("refresh_code") == TIER_UNKNOWN:
354
+ return f"renewal paused · access label check ({TIER_UNKNOWN}) · keep working; it retries on its own"
355
+ if info.get("state") == "fresh" and info.get("tier_known") is False:
356
+ raw = str(info.get("tier") or "")[:32]
357
+ return (f'active · access label "{raw}" is not recognised by this version, treated as Free '
358
+ f"({TIER_UNKNOWN}) · run sibyl update")
359
+ return None
360
+
361
+
362
+ def _untrusted_offline(info: dict[str, Any]) -> bool:
363
+ """D1: the last refresh was not sent (untrusted SIBYL_API_BASE) and the
364
+ state is one whose copy would otherwise say "connect to the internet"."""
365
+ return (info.get("refresh_code") == UNTRUSTED_BASE_CODE
366
+ and (info.get("state") in ("stale", "bootstrap")
367
+ or info.get("code") in ("expired_offline", "setup_incomplete")))
368
+
369
+
370
+ def access_row(info: dict[str, Any]) -> str:
371
+ """The `access` eyebrow value (spec 3.4, 8.2-8.5)."""
372
+ state = info.get("state")
373
+ code = info.get("code")
374
+ tier_row = _tier_unknown_row(info)
375
+ if tier_row is not None:
376
+ return tier_row
377
+ if _untrusted_offline(info):
378
+ return "not checked · " + UNTRUSTED_BASE_LINE
379
+ if state == "fresh":
380
+ secs = info.get("renews_in_seconds") or 0
381
+ hours = max(0, int(round(secs / 3600)))
382
+ if info.get("mem") == "read_only":
383
+ # Reads work, writes are refused (policy_read_only): say why.
384
+ return _read_only_row(info) + f" · re-checks in {hours}h"
385
+ # Plan-end fix (2026-10-08): this is the pass re-check, not a billing renewal
386
+ # (the billing date is the Plan row).
387
+ return f"active · re-checks in {hours}h"
388
+ if state in ("stale", "bootstrap"):
389
+ left = info.get("grace_left_seconds") or 0
390
+ days = max(0, int(-(-left // 86400)))
391
+ return f"offline · {days} days of grace left · connect once to renew"
392
+ if state == "no_account":
393
+ return "signed out · run sibyl init"
394
+ if code == "policy_read_only":
395
+ return _read_only_row(info)
396
+ if code == "signed_out" and info.get("cause") == SIGNED_OUT_ON_CLAIM:
397
+ return signed_out_on_claim_line(info.get("signed_out_at"))
398
+ return {
399
+ "expired_offline": "paused · offline too long · connect to the internet, or run sibyl init",
400
+ "setup_incomplete": "setup not finished · connect to the internet once to finish setup",
401
+ "signed_out": "signed out · run sibyl init",
402
+ "under_review": "under review · email sibyl@sibyllabs.org",
403
+ "account_deleted": "account deleted · run sibyl init",
404
+ "invalid_entitlement": "sign-in file damaged · run sibyl init",
405
+ "wrong_device": "sign-in file damaged · run sibyl init",
406
+ "client_too_old": "update needed · " + CLIENT_TOO_OLD_LINE,
407
+ "policy_read_only": "read only · confirm your email: sibyl email add you@example.com",
408
+ "policy_none": "paused · confirm your email: sibyl email add you@example.com",
409
+ }.get(code or "", "signed out · run sibyl init")
410
+
411
+
412
+ def _devices_over(info: dict[str, Any]) -> bool:
413
+ try:
414
+ from sibyl_memory_client.exceptions import device_limit_info
415
+ d = device_limit_info(info.get("acct"))
416
+ except Exception:
417
+ d = None
418
+ return d is not None and d["over"]
419
+
420
+
421
+ def code_handoff(code: str | None) -> tuple[str, str | None]:
422
+ """(next, human) for an entitlement code (client table rows C1 to C11)."""
423
+ try:
424
+ from sibyl_memory_client.exceptions import ENTITLEMENT_HUMAN_ACTION, ENTITLEMENT_NEXT
425
+ except Exception: # pragma: no cover - client absent or pre-0.9.0
426
+ return ("sibyl init", None)
427
+ code = code if code in ENTITLEMENT_NEXT else "invalid_entitlement"
428
+ return ENTITLEMENT_NEXT[code], ENTITLEMENT_HUMAN_ACTION[code]
429
+
430
+
431
+ def _read_only_handoff(info: dict[str, Any]) -> tuple[str, str | None]:
432
+ if _devices_over(info):
433
+ try:
434
+ from sibyl_memory_client.exceptions import (DEVICES_READ_ONLY_HUMAN_ACTION,
435
+ DEVICES_READ_ONLY_NEXT)
436
+ return DEVICES_READ_ONLY_NEXT, DEVICES_READ_ONLY_HUMAN_ACTION
437
+ except Exception: # pragma: no cover
438
+ return "sibyl devices", None
439
+ return code_handoff("policy_read_only")
440
+
441
+
442
+ def access_handoff(info: dict[str, Any] | None) -> tuple[str, str | None]:
443
+ """The agent handoff for an access state (spec 2026-10-03 section 1.7):
444
+ (next, human). Kept beside ``access_row`` so status, refresh, health and
445
+ the gate lines agree (rows S3 to S8, R3, R4, H3c)."""
446
+ if not info:
447
+ return ("sibyl init", None)
448
+ state = info.get("state")
449
+ code = info.get("code")
450
+ if _untrusted_offline(info):
451
+ return untrusted_base_handoff()
452
+ if state in ("fresh", "stale", "bootstrap"):
453
+ if info.get("refresh_code") == TIER_UNKNOWN:
454
+ return ("done", None)
455
+ if state == "fresh" and info.get("tier_known") is False:
456
+ return ("sibyl update", None)
457
+ if state == "fresh":
458
+ if info.get("mem") == "read_only":
459
+ return _read_only_handoff(info)
460
+ return ("done", None)
461
+ if state in ("stale", "bootstrap"):
462
+ left = info.get("grace_left_seconds") or 0
463
+ days = max(0, int(-(-left // 86400)))
464
+ return ("sibyl refresh",
465
+ f"connect this computer to the internet once; memory keeps working {days} more days")
466
+ if state == "no_account":
467
+ return code_handoff("no_account")
468
+ if code == "policy_read_only":
469
+ return _read_only_handoff(info)
470
+ if code == "signed_out" and info.get("cause") == SIGNED_OUT_ON_CLAIM:
471
+ return (SIGNED_OUT_ON_CLAIM_NEXT, None)
472
+ return code_handoff(code or "signed_out")
473
+
474
+
475
+ def gate_http_handoff(status: int, code: str | None, *, cred_path: Path | None = None,
476
+ body: Any = None) -> tuple[str, str | None] | None:
477
+ """The handoff for the api's 403 gate answers (rows E23, K3, V4): the same
478
+ branch choice as ``gate_http_line``."""
479
+ line = gate_http_line(status, code, cred_path=cred_path, body=body)
480
+ if line is None:
481
+ return None
482
+ if line == UNTRUSTED_BASE_LINE:
483
+ return untrusted_base_handoff()
484
+ if status == 401 and code == SIGNED_OUT_ON_CLAIM:
485
+ return (SIGNED_OUT_ON_CLAIM_NEXT, None)
486
+ if line == ENTITLEMENT_INVALID_LINE:
487
+ return code_handoff("invalid_entitlement")
488
+ if line == SETUP_INCOMPLETE_LINE:
489
+ return code_handoff("setup_incomplete")
490
+ return code_handoff("client_too_old")
491
+
492
+
493
+ ADOPT_HINT = "run sibyl memory adopt to move them into your account"
494
+
495
+
496
+ def _creds_tenant(cred_path: Path) -> str | None:
497
+ import json
498
+ try:
499
+ p = Path(cred_path).expanduser()
500
+ if p.is_symlink() or not p.is_file():
501
+ return None
502
+ raw = json.loads(p.read_text(encoding="utf-8"))
503
+ except (OSError, ValueError):
504
+ return None
505
+ if not isinstance(raw, dict):
506
+ return None
507
+ return (raw.get("tenant_id") or "") or (raw.get("account_id") or "") or None
508
+
509
+
510
+ def adopt_pre_signin(db_path: Path, cred_path: Path, *, trigger: str,
511
+ confirm_other_accounts: bool = False):
512
+ """Move the rows written before sign-in (DEFAULT_TENANT) of ``db_path``
513
+ into the signed-in account's tenant (client ``_adopt``): one local
514
+ transaction, never deletes, no network of its own. Requires a verified
515
+ entitlement for the credentials at ``cred_path`` (``gate.require`` may do
516
+ the one blocking refresh a device without a token needs). Raises
517
+ ``EntitlementError`` when there is no verified sign-in and
518
+ ``_adopt.AdoptionRefused`` when the move is not allowed. Returns the
519
+ ``AdoptionResult``, or None when there is no store."""
520
+ from sibyl_memory_client import _adopt
521
+ from sibyl_memory_client.storage import Storage
522
+ db_path = Path(db_path).expanduser()
523
+ if not db_path.exists():
524
+ return None
525
+ gate = gate_for(cred_path)
526
+ ent = gate.require("adopt")
527
+ tenant = _creds_tenant(cred_path)
528
+ if ent is None or tenant is None:
529
+ raise _adopt.AdoptionRefused("not_verified",
530
+ "No verified sign-in on this computer. Run sibyl init first.")
531
+ storage = Storage(db_path)
532
+ try:
533
+ return _adopt.adopt_default_tenant(storage, tenant, ent, trigger=trigger,
534
+ confirm_other_accounts=confirm_other_accounts)
535
+ finally:
536
+ storage.close()
537
+
538
+
539
+ def pinned_kids() -> list[str]:
540
+ if _E is None:
541
+ return []
542
+ try:
543
+ return sorted(_E.TRUSTED_KEYS)
544
+ except Exception:
545
+ return []
sibyl-memory-cli/src/sibyl_memory_cli/_aesthetic.py ADDED
@@ -0,0 +1,251 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Shared visual identity for the sibyl CLI surface.
2
+
3
+ Sister module to `_banner.py`. Where the banner is the identity-reveal
4
+ moment for `sibyl init`, this module supplies the granular building
5
+ blocks every subcommand uses to share one coherent look:
6
+
7
+ - 24-bit-truecolor → 256-color → plain-text degradation cascade
8
+ - Brand palette derived from the lab creme paper face (rule 46)
9
+ - Letter-spaced eyebrow labels, gradient titles, ASCII rule dividers
10
+ - Key/value rows, status chips, success/warn/error glyphs
11
+ - Pulsing accents for live states (activation, upgrade, watching)
12
+
13
+ Voice constraint: precise, editorial, restrained. Gradients flow over
14
+ 2–3 stops max. No rainbow. The terminal is paper.
15
+ """
16
+ from __future__ import annotations
17
+
18
+ import os
19
+ import sys
20
+
21
+ # ─── Palette (RGB · derived from rule 46 creme-paper tokens) ─────────
22
+ # Names map 1:1 to CSS custom properties on lab artifacts.
23
+
24
+ PAPER = (245, 241, 230) # --paper — foreground accent on dark
25
+ PAPER_DEEP = (237, 230, 211) # --paper-deep — depth on creme
26
+ CARD = (253, 251, 245) # --card — slightly lifted creme
27
+ INK = (21, 17, 10) # --ink — main text on creme
28
+ INK_SOFT = (44, 39, 29) # --ink-soft — body text
29
+ INK_MUTE = (106, 99, 86) # --ink-mute — secondary text
30
+ INK_FAINT = (152, 145, 127) # --ink-faint — tertiary text
31
+ RULE = (216, 208, 187) # --rule — hairline
32
+ RULE_STRONG = (184, 174, 147) # --rule-strong — emphasised hairline
33
+ ACCENT = (138, 106, 42) # --accent — ochre highlight
34
+ ACCENT_WARM = (160, 132, 56) # --accent-warm — softer ochre
35
+ ACCENT_GOLD = (224, 194, 119) # mid gold — gradient bridge
36
+ ACCENT_PALE = (244, 229, 184) # pale gold — gradient top
37
+ JADE = (45, 110, 106) # --jade — cool counterpoint
38
+ PULSE = (29, 138, 130) # --pulse — brighter jade (live signal)
39
+ ERROR = (162, 58, 42) # --error — measured red
40
+
41
+ # Status glyphs (Unicode, terminal-safe in modern fonts)
42
+ GLYPH_OK = "✓"
43
+ GLYPH_WARN = "⚠"
44
+ GLYPH_ERR = "✗"
45
+ GLYPH_DOT = "·"
46
+ GLYPH_ARROW = "→"
47
+ GLYPH_BULLET = "▸"
48
+
49
+
50
+ # ─── Terminal capability detection ────────────────────────────────────
51
+
52
+ def supports_truecolor() -> bool:
53
+ """24-bit RGB ANSI. Same heuristic as _banner.py."""
54
+ if os.environ.get("NO_COLOR"):
55
+ return False
56
+ if os.environ.get("TERM", "").lower() == "dumb":
57
+ return False
58
+ # SIBYL_FORCE_COLOR=1 — explicit override for non-tty rendering
59
+ # (CI logs, doc captures, dev inspection inside the Claude harness).
60
+ if os.environ.get("SIBYL_FORCE_COLOR") == "1":
61
+ return True
62
+ if not sys.stdout.isatty():
63
+ return False
64
+ colorterm = os.environ.get("COLORTERM", "").lower()
65
+ if "truecolor" in colorterm or "24bit" in colorterm:
66
+ return True
67
+ term_program = os.environ.get("TERM_PROGRAM", "").lower()
68
+ if term_program in {"iterm.app", "wezterm", "ghostty", "vscode", "tabby"}:
69
+ return True
70
+ term = os.environ.get("TERM", "").lower()
71
+ if any(k in term for k in ("256color", "kitty", "alacritty", "xterm-direct")):
72
+ return True
73
+ return False
74
+
75
+
76
+ def supports_color() -> bool:
77
+ """Any color at all (3/4-bit fallback)."""
78
+ if os.environ.get("NO_COLOR"):
79
+ return False
80
+ if os.environ.get("TERM", "").lower() == "dumb":
81
+ return False
82
+ if os.environ.get("SIBYL_FORCE_COLOR") == "1":
83
+ return True
84
+ return sys.stdout.isatty()
85
+
86
+
87
+ _TC = supports_truecolor()
88
+ _C = supports_color()
89
+ RESET = "\033[0m" if _C else ""
90
+
91
+
92
+ def rgb(r: int, g: int, b: int) -> str:
93
+ """24-bit foreground escape (no-op if color disabled)."""
94
+ if not _TC:
95
+ return ""
96
+ return f"\033[38;2;{r};{g};{b}m"
97
+
98
+
99
+ def color(text: str, c: tuple[int, int, int]) -> str:
100
+ if not _TC:
101
+ return text
102
+ return f"{rgb(*c)}{text}{RESET}"
103
+
104
+
105
+ # ─── Gradient · char-by-char RGB interpolation ────────────────────────
106
+
107
+ def _interp(a: int, b: int, t: float) -> int:
108
+ return round(a + (b - a) * t)
109
+
110
+
111
+ def gradient(text: str, *stops: tuple[int, int, int]) -> str:
112
+ """Color a string with a gradient across N stops, one char at a time.
113
+
114
+ Plain-text fallback: returns the input unchanged when color is off.
115
+ Whitespace is preserved (uncolored to keep terminals consistent).
116
+ """
117
+ if not _TC or len(stops) < 2 or not text:
118
+ return text
119
+ out = []
120
+ chars = list(text)
121
+ # Distribute char index across stop segments
122
+ n = max(1, len(chars) - 1)
123
+ segs = len(stops) - 1
124
+ for i, ch in enumerate(chars):
125
+ if ch == " ":
126
+ out.append(ch)
127
+ continue
128
+ seg_f = (i / n) * segs
129
+ seg_i = min(int(seg_f), segs - 1)
130
+ t = seg_f - seg_i
131
+ a = stops[seg_i]
132
+ b = stops[seg_i + 1]
133
+ r = _interp(a[0], b[0], t)
134
+ g = _interp(a[1], b[1], t)
135
+ bb = _interp(a[2], b[2], t)
136
+ out.append(f"\033[38;2;{r};{g};{bb}m{ch}")
137
+ return "".join(out) + RESET
138
+
139
+
140
+ def gradient_gold(text: str) -> str:
141
+ """Pale-gold → deep-ochre flow. The brand's headline gradient."""
142
+ return gradient(text, ACCENT_PALE, ACCENT_GOLD, ACCENT)
143
+
144
+
145
+ def gradient_jade(text: str) -> str:
146
+ """Pulse → jade. Used for success states + live indicators."""
147
+ return gradient(text, PULSE, JADE)
148
+
149
+
150
+ # ─── Style primitives ─────────────────────────────────────────────────
151
+
152
+ def dim(s: str) -> str:
153
+ return color(s, INK_FAINT)
154
+
155
+
156
+ def muted(s: str) -> str:
157
+ return color(s, INK_MUTE)
158
+
159
+
160
+ def soft(s: str) -> str:
161
+ return color(s, INK_SOFT)
162
+
163
+
164
+ def ink(s: str) -> str:
165
+ return color(s, INK)
166
+
167
+
168
+ def ok(s: str) -> str:
169
+ return color(s, PULSE)
170
+
171
+
172
+ def warn(s: str) -> str:
173
+ return color(s, ACCENT_WARM)
174
+
175
+
176
+ def err(s: str) -> str:
177
+ return color(s, ERROR)
178
+
179
+
180
+ def accent(s: str) -> str:
181
+ return color(s, ACCENT)
182
+
183
+
184
+ def bold(s: str) -> str:
185
+ if not _C:
186
+ return s
187
+ return f"\033[1m{s}{RESET}"
188
+
189
+
190
+ # ─── Composite primitives ─────────────────────────────────────────────
191
+
192
+ def eyebrow(label: str) -> str:
193
+ """Uppercase letter-spaced ochre label. Editorial section marker."""
194
+ spaced = " ".join(label.upper())
195
+ return color(spaced, ACCENT)
196
+
197
+
198
+ def section_header(name: str, *, subtitle: str | None = None, width: int = 60) -> str:
199
+ """The standard subcommand opener.
200
+
201
+ ─ <name> ────────────────────────────────────────
202
+ <subtitle, dim>
203
+ """
204
+ name_part = f" {gradient_gold(name)} "
205
+ # Stripped-color length for visible width calc
206
+ visible_name_len = len(f" {name} ")
207
+ rule_left = "─"
208
+ rule_right = "─" * max(3, width - 1 - visible_name_len)
209
+ head = color(rule_left, RULE) + name_part + color(rule_right, RULE)
210
+ if subtitle:
211
+ return head + "\n" + dim(subtitle)
212
+ return head
213
+
214
+
215
+ def chip(text: str, *, palette: str = "accent") -> str:
216
+ """Compact inline label · [text]."""
217
+ palettes = {
218
+ "accent": ACCENT,
219
+ "jade": PULSE,
220
+ "warn": ACCENT_WARM,
221
+ "error": ERROR,
222
+ "mute": INK_MUTE,
223
+ }
224
+ c = palettes.get(palette, ACCENT)
225
+ return color(f"[{text}]", c)
226
+
227
+
228
+ def kv(label: str, value: str, *, label_width: int = 16, value_color: str = "ink") -> str:
229
+ """One left-aligned label / value row.
230
+
231
+ Used across status / whoami / devices for the LOCAL / SERVER blocks.
232
+ """
233
+ palettes = {
234
+ "ink": INK, "soft": INK_SOFT, "mute": INK_MUTE, "faint": INK_FAINT,
235
+ "accent": ACCENT, "ok": PULSE, "warn": ACCENT_WARM, "err": ERROR,
236
+ }
237
+ val_color = palettes.get(value_color, INK_SOFT)
238
+ return f" {color(label.ljust(label_width), INK_FAINT)} {color(value, val_color)}"
239
+
240
+
241
+ def success_line(text: str) -> str:
242
+ """Single-line success marker with gradient + glyph."""
243
+ return f" {ok(GLYPH_OK)} {gradient_jade(text)}"
244
+
245
+
246
+ def warn_line(text: str) -> str:
247
+ return f" {warn(GLYPH_WARN)} {warn(text)}"
248
+
249
+
250
+ def err_line(text: str) -> str:
251
+ return f" {err(GLYPH_ERR)} {err(text)}"
sibyl-memory-cli/src/sibyl_memory_cli/_banner.py ADDED
@@ -0,0 +1,114 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """ASCII banner for sibyl-memory-cli.
2
+
3
+ Prints the SIBYL wordmark in ANSI Shadow boxchars with a 24-bit truecolor
4
+ vertical gradient flowing from cream/white at the top through warm gold
5
+ to deep ochre at the bottom — aligned with the lab visual identity per
6
+ the operator's brand-discipline rule (creme palette, deep-ochre accent).
7
+
8
+ Gracefully degrades:
9
+ - NO_COLOR env var set → plain text fallback
10
+ - stdout is not a TTY → plain text fallback (or skip entirely)
11
+ - TERM=dumb → plain text fallback
12
+
13
+ Truecolor support is detected via $COLORTERM (truecolor / 24bit) — most
14
+ modern terminals (iTerm2, Alacritty, Kitty, wezterm, Windows Terminal,
15
+ modern xterm builds, Ghostty) advertise it. Falls back to 256-color
16
+ gradient when not available.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import os
21
+ import sys
22
+
23
+ # ANSI Shadow rendering of "SIBYL" — 6 rows, 41 cols. Each row gets its
24
+ # own gradient color (top = pale cream/white, bottom = deep ochre).
25
+ _LINES = (
26
+ "███████╗██╗██████╗ ██╗ ██╗██╗ ",
27
+ "██╔════╝██║██╔══██╗╚██╗ ██╔╝██║ ",
28
+ "███████╗██║██████╔╝ ╚████╔╝ ██║ ",
29
+ "╚════██║██║██╔══██╗ ╚██╔╝ ██║ ",
30
+ "███████║██║██████╔╝ ██║ ███████╗",
31
+ "╚══════╝╚═╝╚═════╝ ╚═╝ ╚══════╝",
32
+ )
33
+
34
+ # Vertical gradient · cream → gold → deep ochre. One RGB tuple per row.
35
+ # Tuned against the SIBYL palette: --paper #f5f1e6 (top blend),
36
+ # --accent #8a6a2a (mid-bottom), with extra highlight + shadow stops
37
+ # to give the wordmark visible dimension.
38
+ _GRADIENT = (
39
+ (253, 251, 245), # almost white, slight cream (top highlight)
40
+ (244, 229, 184), # pale gold (upper)
41
+ (224, 194, 119), # mid gold (upper-mid)
42
+ (184, 146, 73), # rich ochre gold (mid)
43
+ (138, 106, 42), # deep ochre · brand --accent (lower)
44
+ (106, 79, 31), # deepest (bottom shadow)
45
+ )
46
+
47
+ _TAGLINE = "memory you can hold in your hand"
48
+ _ATTRIBUTION = "a Sibyl Labs LLC Product. Agentic Infrastructure and Memory Products"
49
+
50
+
51
+ def _supports_truecolor() -> bool:
52
+ """Detect 24-bit color support. Conservative — fall back gracefully."""
53
+ if os.environ.get("NO_COLOR"):
54
+ return False
55
+ if os.environ.get("TERM", "").lower() == "dumb":
56
+ return False
57
+ if not sys.stdout.isatty():
58
+ return False
59
+ colorterm = os.environ.get("COLORTERM", "").lower()
60
+ if "truecolor" in colorterm or "24bit" in colorterm:
61
+ return True
62
+ # Many modern terminals don't set COLORTERM but do support truecolor.
63
+ # Recognize the well-behaved emitters.
64
+ term_program = os.environ.get("TERM_PROGRAM", "").lower()
65
+ if term_program in {"iterm.app", "wezterm", "ghostty", "vscode", "tabby"}:
66
+ return True
67
+ term = os.environ.get("TERM", "").lower()
68
+ if any(k in term for k in ("256color", "kitty", "alacritty", "xterm-direct")):
69
+ return True
70
+ return False
71
+
72
+
73
+ def _rgb(r: int, g: int, b: int) -> str:
74
+ return f"\033[38;2;{r};{g};{b}m"
75
+
76
+
77
+ _RESET = "\033[0m"
78
+
79
+
80
+ def render_banner(*, force_color: bool | None = None) -> str:
81
+ """Return the banner as a string ready to print.
82
+
83
+ Args:
84
+ force_color: Override auto-detection. None = auto, True = force
85
+ truecolor, False = force plain text. Useful for testing.
86
+ """
87
+ use_truecolor = force_color if force_color is not None else _supports_truecolor()
88
+
89
+ if not use_truecolor:
90
+ # Plain text — still visually clean, just no color.
91
+ body = "\n".join(" " + line for line in _LINES)
92
+ tagline = f"\n {_TAGLINE}"
93
+ attribution = f"\n {_ATTRIBUTION}\n"
94
+ return body + tagline + attribution
95
+
96
+ # Colored — apply per-row gradient.
97
+ colored_lines = []
98
+ for line, (r, g, b) in zip(_LINES, _GRADIENT):
99
+ colored_lines.append(f" {_rgb(r, g, b)}{line}{_RESET}")
100
+
101
+ body = "\n".join(colored_lines)
102
+ # Tagline in the deepest gold — present, but not competing with the wordmark.
103
+ r, g, b = _GRADIENT[-1]
104
+ tagline = f"\n {_rgb(r, g, b)}{_TAGLINE}{_RESET}"
105
+ # Attribution dimmer still — a half-step below the tagline so the hierarchy
106
+ # reads SIBYL > tagline > attribution at a glance. ANSI dim (\033[2m) gives
107
+ # ~55% perceived opacity across the supported terminals.
108
+ attribution = f"\n \033[2m{_rgb(r, g, b)}{_ATTRIBUTION}{_RESET}\n"
109
+ return body + tagline + attribution
110
+
111
+
112
+ def print_banner(*, force_color: bool | None = None) -> None:
113
+ """Print the banner. Safe to call unconditionally; honors NO_COLOR + TTY checks."""
114
+ print(render_banner(force_color=force_color))
sibyl-memory-cli/src/sibyl_memory_cli/_entry.py ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """The `sibyl` console script (0.5.0).
2
+
3
+ `sibyl hook <event>` is what Claude Code runs at every session start, prompt,
4
+ turn end, compaction and session end, under a 5 s timeout. It goes straight to
5
+ ``hooks.main_hook`` (standard library only until a hook actually needs the
6
+ client) instead of importing the whole CLI first. Every other command is the
7
+ unchanged ``cli.main``.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import sys
12
+
13
+ _HOOK_EVENTS = ("session-start", "prompt", "stop", "pre-compact", "session-end")
14
+
15
+
16
+ def main(argv: list[str] | None = None) -> int:
17
+ args = sys.argv[1:] if argv is None else list(argv)
18
+ if len(args) == 2 and args[0] == "hook" and args[1] in _HOOK_EVENTS:
19
+ from .hooks import main_hook
20
+ return main_hook(args[1])
21
+ from .cli import main as cli_main
22
+ return cli_main(argv)
23
+
24
+
25
+ if __name__ == "__main__": # pragma: no cover
26
+ sys.exit(main())
sibyl-memory-cli/src/sibyl_memory_cli/_handoff.py ADDED
@@ -0,0 +1,75 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Agent handoff block (spec agent-handoff-messages 2026-10-03, section 1).
2
+
3
+ Every stop of a ``sibyl`` command ends with this block, printed to stdout in
4
+ both interactive and non-interactive runs, after the status line:
5
+
6
+ later: <command> zero or more; optional follow-ups
7
+ ask your human: <sentence> zero or one; only when a person must act
8
+ next: <command> exactly one; always the last line
9
+
10
+ A wait (the process is still running and watching) prints, once, when the
11
+ watching starts:
12
+
13
+ ask your human: <sentence>
14
+ waiting: <what is watched> (up to <m:ss>)
15
+
16
+ Plain text at column 0: lowercase key, one colon, one space, no glyph, no
17
+ colour, no indentation, even on a TTY. ``next`` is a shell command, ``done``,
18
+ ``retry`` or ``retry in <N> minutes``. Placeholders (``<code>``,
19
+ ``<address>``, ``<index>``, ``<cs_code>``, ``<file>``) appear only when the
20
+ ``ask your human:`` line names them.
21
+
22
+ With ``--json`` the block is never printed; ``json_handoff`` adds the same two
23
+ values to the document as ``next`` and ``human_action``.
24
+ """
25
+ from __future__ import annotations
26
+
27
+ from typing import Any, Iterable
28
+
29
+ DONE = "done"
30
+ RETRY = "retry"
31
+
32
+
33
+ def retry_in(minutes: Any) -> str:
34
+ return f"retry in {minutes} minutes"
35
+
36
+
37
+ def block(next: str, *, human: str | None = None, later: Iterable[str] = ()) -> str:
38
+ lines = [f"later: {c}" for c in later if c]
39
+ if human:
40
+ lines.append(f"ask your human: {human}")
41
+ lines.append(f"next: {next}")
42
+ return "\n".join(lines)
43
+
44
+
45
+ def handoff(next: str, *, human: str | None = None, later: Iterable[str] = ()) -> None:
46
+ """Print the handoff block (the last thing a stopping command prints)."""
47
+ print(block(next, human=human, later=later), flush=True)
48
+
49
+
50
+ def waiting(what: str, seconds: Any, *, human: str | None = None) -> None:
51
+ """Print the wait lines once, when the watching starts."""
52
+ try:
53
+ secs = max(0, int(seconds))
54
+ except (TypeError, ValueError):
55
+ secs = 0
56
+ if human:
57
+ print(f"ask your human: {human}", flush=True)
58
+ print(f"waiting: {what} (up to {secs // 60}:{secs % 60:02d})", flush=True)
59
+
60
+
61
+ def json_handoff(payload: dict, next: str, human: str | None = None) -> dict:
62
+ """Add the two handoff keys to a ``--json`` document."""
63
+ payload["next"] = next
64
+ payload["human_action"] = human
65
+ return payload
66
+
67
+
68
+ def from_exception(e: BaseException, *, default: str = "sibyl status") -> tuple[str, str | None]:
69
+ """(next, human) carried by a client exception (rows C1 to C17), or the
70
+ default when the exception predates the convention."""
71
+ nxt = getattr(e, "next", None)
72
+ if not isinstance(nxt, str) or not nxt:
73
+ return default, None
74
+ human = getattr(e, "human_action", None)
75
+ return nxt, human if isinstance(human, str) and human else None
sibyl-memory-cli/src/sibyl_memory_cli/_timefmt.py ADDED
@@ -0,0 +1,61 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Times shown to people: always with a zone.
2
+
3
+ Every clock time the CLI prints is UTC and says so: ``2026-10-09 19:08 UTC``.
4
+ A bare ``2026-10-09 19:08:12`` read as local time by one person and as server
5
+ time by another; the zone removes the guess. Stdlib only.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import calendar
10
+ import re
11
+ import time
12
+ from typing import Any
13
+
14
+ _ISO_RE = re.compile(r"^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?"
15
+ r"(Z|[+-]\d{2}:?\d{2})?$")
16
+
17
+
18
+ def _epoch_of(value: Any) -> float | None:
19
+ if isinstance(value, bool):
20
+ return None
21
+ if isinstance(value, (int, float)):
22
+ return float(value)
23
+ if not isinstance(value, str) or len(value) > 40:
24
+ return None
25
+ m = _ISO_RE.match(value.strip())
26
+ if not m:
27
+ return None
28
+ try:
29
+ y, mo, d, hh, mi = (int(m.group(i)) for i in range(1, 6))
30
+ epoch = calendar.timegm((y, mo, d, hh, mi, int(m.group(6) or 0), 0, 0, 0))
31
+ except (ValueError, OverflowError):
32
+ return None
33
+ off = m.group(7)
34
+ if off and off != "Z":
35
+ sign = -1 if off[0] == "-" else 1
36
+ digits = off[1:].replace(":", "")
37
+ epoch -= sign * (int(digits[:2]) * 3600 + int(digits[2:]) * 60)
38
+ return float(epoch)
39
+
40
+
41
+ def utc_minute(value: Any) -> str | None:
42
+ """Epoch seconds or an ISO-8601 string (no offset = UTC) ->
43
+ ``'2026-10-09 19:08 UTC'``; None when ``value`` is neither."""
44
+ epoch = _epoch_of(value)
45
+ if epoch is None:
46
+ return None
47
+ try:
48
+ return time.strftime("%Y-%m-%d %H:%M", time.gmtime(epoch)) + " UTC"
49
+ except (ValueError, OverflowError, OSError):
50
+ return None
51
+
52
+
53
+ def utc_hm(value: Any) -> str | None:
54
+ """Epoch seconds -> ``'19:08 UTC'`` (a time of day, for today's rows)."""
55
+ epoch = _epoch_of(value)
56
+ if epoch is None:
57
+ return None
58
+ try:
59
+ return time.strftime("%H:%M", time.gmtime(epoch)) + " UTC"
60
+ except (ValueError, OverflowError, OSError):
61
+ return None
sibyl-memory-cli/src/sibyl_memory_cli/cli.py ADDED
The diff for this file is too large to render. See raw diff
 
sibyl-memory-cli/src/sibyl_memory_cli/doctor.py ADDED
@@ -0,0 +1,682 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """`sibyl doctor`: end-to-end check of the MCP path an agent actually uses.
2
+
3
+ Starts the real ``sibyl-memory-mcp`` stdio server, lists its tools, saves a
4
+ clearly MARKED test memory, recalls it, deletes it, then verifies nothing is
5
+ left behind. Reports pass/fail per step.
6
+
7
+ Deletion note: the server's ``memory_forget`` tool ARCHIVES (the body is kept in
8
+ ``archived_entities``). A doctor run must leave no data, so after exercising
9
+ ``memory_forget`` the exact test row (a unique uuid name) is purged from both
10
+ ``entities`` and ``archived_entities`` with a narrowly scoped DELETE, and the
11
+ purge is verified with row counts. Nothing but that one name is ever touched.
12
+
13
+ The MCP client here is a minimal newline-delimited JSON-RPC speaker over the
14
+ child's pipes (no dependency on the ``mcp`` package).
15
+
16
+ Harness checks (cli 0.7.0, spec dsh-doctor v2 section 5): after the server
17
+ round trip, each detected harness's sibyl-memory wiring is probed and
18
+ reported (ok, missing, stale, broken, foreign, duplicate, unreadable,
19
+ disabled, overridden, unverifiable). Read-only by default. ``--fix`` repairs
20
+ stale and broken entries without asking; at a terminal each repair is asked,
21
+ default No. A missing entry is a warning and is never added (the
22
+ ``sibyl setup <target>`` command is named instead). Doctor never installs
23
+ packages and only ever starts a command whose name starts with
24
+ sibyl-memory-mcp. Timestamped ``.bak`` files older versions left beside
25
+ harness configs are listed, never touched.
26
+ """
27
+ from __future__ import annotations
28
+
29
+ import contextlib
30
+ import io
31
+ import json
32
+ import os
33
+ import queue
34
+ import re
35
+ import shutil
36
+ import sqlite3
37
+ import subprocess
38
+ import sys
39
+ import threading
40
+ import time
41
+ import uuid
42
+ from dataclasses import asdict, dataclass
43
+ from pathlib import Path
44
+ from typing import Any, Callable, Optional
45
+
46
+ from . import _aesthetic as a
47
+
48
+ TEST_CATEGORY = "_sibyl_doctor"
49
+ REQUIRED_TOOLS = ("memory_remember", "memory_recall", "memory_forget")
50
+ STEP_TIMEOUT = 25.0
51
+
52
+
53
+ @dataclass
54
+ class Step:
55
+ name: str
56
+ ok: bool
57
+ detail: str = ""
58
+ skipped: bool = False
59
+
60
+
61
+ class McpStdioClient:
62
+ """Just enough MCP over stdio: initialize, tools/list, tools/call."""
63
+
64
+ def __init__(self, cmd: list, env: dict):
65
+ self.proc = subprocess.Popen(
66
+ cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, env=env)
67
+ self._q: "queue.Queue[dict]" = queue.Queue()
68
+ self._next = 1
69
+ self._err = b""
70
+ threading.Thread(target=self._read, daemon=True).start()
71
+ threading.Thread(target=self._drain_err, daemon=True).start()
72
+
73
+ def _drain_err(self) -> None:
74
+ try:
75
+ for chunk in iter(lambda: self.proc.stderr.read(1024), b""):
76
+ self._err = (self._err + chunk)[-2000:]
77
+ except Exception:
78
+ pass
79
+
80
+ def _read(self) -> None:
81
+ try:
82
+ for line in self.proc.stdout:
83
+ line = line.strip()
84
+ if not line:
85
+ continue
86
+ try:
87
+ msg = json.loads(line)
88
+ except ValueError:
89
+ continue
90
+ if isinstance(msg, dict):
91
+ self._q.put(msg)
92
+ except Exception:
93
+ pass
94
+
95
+ def _send(self, obj: dict) -> None:
96
+ self.proc.stdin.write((json.dumps(obj) + "\n").encode())
97
+ self.proc.stdin.flush()
98
+
99
+ def request(self, method: str, params: Optional[dict] = None, timeout: float = STEP_TIMEOUT) -> dict:
100
+ rid = self._next
101
+ self._next += 1
102
+ self._send({"jsonrpc": "2.0", "id": rid, "method": method, "params": params or {}})
103
+ deadline = time.monotonic() + timeout
104
+ while True:
105
+ left = deadline - time.monotonic()
106
+ if left <= 0:
107
+ raise TimeoutError(f"{method} timed out after {timeout:.0f}s")
108
+ try:
109
+ msg = self._q.get(timeout=left)
110
+ except queue.Empty:
111
+ continue
112
+ if msg.get("id") == rid and ("result" in msg or "error" in msg):
113
+ if "error" in msg:
114
+ raise RuntimeError(f"{method}: {msg['error']}")
115
+ return msg["result"]
116
+ if self.proc.poll() is not None and self._q.empty():
117
+ raise RuntimeError(f"server exited (code {self.proc.returncode}): "
118
+ f"{self._err.decode(errors='replace')[:200]}")
119
+
120
+ def initialize(self) -> dict:
121
+ res = self.request("initialize", {
122
+ "protocolVersion": "2024-11-05", "capabilities": {},
123
+ "clientInfo": {"name": "sibyl-doctor", "version": "1"}})
124
+ self._send({"jsonrpc": "2.0", "method": "notifications/initialized"})
125
+ return res
126
+
127
+ def call(self, tool: str, arguments: dict) -> tuple:
128
+ """Returns (is_error, payload dict)."""
129
+ res = self.request("tools/call", {"name": tool, "arguments": arguments})
130
+ payload: Any = res.get("structuredContent")
131
+ if not isinstance(payload, dict):
132
+ payload = {}
133
+ for part in res.get("content") or []:
134
+ if isinstance(part, dict) and part.get("type") == "text":
135
+ try:
136
+ loaded = json.loads(part.get("text", ""))
137
+ if isinstance(loaded, dict):
138
+ payload = loaded
139
+ break
140
+ except ValueError:
141
+ payload = {"message": str(part.get("text", ""))[:300]}
142
+ return bool(res.get("isError")), payload
143
+
144
+ def close(self) -> None:
145
+ try:
146
+ self.proc.stdin.close()
147
+ except Exception:
148
+ pass
149
+ try:
150
+ self.proc.terminate()
151
+ self.proc.wait(timeout=3)
152
+ except Exception:
153
+ try:
154
+ self.proc.kill()
155
+ except Exception:
156
+ pass
157
+
158
+
159
+ def purge_test_rows(db_path: Path, name: str) -> int:
160
+ """Delete the doctor's test rows (exact category + unique name) from
161
+ entities and archived_entities. Returns how many rows remain (0 = clean)."""
162
+ if not db_path.exists():
163
+ return 0
164
+ conn = sqlite3.connect(str(db_path), timeout=10)
165
+ try:
166
+ for table in ("entities", "archived_entities"):
167
+ try:
168
+ conn.execute(f"DELETE FROM {table} WHERE category = ? AND name = ?",
169
+ (TEST_CATEGORY, name))
170
+ except sqlite3.Error:
171
+ pass
172
+ conn.commit()
173
+ left = 0
174
+ for table in ("entities", "archived_entities"):
175
+ try:
176
+ left += conn.execute(
177
+ f"SELECT COUNT(*) FROM {table} WHERE category = ? AND name = ?",
178
+ (TEST_CATEGORY, name)).fetchone()[0]
179
+ except sqlite3.Error:
180
+ pass
181
+ return left
182
+ finally:
183
+ conn.close()
184
+
185
+
186
+ def run_checks(*, server_cmd: list, db_path: Path, cred_path: Path,
187
+ purge: Callable[[Path, str], int] = purge_test_rows) -> list:
188
+ steps: list = []
189
+ env = dict(os.environ)
190
+ env["SIBYL_MEMORY_DB"] = str(db_path)
191
+ env["SIBYL_CREDENTIALS"] = str(cred_path)
192
+ name = f"doctor-test-{uuid.uuid4().hex[:12]}"
193
+ marker = f"SIBYL-DOCTOR-TEST-{uuid.uuid4().hex}"
194
+ body = {"marker": marker, "note": "sibyl doctor test memory. Safe to delete; removed automatically."}
195
+
196
+ try:
197
+ client = McpStdioClient(server_cmd, env)
198
+ except Exception as e:
199
+ steps.append(Step("start server", False, f"{type(e).__name__}: {e}"))
200
+ return steps
201
+
202
+ saved = False
203
+ try:
204
+ try:
205
+ info = client.initialize()
206
+ sv = (info.get("serverInfo") or {})
207
+ steps.append(Step("start server", True,
208
+ f"{sv.get('name', 'mcp server')} {sv.get('version', '')}".strip()))
209
+ except Exception as e:
210
+ steps.append(Step("start server", False, str(e)))
211
+ return steps
212
+
213
+ try:
214
+ tools = [t.get("name") for t in client.request("tools/list").get("tools", [])]
215
+ missing = [t for t in REQUIRED_TOOLS if t not in tools]
216
+ if missing:
217
+ steps.append(Step("list tools", False, "missing: " + ", ".join(missing)))
218
+ return steps
219
+ steps.append(Step("list tools", True, f"{len(tools)} tools"))
220
+ except Exception as e:
221
+ steps.append(Step("list tools", False, str(e)))
222
+ return steps
223
+
224
+ try:
225
+ is_err, res = client.call("memory_remember",
226
+ {"category": TEST_CATEGORY, "name": name, "body": body})
227
+ if is_err or not res.get("ok", False):
228
+ raw = json.dumps(res)[:300] if res else "tool error"
229
+ code = res.get("code") if isinstance(res, dict) else None
230
+ if code == "ACCOUNT_REQUIRED" or "ACCOUNT_REQUIRED" in raw:
231
+ steps.append(Step("save test memory", False,
232
+ "sign-in required: run `sibyl init` in a terminal, then re-run `sibyl doctor`"))
233
+ else:
234
+ steps.append(Step("save test memory", False, raw))
235
+ for n in ("recall test memory", "delete test memory"):
236
+ steps.append(Step(n, False, "skipped (save failed)", skipped=True))
237
+ return steps
238
+ saved = True
239
+ steps.append(Step("save test memory", True, f"{TEST_CATEGORY}/{name}"))
240
+ except Exception as e:
241
+ steps.append(Step("save test memory", False, str(e)))
242
+ return steps
243
+
244
+ try:
245
+ is_err, res = client.call("memory_recall", {"category": TEST_CATEGORY, "name": name})
246
+ text = json.dumps(res)
247
+ if is_err or marker not in text:
248
+ steps.append(Step("recall test memory", False, "saved memory did not come back"))
249
+ else:
250
+ steps.append(Step("recall test memory", True, "marker round-tripped"))
251
+ except Exception as e:
252
+ steps.append(Step("recall test memory", False, str(e)))
253
+
254
+ try:
255
+ is_err, res = client.call("memory_forget",
256
+ {"category": TEST_CATEGORY, "name": name,
257
+ "reason": "sibyl doctor cleanup"})
258
+ if is_err:
259
+ steps.append(Step("delete test memory", False, json.dumps(res)[:300]))
260
+ else:
261
+ steps.append(Step("delete test memory", True, "forgotten via memory_forget"))
262
+ except Exception as e:
263
+ steps.append(Step("delete test memory", False, str(e)))
264
+ finally:
265
+ client.close()
266
+ if saved:
267
+ # Runs even when a step above failed: the doctor never leaves data.
268
+ try:
269
+ left = purge(db_path, name)
270
+ if left:
271
+ steps.append(Step("verify nothing left behind", False,
272
+ f"{left} test row(s) remain for {TEST_CATEGORY}/{name}"))
273
+ else:
274
+ steps.append(Step("verify nothing left behind", True, "0 test rows remain"))
275
+ except Exception as e:
276
+ steps.append(Step("verify nothing left behind", False,
277
+ f"{type(e).__name__}: {e}"))
278
+ return steps
279
+
280
+
281
+ def _server_cmd() -> Optional[list]:
282
+ from .setup import resolve_mcp_binary # same lookup as setup (cli 0.6.1)
283
+ w = resolve_mcp_binary()
284
+ return [w] if w else None
285
+
286
+
287
+ # ----------------------------------------------------------------------
288
+ # Harness checks (spec dsh-doctor v2, 5.2 to 5.7)
289
+ # ----------------------------------------------------------------------
290
+
291
+ @dataclass
292
+ class HarnessCheck:
293
+ name: str # wirer.name
294
+ display_name: str
295
+ location: str # "" or "home" / "profile:<name>" for DeepSeek Harness
296
+ status: str # ok | missing | stale | broken | foreign | duplicate | unreadable
297
+ # | disabled | overridden | unverifiable
298
+ level: str # pass | warn | fail
299
+ command: Optional[str]
300
+ config_path: str
301
+ detail: str
302
+ fixable: bool
303
+ hint: str = "" # e.g. "sibyl setup cursor" for missing
304
+ fixed: bool = False
305
+ fix_message: str = ""
306
+ # Panel fix 8: text to paste by hand, kept with its newlines (valid YAML
307
+ # or TOML as printed); printed under the FAIL line.
308
+ fix_block: str = ""
309
+
310
+
311
+ _WARN_STATUSES = ("foreign", "duplicate", "unreadable", "disabled", "overridden", "unverifiable")
312
+
313
+
314
+ def _loc_suffix(location: str) -> str:
315
+ if location.startswith("profile:"):
316
+ return ", profile " + location.split(":", 1)[1]
317
+ return ""
318
+
319
+
320
+ def _abs_command(cmd: str) -> Optional[str]:
321
+ if os.path.isabs(cmd):
322
+ return cmd
323
+ w = shutil.which(cmd)
324
+ return os.path.abspath(w) if w else None
325
+
326
+
327
+ def check_harness(wirer: Any, probe: dict, *, verified: dict) -> HarnessCheck:
328
+ """Turn one probe into a check. ``verified`` caches _verify_mcp_starts
329
+ results per absolute path (the round-trip server path is pre-seeded)."""
330
+ from . import setup as S
331
+ entry = probe.get("entry")
332
+ cmd = probe.get("command")
333
+ cfg = str(probe.get("config_path") or "")
334
+ loc = probe.get("location") or ""
335
+ pdetail = probe.get("detail") or ""
336
+
337
+ def mk(status: str, level: str, detail: str, fixable: bool = False, hint: str = "") -> HarnessCheck:
338
+ return HarnessCheck(wirer.name, wirer.display_name, loc, status, level, cmd, cfg,
339
+ detail, fixable, hint)
340
+
341
+ if entry in _WARN_STATUSES:
342
+ # Name the config file once (sandbox M4): a detail that already lists
343
+ # it, such as the duplicate one, is not followed by it again.
344
+ if not pdetail:
345
+ c = mk(entry, "warn", f"{entry}: see {cfg}")
346
+ elif cfg and cfg in pdetail:
347
+ c = mk(entry, "warn", f"{entry}: {pdetail}")
348
+ else:
349
+ c = mk(entry, "warn", f"{entry}: {pdetail}; {cfg}")
350
+ elif entry == "absent":
351
+ hint = f"sibyl setup {wirer.name}"
352
+ c = mk("missing", "warn", f"missing: no sibyl-memory entry; to add it run: {hint}",
353
+ hint=hint)
354
+ elif entry == "present" and probe.get("broken"):
355
+ c = mk("broken", "fail", f"broken: {pdetail or 'the entry does not work'}; {cfg}",
356
+ fixable=bool(probe.get("fixable", True)))
357
+ elif entry == "present" and cmd is None:
358
+ c = mk("ok", "pass", pdetail or "wired")
359
+ elif entry == "present" and not S._command_resolves(cmd, strict=True):
360
+ why = "does not exist" if os.path.isabs(cmd) else "is not on PATH"
361
+ c = mk("stale", "fail", f"stale: {cmd} {why}; {cfg}", fixable=True)
362
+ elif entry == "present":
363
+ path = _abs_command(cmd) or cmd
364
+ if not S._is_our_command(path):
365
+ # Doctor only ever starts a command named sibyl-memory-mcp*.
366
+ c = mk("foreign", "warn", f"foreign: the entry runs another command; {cfg}")
367
+ c.command = None # never a foreign command string in the output
368
+ else:
369
+ if path not in verified:
370
+ verified[path] = bool(S._verify_mcp_starts(path)[0])
371
+ if not verified[path]:
372
+ mine = S.resolve_mcp_binary()
373
+ alt = bool(mine and os.path.abspath(mine) != os.path.abspath(path))
374
+ if alt and mine not in verified:
375
+ verified[mine] = bool(S._verify_mcp_starts(mine)[0])
376
+ c = mk("broken", "fail", f"broken: {cmd} does not start; {cfg}",
377
+ fixable=bool(alt and verified.get(mine)))
378
+ else:
379
+ notes = []
380
+ mine = S.resolve_mcp_binary()
381
+ if mine and os.path.abspath(mine) != os.path.abspath(path):
382
+ notes.append("uses a different install than this CLI")
383
+ if not os.path.isabs(cmd):
384
+ notes.append("relies on PATH")
385
+ c = mk("ok", "pass", "; ".join([f"wired; {cmd}"] + notes))
386
+ else:
387
+ c = mk("unreadable", "warn", f"unreadable: unknown probe result; {cfg}")
388
+ # Nothing to fix by hand: customized entries, and no installed server to
389
+ # point at (Hermes broken excepted: its repair installs the plugin).
390
+ if c.fixable and probe.get("customized"):
391
+ c.fixable = False
392
+ c.detail += f" ({pdetail})" if pdetail else (
393
+ " (entry has custom env or args; update the path by hand)")
394
+ if c.fixable and S.resolve_mcp_binary() is None and not (
395
+ wirer.name == "hermes" and c.status == "broken"):
396
+ c.fixable = False
397
+ if c.status in ("stale", "broken") and not c.fixable and wirer.name == "claude-code" \
398
+ and probe.get("customized"):
399
+ binpath = S.mcp_command_path()
400
+ c.detail = (f"{c.status}: entry has custom env or args; update the path by hand: "
401
+ f"claude mcp remove -s user sibyl-memory, then claude mcp add --scope user "
402
+ f"sibyl-memory -- {binpath} with your settings")
403
+ return c
404
+
405
+
406
+ def find_legacy_backups() -> list:
407
+ """Timestamped .bak files that sibyl versions before 0.7.0 wrote beside
408
+ harness configs. Listed only: never opened, moved or deleted."""
409
+ from . import setup as S
410
+ out = []
411
+ for name, cls in S.ALL_WIRERS.items():
412
+ if name == "deepseek":
413
+ continue # it never wrote one
414
+ try:
415
+ w = cls()
416
+ except Exception:
417
+ continue
418
+ cfg = getattr(w, "settings_path", None) if name == "claude-code" else getattr(w, "config_path", None)
419
+ if cfg is None:
420
+ continue
421
+ cfg = Path(cfg)
422
+ pat = re.compile(r"^" + re.escape(cfg.name) + r"\.\d{8}T\d{6}Z\.bak$")
423
+ try:
424
+ for f in cfg.parent.iterdir():
425
+ if pat.match(f.name):
426
+ out.append(str(f.absolute()))
427
+ except OSError:
428
+ continue
429
+ return sorted(set(out))
430
+
431
+
432
+ # `doctor --harness` names that check another harness's file: Grok Bot is
433
+ # wired into the Cursor file (sibyl setup grokbot), so its check is Cursor's.
434
+ DOCTOR_ALIASES: dict = {"grokbot": "cursor"}
435
+
436
+
437
+ def run_harness_checks(only: list, verified: dict) -> list:
438
+ """[(wirer, probe, check)] for each detected harness (default paths;
439
+ Grok Bot is the Cursor file, so it is not checked twice)."""
440
+ from . import setup as S
441
+ rows = []
442
+ for name, cls in S.ALL_WIRERS.items():
443
+ if only and name not in only:
444
+ continue
445
+ try:
446
+ w = cls()
447
+ present = w.is_present()
448
+ except Exception:
449
+ continue
450
+ if not present:
451
+ if only:
452
+ rows.append((w, None, HarnessCheck(name, w.display_name, "", "ok", "pass", None,
453
+ str(getattr(w, "config_path", "") or ""),
454
+ "not detected", False)))
455
+ continue
456
+ try:
457
+ probes = w.doctor_probe()
458
+ except Exception as e: # doctor_probe never raises; belt and braces
459
+ probes = [{"entry": "unreadable", "command": None, "location": "",
460
+ "config_path": str(getattr(w, "config_path", "")), "detail": type(e).__name__}]
461
+ for pr in probes:
462
+ rows.append((w, pr, check_harness(w, pr, verified=verified)))
463
+ return rows
464
+
465
+
466
+ def repair_check(wirer: Any, probe: dict, check: HarnessCheck, verified: dict) -> tuple:
467
+ """Repair one check. Every repair runs with stdout captured (the Hermes
468
+ plugin installer prints a banner; under --json that would break the
469
+ document). Returns (new check, outcome or None)."""
470
+ buf = io.StringIO()
471
+ try:
472
+ with contextlib.redirect_stdout(buf):
473
+ out = wirer.repair_mcp(probe)
474
+ except Exception as e:
475
+ check.fixed = False
476
+ check.fix_message = f"repair failed ({type(e).__name__})"
477
+ return check, None
478
+ try:
479
+ with contextlib.redirect_stdout(buf):
480
+ probes = wirer.doctor_probe()
481
+ except Exception:
482
+ probes = []
483
+ same = [p for p in probes if (p.get("location") or "") == (probe.get("location") or "")]
484
+ newp = same[0] if same else (probes[0] if probes else probe)
485
+ new = check_harness(wirer, newp, verified=verified)
486
+ new.fixed = new.status == "ok"
487
+ if not new.fixed:
488
+ # A repair that did not take fails the run whatever the entry is now
489
+ # (a failed Claude Code re-add leaves it unregistered: "missing").
490
+ new.level = "fail"
491
+ new.fixable = False
492
+ text = str(out.message or "")
493
+ block = getattr(out, "manual_block", None)
494
+ if block and text.endswith(block):
495
+ # Panel fix 8: the paste-by-hand block keeps its line breaks; only the
496
+ # lead sentence is folded onto the FAIL line.
497
+ text = text[:-len(block)]
498
+ new.fix_block = block
499
+ msg = " ".join(text.split())
500
+ if out.backup_path:
501
+ msg += f"; backup at {out.backup_path}"
502
+ new.fix_message = msg
503
+ return new, out
504
+
505
+
506
+ def _prompt_for(wirer: Any, check: HarnessCheck) -> str:
507
+ from . import setup as S
508
+ newp = S.mcp_command_path()
509
+ if wirer.name == "hermes":
510
+ return (f"Repair Hermes? (installs the Sibyl plugin into {wirer.plugin_dir}; "
511
+ "config.yaml is not changed)")
512
+ if wirer.name == "claude-code":
513
+ return ("Repair Claude Code? (removes the sibyl-memory registration and adds it again "
514
+ f"with {newp})")
515
+ return (f"Repair {check.display_name}{_loc_suffix(check.location)}? "
516
+ f"(points it at {newp}; a backup is kept)")
517
+
518
+
519
+ def _doctor_handoff(steps: list, server_cmd: Optional[list], checks: list, repairs: list) -> tuple:
520
+ """(next, human, later) by the rules of spec 5.5, first match wins.
521
+ ``repairs``: [(check after repair, outcome or None)]."""
522
+ from . import setup as S
523
+ later = tuple(dict.fromkeys(c.hint for c in checks if c.status == "missing" and c.hint))
524
+ if not all(s.ok for s in steps):
525
+ if any("sign-in required" in (s.detail or "") for s in steps):
526
+ return "sibyl init", None, later
527
+ if server_cmd is None:
528
+ nxt, human, _l = S._binary_missing_handoff("doctor")
529
+ return nxt, human, later + (("sibyl doctor",) if nxt != "done" else ())
530
+ return "done", "run sibyl-memory-mcp in a terminal and tell me the first error line", later
531
+ for c, out in repairs:
532
+ if not c.fixed:
533
+ if out is not None and out.handoff:
534
+ nxt, human, more = out.handoff
535
+ return nxt, human, later + tuple(more or ())
536
+ why = " ".join((c.fix_message or c.detail or "an error").split())[:200]
537
+ return "done", f"{c.display_name} wiring could not be repaired ({why})", later
538
+ if any(c.fixable and c.level == "fail" for c in checks):
539
+ return "sibyl doctor --fix", None, later
540
+ for c in checks:
541
+ if c.level == "fail":
542
+ return "done", f"{c.config_path} needs fixing by hand ({c.detail})", later
543
+ fixed = [c for c, _o in repairs if c.fixed]
544
+ if fixed:
545
+ asks = list(dict.fromkeys(S._RESTART_HUMAN.get(c.name, f"restart {c.display_name}")
546
+ for c in fixed))
547
+ return "done", "; ".join(asks), later
548
+ return "done", None, later
549
+
550
+
551
+ def _check_line(c: HarnessCheck) -> str:
552
+ who = f"{c.display_name}{_loc_suffix(c.location)}"
553
+ if c.fixed:
554
+ return a.success_line(f"FIXED {who} ({c.fix_message})")
555
+ if c.level == "pass":
556
+ return a.success_line(f"PASS {who} ({c.detail})")
557
+ if c.level == "warn":
558
+ return a.warn_line(f"WARN {who} ({c.detail})")
559
+ line = f"FAIL {who} ({c.detail})"
560
+ if c.fix_message:
561
+ line += f" not fixed: {c.fix_message}"
562
+ if c.fix_block:
563
+ # Column 0, unstyled, so it can be pasted as it is.
564
+ return a.err_line(line) + "\n" + c.fix_block
565
+ return a.err_line(line)
566
+
567
+
568
+ def _print_harness_report(checks: list, legacy: list) -> None:
569
+ print()
570
+ print("Harnesses")
571
+ if not checks:
572
+ print(a.dim(" none detected (sibyl setup wires one)"))
573
+ for c in checks:
574
+ print(_check_line(c))
575
+ if legacy:
576
+ print(a.dim(f" INFO {len(legacy)} backup file{'s' if len(legacy) != 1 else ''} from "
577
+ "older sibyl versions sit beside harness configs (not removed):"))
578
+ for p in legacy:
579
+ print(a.dim(f" {p}"))
580
+
581
+
582
+ def run_doctor(args: Any) -> int:
583
+ from . import _handoff as _h
584
+ from . import setup as S
585
+ db_path = Path(getattr(args, "db", None) or "~/.sibyl-memory/memory.db").expanduser()
586
+ cred_path = Path(getattr(args, "credentials", None) or "~/.sibyl-memory/credentials.json").expanduser()
587
+ as_json = bool(getattr(args, "json", False))
588
+ fix = bool(getattr(args, "fix", False))
589
+ only = [DOCTOR_ALIASES.get(n, S.SETUP_ALIASES.get(n, n))
590
+ for n in (getattr(args, "harness", None) or [])]
591
+ no_harness = bool(getattr(args, "no_harness", False))
592
+ cmd = _server_cmd()
593
+ if cmd is None:
594
+ steps = [Step("start server", False, "sibyl-memory-mcp not found. Run: pip install sibyl-memory-mcp")]
595
+ else:
596
+ steps = run_checks(server_cmd=cmd, db_path=db_path, cred_path=cred_path)
597
+ server_ok = all(s.ok for s in steps)
598
+
599
+ verified: dict = {}
600
+ if cmd is not None and any(s.name == "start server" and s.ok for s in steps):
601
+ verified[os.path.abspath(cmd[0])] = True
602
+ rows: list = []
603
+ legacy: list = []
604
+ if not no_harness:
605
+ rows = run_harness_checks(only, verified)
606
+ legacy = find_legacy_backups()
607
+
608
+ def checks() -> list:
609
+ return [c for _w, _p, c in rows]
610
+
611
+ wants = [i for i, (_w, p, c) in enumerate(rows) if c.fixable and p is not None]
612
+ prompted = False
613
+ repairs: list = []
614
+ if wants and fix:
615
+ to_fix = wants
616
+ elif wants and not as_json and sys.stdin.isatty() and sys.stdout.isatty():
617
+ prompted = True
618
+ _print_steps(steps)
619
+ _print_harness_report(checks(), legacy)
620
+ print()
621
+ to_fix = [i for i in wants
622
+ if S._interactive_prompt(_prompt_for(rows[i][0], rows[i][2]), default="N") == "y"]
623
+ else:
624
+ to_fix = []
625
+ attempted, fixed_ids = [], []
626
+ for i in to_fix:
627
+ w, p, c = rows[i]
628
+ new, out = repair_check(w, p, c, verified)
629
+ rows[i] = (w, p, new)
630
+ repairs.append((new, out))
631
+ ident = w.name + (f":{c.location}" if c.location else "")
632
+ attempted.append(ident)
633
+ if new.fixed:
634
+ fixed_ids.append(ident)
635
+
636
+ all_checks = checks()
637
+ harness_fail = any(c.level == "fail" and not c.fixed for c in all_checks)
638
+ ok = server_ok and not harness_fail
639
+ nxt, human, later = _doctor_handoff(steps, cmd, all_checks, repairs)
640
+
641
+ if as_json:
642
+ payload = {
643
+ "ok": ok,
644
+ "server_ok": server_ok,
645
+ "steps": [s.__dict__ for s in steps],
646
+ "harnesses": [asdict(c) for c in all_checks],
647
+ "fix": {"requested": fix, "attempted": attempted, "fixed": fixed_ids},
648
+ "legacy_backups": {"count": len(legacy), "paths": legacy},
649
+ }
650
+ _h.json_handoff(payload, nxt, human)
651
+ payload["later"] = list(later)
652
+ print(json.dumps(payload, indent=2))
653
+ return 0 if ok else 1
654
+
655
+ if prompted:
656
+ if repairs:
657
+ print()
658
+ for c, _o in repairs:
659
+ print(_check_line(c))
660
+ else:
661
+ _print_steps(steps)
662
+ if not no_harness:
663
+ _print_harness_report(all_checks, legacy)
664
+ print()
665
+ warned = any(c.level == "warn" for c in all_checks)
666
+ if not ok:
667
+ print(a.err_line("Doctor: some steps failed."))
668
+ elif warned:
669
+ print(a.warn_line("Doctor: passed with warnings."))
670
+ else:
671
+ print(a.success_line("Doctor: all steps passed."))
672
+ print()
673
+ _h.handoff(nxt, human=human, later=later)
674
+ return 0 if ok else 1
675
+
676
+
677
+ def _print_steps(steps: list) -> None:
678
+ print()
679
+ for s in steps:
680
+ mark = "PASS" if s.ok else ("SKIP" if s.skipped else "FAIL")
681
+ line = f"{mark} {s.name}" + (f" ({s.detail})" if s.detail else "")
682
+ print(a.success_line(line) if s.ok else a.err_line(line))
sibyl-memory-cli/src/sibyl_memory_cli/hooks.py ADDED
@@ -0,0 +1,502 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """`sibyl hook <event>`: the Claude Code hooks (spec plugin-save-debloat 5.2).
2
+
3
+ Installed by `sibyl setup` into ~/.claude/settings.json; not for manual use.
4
+ Each call reads the hook JSON from stdin (bounded), always exits 0, prints at
5
+ most one JSON object on stdout, and logs one short line (event and outcome,
6
+ never content) to ~/.sibyl-memory/lifecycle.log. A failure never blocks a
7
+ session: it degrades to printing nothing.
8
+
9
+ Output contract, verified against Claude Code 2.1.283's hook schemas (the
10
+ binary's zod definitions; see the release notes):
11
+
12
+ * SessionStart / UserPromptSubmit add context with
13
+ ``{"hookSpecificOutput": {"hookEventName": "<event>", "additionalContext": "<text>"}}``;
14
+ * Stop continues the session with ``{"decision": "block", "reason": "<text>"}``
15
+ (``decision`` is ``"approve" | "block"``); the re-entry carries
16
+ ``stop_hook_active: true`` and gets nothing.
17
+
18
+ Free tier: reminders only (the debloat FYI and the unsaved-last-session line
19
+ at start, the save-due line on a prompt). Pro (a verified fresh/stale
20
+ entitlement whose tier is paid, never a file hint): the start runs the debloat
21
+ plan under the person's policy and reports one line, and names up to three
22
+ relevant skill proposals (read-only, at most once a day); Stop asks the model
23
+ to run the save procedure headless by ACTIVE time (R1, plan 2.2): once early
24
+ (the first turn end after 5 memory writes, or after a compaction of THIS
25
+ session; the write count is the account's, plan D6.5), then after
26
+ every interval of active work (default 60 minutes; `sibyl autosave`), never
27
+ more than 8 times a session or 12 a day, and only when there is something to
28
+ save (Stop fires at every turn end, not only at the end of a session). Active
29
+ time: every SessionStart, UserPromptSubmit, Stop and PreCompact adds the time
30
+ since the previous event, capped at 5 minutes, except the model's own turn
31
+ (from a prompt to its Stop), capped at 30 minutes. A scripted `claude -p` run is
32
+ never continued (no transcript, or fewer than two prompts in the session).
33
+ Each continuation carries its sequence number ("save 2 of this session"), so
34
+ the transcript guard applies per request; a request is recorded (per-session
35
+ and per-day caps, the interval) only when it is actually emitted. PreCompact
36
+ and SessionEnd write the session capsule.
37
+
38
+ Skill signals (R2, Pro): Stop also reads the transcript INCREMENTALLY from the
39
+ session's stored byte offset (at most 4 MiB per Stop) and records each
40
+ tool_use block's name and the hashed, sorted key names of its input in
41
+ ~/.sibyl-memory/signals.json; values and text are never kept. The learner
42
+ never runs in a hook: the next MCP server start turns the record into
43
+ proposals.
44
+
45
+ Time bound (Claude Code kills a hook at its timeout, 5 s): nothing in a hook
46
+ touches the network. The Pro client's entitlement gate never refreshes, its
47
+ usage heartbeat is off (the exit flush would wait on the network), and a
48
+ memory write (a trim's history, a capsule) happens only when the cap gate can
49
+ decide it locally (a fresh tier cache) and within ``WRITE_BUDGET_SECONDS`` of
50
+ the hook's start; otherwise the start only plans and the write waits for a
51
+ later start or the MCP server. Measured: see the release notes.
52
+
53
+ Fast path: this module imports only the standard library. A hook first reads
54
+ the payload, the credentials and the UNVERIFIED tier claim in
55
+ entitlement.json; when that claim is not a paid tier the device cannot be Pro
56
+ (the verified tier is that same claim), so Stop returns at once and
57
+ PreCompact / SessionEnd record their counters without verifying the token or
58
+ opening the memory database. A claim that says paid is always verified.
59
+ """
60
+ from __future__ import annotations
61
+
62
+ import base64
63
+ import json
64
+ import os
65
+ import sys
66
+ import time
67
+ from pathlib import Path
68
+ from typing import Any
69
+
70
+ MAX_STDIN_BYTES = 1024 * 1024
71
+ MAX_TRANSCRIPT_SCAN = 64 * 1024 * 1024
72
+ STOP_REASON_BASE = ("Sibyl Memory Pro auto-save: read ~/.sibyl-memory/skills/SAVE.md and run it in "
73
+ "headless mode now (ask nothing, skip skill extraction, queue decisions)")
74
+ # A scripted run (`claude -p`) has one prompt: never continue a session with
75
+ # fewer prompts than this.
76
+ MIN_PROMPTS_FOR_STOP = 2
77
+
78
+
79
+ def stop_reason(seq: int) -> str:
80
+ """The Stop continuation for the ``seq``-th automatic save of a session."""
81
+ return f"{STOP_REASON_BASE} (save {int(seq)} of this session). Then stop."
82
+
83
+
84
+ STOP_REASON = stop_reason(1)
85
+ EVENTS = {"session-start": "SessionStart", "prompt": "UserPromptSubmit", "stop": "Stop",
86
+ "pre-compact": "PreCompact", "session-end": "SessionEnd"}
87
+ # A memory write starts only this long after the hook started (the harness
88
+ # kills the hook at 5 s; the write itself is local and takes milliseconds).
89
+ WRITE_BUDGET_SECONDS = 2.5
90
+ # Mirrors sibyl_memory_client.tiers.PAID_TIERS (kept literal so the fast path
91
+ # imports nothing); test_f11_paid_tier_literal_matches_the_client asserts
92
+ # equality; edit both. Canonical paid tiers pro + elite, then the legacy aliases.
93
+ PAID_TIERS = frozenset({"pro", "elite", "sync", "team", "lifetime", "stake", "enterprise"})
94
+ ENTITLEMENT_FILENAME = "entitlement.json"
95
+
96
+
97
+ def _paths(home: Path | None) -> tuple[Path, Path, Path]:
98
+ home = home or Path.home()
99
+ cred = Path(os.environ.get("SIBYL_CREDENTIALS") or (home / ".sibyl-memory" / "credentials.json"))
100
+ db = Path(os.environ.get("SIBYL_MEMORY_DB") or (home / ".sibyl-memory" / "memory.db"))
101
+ return home, cred.expanduser(), db.expanduser()
102
+
103
+
104
+ def _read_creds(path: Path) -> dict[str, Any]:
105
+ try:
106
+ if path.is_symlink() or not path.is_file() or path.stat().st_size > 64 * 1024:
107
+ return {}
108
+ raw = json.loads(path.read_text(encoding="utf-8"))
109
+ return raw if isinstance(raw, dict) else {}
110
+ except (OSError, ValueError):
111
+ return {}
112
+
113
+
114
+ def _transcript_has(path: Any, needle: str) -> bool:
115
+ """True when the session transcript already carries ``needle`` (our
116
+ continuation reason with its sequence number): a second guard beside
117
+ lifecycle.json, so each numbered request is made at most once even if that
118
+ file was rewritten."""
119
+ if not isinstance(path, str) or not path:
120
+ return False
121
+ p = Path(path)
122
+ try:
123
+ if p.is_symlink() or not p.is_file():
124
+ return False
125
+ b = needle.encode("utf-8")
126
+ seen = 0
127
+ tail = b""
128
+ with open(p, "rb") as fh:
129
+ while seen < MAX_TRANSCRIPT_SCAN:
130
+ chunk = fh.read(1024 * 1024)
131
+ if not chunk:
132
+ return False
133
+ seen += len(chunk)
134
+ if b in tail + chunk:
135
+ return True
136
+ tail = chunk[-len(b):]
137
+ except OSError:
138
+ return False
139
+ return False
140
+
141
+
142
+ def _context(event_name: str, lines: list[str]) -> str:
143
+ if not lines:
144
+ return ""
145
+ return json.dumps({"hookSpecificOutput": {"hookEventName": event_name,
146
+ "additionalContext": "\n".join(lines)}})
147
+
148
+
149
+ def claim_label(cred: Path) -> str | None:
150
+ """The UNVERIFIED tier label of the entitlement next to ``cred``, stripped
151
+ and lowercased; None when there is no readable SE1 token or no string
152
+ label. Standard library only (no signature check, no client import)."""
153
+ try:
154
+ p = Path(cred).parent / ENTITLEMENT_FILENAME
155
+ if p.is_symlink() or not p.is_file() or p.stat().st_size > 64 * 1024:
156
+ return None
157
+ token = json.loads(p.read_text(encoding="utf-8")).get("token")
158
+ if not isinstance(token, str):
159
+ return None
160
+ parts = token.split(".")
161
+ if len(parts) != 3 or parts[0] != "SE1":
162
+ return None
163
+ seg = parts[1] + "=" * (-len(parts[1]) % 4)
164
+ claim = json.loads(base64.urlsafe_b64decode(seg.encode("ascii")))
165
+ if not isinstance(claim, dict) or not isinstance(claim.get("tier"), str):
166
+ return None
167
+ return claim["tier"].strip().lower()
168
+ except (OSError, ValueError, UnicodeError, AttributeError):
169
+ return None
170
+
171
+
172
+ def claims_paid(cred: Path) -> bool:
173
+ """The UNVERIFIED tier claim of the entitlement next to ``cred`` is a paid
174
+ tier. Standard library only (no signature check, no client import). False
175
+ means the device cannot be Pro: the verified tier is this same claim. True
176
+ means nothing until the gate has verified the token."""
177
+ return claim_label(cred) in PAID_TIERS
178
+
179
+
180
+ def _pro_client(db: Path, cred: Path, creds: dict[str, Any], tenant: str):
181
+ """The gated client a Pro hook writes through, bounded for a hook: its
182
+ entitlement gate never refreshes (no network, no thread) and its usage
183
+ heartbeat is off (its exit flush would wait on the network)."""
184
+ from sibyl_memory_client import MemoryClient
185
+ from sibyl_memory_client._entitlement import EntitlementGate
186
+ from sibyl_memory_client._heartbeat import _NullHeartbeat
187
+ db.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
188
+ client = MemoryClient.local(str(db), tenant_id=tenant, account_id=creds.get("account_id"),
189
+ session_token=creds.get("session_token"),
190
+ tier=creds.get("tier", "free"), credentials_path=cred,
191
+ entitlement_gate=EntitlementGate(cred, allow_refresh=False))
192
+ client._heartbeat = _NullHeartbeat()
193
+ return client
194
+
195
+
196
+ def _local_write_ok(client: Any, delta: int = 0) -> bool:
197
+ gate = getattr(client, "_cap_gate", None)
198
+ try:
199
+ return bool(gate is not None and gate.decides_locally(delta))
200
+ except Exception:
201
+ return False
202
+
203
+
204
+ def _payload(stdin_text: str) -> dict[str, Any] | None:
205
+ try:
206
+ payload = json.loads(stdin_text) if stdin_text.strip() else None
207
+ except ValueError:
208
+ return None
209
+ return payload if isinstance(payload, dict) else None
210
+
211
+
212
+ def run_hook(event: str, stdin_text: str, *, home: Path | None = None, now: float | None = None,
213
+ started: float | None = None) -> str:
214
+ """The hook's stdout ('' for nothing). Never raises. ``started`` is the
215
+ ``time.monotonic()`` of the process start (the write budget counts from
216
+ it; default: now)."""
217
+ t0 = time.monotonic() if started is None else started
218
+ home, cred, db = _paths(home)
219
+ paid_claim = True
220
+ try:
221
+ paid_claim = claims_paid(cred)
222
+ if event == "stop":
223
+ payload = _payload(stdin_text)
224
+ if payload is not None:
225
+ if payload.get("stop_hook_active") is True:
226
+ return "" # the re-entry after our own continuation: never loop
227
+ if not paid_claim:
228
+ return "" # free: Stop does nothing (no import, no verify, no DB)
229
+ except Exception:
230
+ paid_claim = True # unsure: take the verified path
231
+ try:
232
+ return _run(event, stdin_text, home, cred, db, time.time() if now is None else now,
233
+ t0, paid_claim)
234
+ except Exception as e:
235
+ try:
236
+ from sibyl_memory_client.lifecycle import state as ST
237
+ ST.log(f"hook {event}: error {type(e).__name__}", home)
238
+ except Exception:
239
+ pass
240
+ return ""
241
+
242
+
243
+ def main_hook(event: str) -> int:
244
+ """`sibyl hook <event>` as a process: bounded stdin, one write to stdout,
245
+ exit 0 always."""
246
+ t0 = time.monotonic()
247
+ try:
248
+ raw = sys.stdin.buffer.read(MAX_STDIN_BYTES + 1) if not sys.stdin.isatty() else b""
249
+ text = raw[:MAX_STDIN_BYTES].decode("utf-8", "replace")
250
+ except Exception:
251
+ text = ""
252
+ out = run_hook(event, text, started=t0)
253
+ if out:
254
+ try:
255
+ sys.stdout.write(out + "\n")
256
+ sys.stdout.flush()
257
+ except Exception:
258
+ pass
259
+ return 0
260
+
261
+
262
+ def _run(event: str, stdin_text: str, home: Path, cred: Path, db: Path, now: float,
263
+ t0: float, paid_claim: bool) -> str:
264
+ from sibyl_memory_client.lifecycle import capsule as C
265
+ from sibyl_memory_client.lifecycle import reminders as R
266
+ from sibyl_memory_client.lifecycle import state as ST
267
+
268
+ if event not in EVENTS:
269
+ ST.log(f"hook {event}: unknown event", home)
270
+ return ""
271
+ payload = _payload(stdin_text)
272
+ if payload is None:
273
+ ST.log(f"hook {event}: malformed input", home)
274
+ return ""
275
+ creds = _read_creds(cred)
276
+ tenant = (creds.get("tenant_id") or creds.get("account_id") or "")
277
+ if not isinstance(tenant, str) or not tenant:
278
+ ST.log(f"hook {event}: no account", home)
279
+ return ""
280
+ if event == "stop" and payload.get("stop_hook_active") is True:
281
+ return "" # the re-entry after our own continuation: never loop
282
+ if paid_claim:
283
+ from sibyl_memory_client.lifecycle.entitled import automation_allowed_for_credentials
284
+ pro, why = automation_allowed_for_credentials(cred)
285
+ if why == "tier_unknown":
286
+ # The signed label is not one this version knows: treated as Free.
287
+ # Logged so a support ticket can be diagnosed without the token.
288
+ ST.log(f"hook {event}: tier_unknown (access label not recognised, treated as free)", home)
289
+ else:
290
+ pro, why = False, "free"
291
+ label = claim_label(cred)
292
+ if label and label != "free":
293
+ # Not free and not a paid label this version knows (claims_paid
294
+ # said no): treated as Free; the reason goes to lifecycle.log.
295
+ why = "tier_unknown"
296
+ ST.log(f"hook {event}: tier_unknown (access label not recognised, treated as free)", home)
297
+ sk = ST.session_key(payload.get("session_id"))
298
+ cwd = payload.get("cwd") if isinstance(payload.get("cwd"), str) else os.getcwd()
299
+ store = ST.LifecycleState(home)
300
+ # The save marker lives in memory.db. A free PreCompact / SessionEnd does
301
+ # not need it (the next start or prompt folds it in), so it opens nothing.
302
+ need_marker = pro or event in ("session-start", "prompt")
303
+ marker = ST.read_save_marker(db, tenant) if need_marker else None
304
+
305
+ def _budget_left() -> bool:
306
+ return time.monotonic() - t0 < WRITE_BUDGET_SECONDS
307
+
308
+ def _session(st: dict[str, Any]) -> dict[str, Any]:
309
+ s = ST.ensure_session(st, sk, tenant_id=tenant, harness="claude-code", now=now)
310
+ if marker is not None and s.get("started_at") is not None and marker >= s["started_at"]:
311
+ s["saved"] = True
312
+ return s
313
+
314
+ if event == "session-start":
315
+ tier_class = "paid" if pro else ("free" if why == "free" else None)
316
+
317
+ def _start(st: dict[str, Any]) -> list[str]:
318
+ ST.observe_marker(st, tenant, marker)
319
+ s = _session(st)
320
+ ST.add_active(s, now, kind="start")
321
+ out = []
322
+ line = R.tier_change_line(st, tenant, tier_class)
323
+ if line:
324
+ out.append(line)
325
+ line = R.unsaved_session_line(st, tenant, now, exclude_session=sk)
326
+ if line:
327
+ out.append(line)
328
+ return out
329
+ lines = store.update(_start)
330
+ if pro:
331
+ try:
332
+ from sibyl_memory_client.lifecycle.runner import run_automatic
333
+ client = _pro_client(db, cred, creds, tenant)
334
+ local = _local_write_ok(client, 64 * 1024)
335
+ rep = run_automatic(client, home=home, cwd=Path(cwd), harness="claude-code", now=now,
336
+ allow_apply=local, deadline=t0 + WRITE_BUDGET_SECONDS)
337
+ if rep.line and R.reports_enabled(store.load()):
338
+ lines.append(rep.line)
339
+ ST.log(f"hook session-start: pro run {rep.reason}"
340
+ f"{'' if local else ' (plan only: no fresh tier cache)'}", home)
341
+ except Exception as e:
342
+ ST.log(f"hook session-start: pro run failed {type(e).__name__}", home)
343
+ pending = ST.read_pending_count(db, tenant)
344
+ pl = R.pending_line(pending)
345
+ if pl and R.enabled(store.load()):
346
+ lines.append(pl)
347
+ # R1 (plan 3.2): relevant skill proposals, named, read-only.
348
+ from sibyl_memory_client.lifecycle import proposals as PR
349
+ st0 = store.load()
350
+ s0 = st0.get("sessions", {}).get(sk) or {}
351
+ anchor = PR.last_session_start(st0, tenant, exclude=sk, before=s0.get("started_at") or now)
352
+ names, total = PR.read_relevant(db, tenant, now, anchor=anchor,
353
+ muted=PR.muted_kinds(st0, now))
354
+ if total:
355
+ sl = store.update(lambda st: PR.skill_prompt(st, tenant, sk, now, names, total))
356
+ if sl:
357
+ lines.append(sl)
358
+ else:
359
+ from sibyl_memory_client.lifecycle.runner import measure_for_reminder
360
+ rec = measure_for_reminder(home, Path(cwd))
361
+ if rec is not None:
362
+ line = store.update(lambda st: R.debloat_reminder(st, tenant, now, rec, pro=False))
363
+ if line:
364
+ lines.append(line)
365
+ ST.log(f"hook session-start: {len(lines)} line(s), {'pro' if pro else why}", home)
366
+ return _context("SessionStart", lines)
367
+
368
+ if event == "prompt":
369
+ def _prompt(st: dict[str, Any]) -> str | None:
370
+ ST.observe_marker(st, tenant, marker)
371
+ s = _session(st)
372
+ ST.add_active(s, now, kind="prompt")
373
+ s["prompts"] = int(s.get("prompts") or 0) + 1
374
+ if pro:
375
+ return None # Pro: the prompt only counts active time
376
+ return R.save_reminder(st, tenant, now, pro=False, sk=sk)
377
+ line = store.update(_prompt)
378
+ return _context("UserPromptSubmit", [line] if line else [])
379
+
380
+ if event == "pre-compact":
381
+ def _pre(st: dict[str, Any]) -> dict[str, Any]:
382
+ ST.observe_marker(st, tenant, marker)
383
+ s = _session(st)
384
+ in_turn = s.get("last_event_kind") in ("prompt", "compact")
385
+ ST.add_active(s, now, kind="compact",
386
+ cap=ST.TURN_CAP_SECONDS if in_turn else ST.IDLE_CAP_SECONDS)
387
+ s["compactions"] = int(s.get("compactions") or 0) + 1
388
+ # This session's compaction (another session's never makes this
389
+ # one due); cleared by the next save.
390
+ s["compaction_seen"] = True
391
+ t = ST.tenant(st, tenant)
392
+ return dict(s, writes=max(0, int(t.get("writes_total") or 0) - int(s.get("writes_at_start") or 0)))
393
+ s = store.update(_pre)
394
+ if pro:
395
+ cap = C.build_capsule(harness="claude-code", session_id=payload.get("session_id"),
396
+ started_at=s.get("started_at"), ended_at=None, turns=None,
397
+ memory_writes=s.get("writes", 0), saved_by_skill=bool(s.get("saved")),
398
+ cwd=cwd)
399
+ ev, why_not = _write_capsule(C, db, cred, creds, tenant, cap, _budget_left)
400
+ if ev:
401
+ store.update(lambda st: _session(st).update(capsule_written=True, capsule_at=now))
402
+ ST.log(f"hook pre-compact: capsule {'written' if ev else 'not written' + why_not}", home)
403
+ return ""
404
+
405
+ if event == "stop":
406
+ if not pro:
407
+ return ""
408
+ # R2 (spec plugin-paid-tier-r2 1.2): skill signals from the Claude Code
409
+ # workflow. The transcript is read from this session's stored offset,
410
+ # at most 4 MiB per Stop; only each tool_use block's name and the
411
+ # hashed sorted key names of its input are kept (signals.json), the
412
+ # parsed text is dropped. Local only; never the learner here.
413
+ try:
414
+ from sibyl_memory_client.lifecycle import signals as SG
415
+ srep = SG.record_transcript(home, sk, payload.get("transcript_path"), tenant_id=tenant, now=now)
416
+ if srep.get("events"):
417
+ ST.log(f"hook stop: signals {srep['events']} tool events", home)
418
+ except Exception as e:
419
+ ST.log(f"hook stop: signals skipped {type(e).__name__}", home)
420
+ scripted = not (isinstance(payload.get("transcript_path"), str) and payload["transcript_path"])
421
+
422
+ def _stop(st: dict[str, Any]) -> tuple[int, str] | None:
423
+ # Decides only; the request is recorded (caps, interval) once it is
424
+ # actually emitted, after the transcript guard below.
425
+ ST.observe_marker(st, tenant, marker)
426
+ s = _session(st)
427
+ # The model worked from the prompt to this turn end: that gap is
428
+ # active (bounded); a gap after a turn end is the person's pause.
429
+ in_turn = s.get("last_event_kind") in ("prompt", "compact")
430
+ ST.add_active(s, now, kind="stop",
431
+ cap=ST.TURN_CAP_SECONDS if in_turn else ST.IDLE_CAP_SECONDS)
432
+ if scripted or int(s.get("prompts") or 0) < MIN_PROMPTS_FOR_STOP:
433
+ return None # a `claude -p` run: never continued
434
+ why_due = R.autosave_due(st, tenant, sk, now)
435
+ if why_due is None:
436
+ return None
437
+ return ST.next_nudge_seq(s), why_due
438
+ got = store.update(_stop)
439
+ if not got:
440
+ ST.log("hook stop: pass", home)
441
+ return ""
442
+ seq, why_due = got
443
+ reason = stop_reason(seq)
444
+ if _transcript_has(payload.get("transcript_path"), reason):
445
+ # This numbered request is already in the transcript (the state
446
+ # lost it): not asked again and not counted; the next one is
447
+ # numbered past it.
448
+ store.update(lambda st: ST.note_seq_seen(st, tenant, sk, seq, now=now,
449
+ harness="claude-code"))
450
+ ST.log(f"hook stop: pass (request {seq} already in the transcript)", home)
451
+ return ""
452
+
453
+ def _record(st: dict[str, Any]) -> int | None:
454
+ s = _session(st)
455
+ if ST.next_nudge_seq(s) != seq or R.autosave_due(st, tenant, sk, now) is None:
456
+ return None # another hook recorded a request, or a save landed, meanwhile
457
+ return ST.record_nudge(st, tenant, sk, now, harness="claude-code")
458
+ if store.update(_record) != seq:
459
+ ST.log("hook stop: pass (recorded elsewhere)", home)
460
+ return ""
461
+ ST.log(f"hook stop: continue {seq} ({why_due})", home)
462
+ return json.dumps({"decision": "block", "reason": reason})
463
+
464
+ # session-end
465
+ def _end(st: dict[str, Any]) -> dict[str, Any]:
466
+ ST.observe_marker(st, tenant, marker)
467
+ s = _session(st)
468
+ t = ST.tenant(st, tenant)
469
+ s["ended_at"] = now
470
+ s["writes"] = max(0, int(t.get("writes_total") or 0) - int(s.get("writes_at_start") or 0))
471
+ last_save = t.get("last_save_at")
472
+ need = (not s.get("capsule_at")) or (last_save is not None and s["capsule_at"] <= last_save)
473
+ return dict(s, need_capsule=need)
474
+ s = store.update(_end)
475
+ if pro and s.get("need_capsule"):
476
+ cap = C.build_capsule(harness="claude-code", session_id=payload.get("session_id"),
477
+ started_at=s.get("started_at"), ended_at=now, turns=None,
478
+ memory_writes=s.get("writes", 0), saved_by_skill=bool(s.get("saved")),
479
+ cwd=cwd)
480
+ ev, why_not = _write_capsule(C, db, cred, creds, tenant, cap, _budget_left)
481
+ if ev:
482
+ store.update(lambda st: _session(st).update(capsule_written=True, capsule_at=now))
483
+ ST.log(f"hook session-end: capsule {'written' if ev else 'not written' + why_not}", home)
484
+ else:
485
+ ST.log("hook session-end: recorded", home)
486
+ return ""
487
+
488
+
489
+ def _write_capsule(C: Any, db: Path, cred: Path, creds: dict[str, Any], tenant: str,
490
+ cap: dict[str, Any], budget_left: Any) -> tuple[Any, str]:
491
+ """(event id or None, why not). Writes only when the cap gate decides
492
+ locally and the hook is inside its write budget."""
493
+ if not budget_left():
494
+ return None, " (out of time)"
495
+ client = _pro_client(db, cred, creds, tenant)
496
+ if not _local_write_ok(client, 4096):
497
+ return None, " (no fresh tier cache; a later hook or the MCP server writes it)"
498
+ return C.write_capsule(client, cap), ""
499
+
500
+
501
+ __all__ = ["EVENTS", "MIN_PROMPTS_FOR_STOP", "PAID_TIERS", "STOP_REASON", "STOP_REASON_BASE",
502
+ "WRITE_BUDGET_SECONDS", "claim_label", "claims_paid", "main_hook", "run_hook", "stop_reason"]
sibyl-memory-cli/src/sibyl_memory_cli/lifecycle_cli.py ADDED
@@ -0,0 +1,1233 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """`sibyl save`, `sibyl debloat`, `sibyl skills`, `sibyl reminders`, `sibyl hook`
2
+ and the `lifecycle` rows of `sibyl status` (spec plugin-save-debloat 4.3, 6.3,
3
+ 7.1). The procedures themselves live in sibyl-memory-client (``skills``,
4
+ ``lifecycle``); this module is the terminal surface.
5
+
6
+ Naming (spec 0.1): the plugin's step is "the debloat step" / "context trim";
7
+ "automatic debloat on Pro". Nothing here prints a token or file content (a
8
+ plan shows section headings and token counts only).
9
+ """
10
+ from __future__ import annotations
11
+
12
+ import argparse
13
+ import hashlib
14
+ import json
15
+ import os
16
+ import re
17
+ import shlex
18
+ import sys
19
+ import time
20
+ from pathlib import Path
21
+ from typing import Any
22
+
23
+ from . import _aesthetic as a
24
+ from . import _handoff as _h
25
+
26
+
27
+ # ----------------------------------------------------------------------
28
+ # helpers
29
+ # ----------------------------------------------------------------------
30
+
31
+ def _home() -> Path:
32
+ return Path.home()
33
+
34
+
35
+ def _cred(args: argparse.Namespace) -> Path:
36
+ from .cli import DEFAULT_CRED_PATH
37
+ return Path(getattr(args, "credentials", None) or DEFAULT_CRED_PATH).expanduser()
38
+
39
+
40
+ def _db(args: argparse.Namespace) -> Path:
41
+ from .cli import DEFAULT_DB_PATH
42
+ return Path(getattr(args, "db", None) or DEFAULT_DB_PATH).expanduser()
43
+
44
+
45
+ def _creds(args: argparse.Namespace) -> dict[str, Any]:
46
+ from .cli import read_credentials
47
+ return read_credentials(_cred(args)) or {}
48
+
49
+
50
+ def _tenant(creds: dict[str, Any]) -> str | None:
51
+ return (creds.get("tenant_id") or creds.get("account_id") or None)
52
+
53
+
54
+ def _client(args: argparse.Namespace):
55
+ """The gated client an agent would use (the account gate applies)."""
56
+ from sibyl_memory_client import DEFAULT_TENANT, MemoryClient
57
+ creds = _creds(args)
58
+ db = _db(args)
59
+ db.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
60
+ client = MemoryClient.local(str(db), tenant_id=_tenant(creds) or DEFAULT_TENANT,
61
+ account_id=creds.get("account_id"),
62
+ session_token=creds.get("session_token"),
63
+ tier=creds.get("tier", "free"), credentials_path=_cred(args))
64
+ client.enable_lifecycle_counting(_home()) # `sibyl save --fact` counts like an agent write
65
+ return client
66
+
67
+
68
+ def _pro(args: argparse.Namespace) -> tuple[bool, str]:
69
+ from sibyl_memory_client.lifecycle.entitled import automation_allowed_for_credentials
70
+ return automation_allowed_for_credentials(_cred(args))
71
+
72
+
73
+ # The question `_ask` could not put because there is no terminal (row G1):
74
+ # the caller's handoff relays it and names the same command with --yes.
75
+ _NI_QUESTION: str | None = None
76
+
77
+
78
+ def _ask(question: str, *, yes: bool) -> bool:
79
+ global _NI_QUESTION
80
+ _NI_QUESTION = None
81
+ if yes:
82
+ return True
83
+ if not sys.stdin.isatty():
84
+ print(a.dim(" Not a terminal: re-run with --yes to confirm."))
85
+ _NI_QUESTION = question
86
+ return False
87
+ try:
88
+ return input(f"{question} [y/N]: ").strip().lower() in ("y", "yes")
89
+ except EOFError:
90
+ _NI_QUESTION = question
91
+ return False
92
+
93
+
94
+ def _declined(command: str) -> None:
95
+ """Handoff after `_ask` said no: the same command with --yes and the
96
+ question relayed when there was no terminal (G1), else done (G2)."""
97
+ if _NI_QUESTION:
98
+ _h.handoff(f"{command} --yes", human=_NI_QUESTION)
99
+ else:
100
+ _h.handoff("done")
101
+
102
+
103
+ def _entitlement_handoff(e: BaseException, *, later: tuple = ()) -> None:
104
+ nxt, human = _h.from_exception(e, default="sibyl init")
105
+ _h.handoff(nxt, human=human, later=later)
106
+
107
+
108
+ def _fmt_ts(ts: Any) -> str:
109
+ if not isinstance(ts, (int, float)) or isinstance(ts, bool):
110
+ return "never"
111
+ from ._timefmt import utc_minute
112
+ return utc_minute(ts) or "never"
113
+
114
+
115
+ def _slug(text: str) -> str:
116
+ s = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")[:60].strip("-")
117
+ return s or ("fact-" + hashlib.sha256(text.encode("utf-8")).hexdigest()[:8])
118
+
119
+
120
+ # ----------------------------------------------------------------------
121
+ # sibyl save
122
+ # ----------------------------------------------------------------------
123
+
124
+ THREE_WAYS = (
125
+ "Saving a session is a distillation, so your agent does it with the save procedure:",
126
+ " Claude Code /sibyl-save (installed by sibyl setup)",
127
+ " any MCP host the `save` prompt on the sibyl-memory server (/mcp__sibyl-memory__save)",
128
+ " Codex, Hermes ask the agent to follow ~/.sibyl-memory/skills/SAVE.md",
129
+ "From a terminal: sibyl save --fact \"<one fact>\" writes one fact; sibyl save --status shows the last save.",
130
+ "On Pro, your agent is asked to save by itself: once early (after 5 memory writes or a compaction), "
131
+ "then about every hour of active work (sibyl autosave sets the interval or turns it off).",
132
+ )
133
+
134
+
135
+ def cmd_save(args: argparse.Namespace) -> int:
136
+ from sibyl_memory_client.lifecycle import state as ST
137
+ print()
138
+ if getattr(args, "status", False):
139
+ creds = _creds(args)
140
+ tid = _tenant(creds)
141
+ st = ST.LifecycleState(_home()).load()
142
+ t = st.get("tenants", {}).get(tid or "", {}) if tid else {}
143
+ marker = ST.read_save_marker(_db(args), tid) if tid else None
144
+ last = max([x for x in (marker, t.get("last_save_at")) if isinstance(x, (int, float))], default=None)
145
+ print(a.eyebrow("save"))
146
+ print(a.kv("last save", _fmt_ts(last)))
147
+ print(a.kv("writes since", str(int(t.get("writes_since_save") or 0))))
148
+ pend = ST.read_pending_count(_db(args), tid) if tid else 0
149
+ print(a.kv("to decide", f"{pend} item(s) queued by a headless save" if pend else "nothing queued"))
150
+ _h.handoff("done")
151
+ return 0
152
+ fact = getattr(args, "fact", None)
153
+ if fact is not None:
154
+ text = fact.strip()
155
+ if not text:
156
+ print(a.warn_line("Nothing to save: the fact is empty."))
157
+ _h.handoff('sibyl save --fact "<fact>"', human="the fact to save")
158
+ return 1
159
+ slug = _slug(text)
160
+ if getattr(args, "preview", False):
161
+ print(a.dim(f"would write fact/{slug} (nothing written)"))
162
+ _h.handoff("done")
163
+ return 0
164
+ from sibyl_memory_client import EntitlementError
165
+ from sibyl_memory_client.exceptions import CapExceededError
166
+ try:
167
+ c = _client(args)
168
+ c.set_entity("fact", slug, {"value": text,
169
+ "saved_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())})
170
+ except CapExceededError as e:
171
+ # Finding 5.3.2 (handoff spec 2026-10-03): the free cap used to
172
+ # escape as a traceback. Its first line, then the handoff.
173
+ print(a.warn_line(str(e).splitlines()[0] if str(e) else "The free 5 MB memory cap is full."))
174
+ print(a.dim(" Nothing was written."))
175
+ _h.handoff("done", later=("sibyl upgrade",))
176
+ return 1
177
+ except EntitlementError as e:
178
+ print(a.warn_line(str(e).splitlines()[0]))
179
+ print(a.dim(" Sign in first: sibyl init. Nothing was written."))
180
+ _entitlement_handoff(e, later=(f"sibyl save --fact {shlex.quote(text)}",))
181
+ return 1
182
+ print(a.success_line(f"Saved fact/{slug}."))
183
+ print(a.dim(f" recall it with: sibyl memory recall fact {slug}"))
184
+ _h.handoff("done")
185
+ return 0
186
+ if getattr(args, "capsule", False):
187
+ ok, _why = _pro(args)
188
+ if not ok:
189
+ print(a.dim("Automatic save is on Pro. Nothing was written."))
190
+ print(a.dim(" On the free plan run the save procedure yourself (sibyl save shows how)."))
191
+ _h.handoff("sibyl save", later=("sibyl upgrade",))
192
+ return 0
193
+ if getattr(args, "preview", False):
194
+ print(a.dim("would write one session capsule (counts only) (nothing written)"))
195
+ _h.handoff("done")
196
+ return 0
197
+ from sibyl_memory_client.lifecycle import capsule as C
198
+ cap = C.build_capsule(harness="cli", session_id=f"cli-{time.time()}", started_at=None,
199
+ ended_at=time.time(), turns=None, memory_writes=0,
200
+ saved_by_skill=False, cwd=Path.cwd())
201
+ ev = C.write_capsule(_client(args), cap)
202
+ print(a.success_line("Session capsule written.") if ev else a.warn_line("Capsule not written."))
203
+ _h.handoff("done" if ev else "sibyl status")
204
+ return 0 if ev else 1
205
+ for ln in THREE_WAYS:
206
+ print(ln if not ln.startswith(" ") else a.dim(ln))
207
+ if getattr(args, "preview", False):
208
+ print(a.dim("(preview: nothing was written)"))
209
+ _h.handoff("done")
210
+ return 0
211
+
212
+
213
+ # ----------------------------------------------------------------------
214
+ # sibyl debloat
215
+ # ----------------------------------------------------------------------
216
+
217
+ def _root(args: argparse.Namespace) -> Path:
218
+ """The project root, as its real path (``--root`` given through a symlink
219
+ names the same files, the same authorisations and the same backups as
220
+ the real folder)."""
221
+ return Path(os.path.realpath(str(Path(getattr(args, "root", None) or Path.cwd()).expanduser())))
222
+
223
+
224
+ def _measure(args: argparse.Namespace) -> dict[str, Any]:
225
+ from sibyl_memory_client.lifecycle import measure as M
226
+ from sibyl_memory_client.lifecycle import policy as P
227
+ pol = P.load(_home())
228
+ root = _root(args)
229
+ return M.measure(root, home=_home(), config_path=getattr(args, "config", None),
230
+ includes=getattr(args, "include", None) or [], surface=pol.get("surface"),
231
+ thresholds=pol.get("thresholds"), per_file_soft=pol.get("perFileSoft"),
232
+ write_journal=True)
233
+
234
+
235
+ def _candidates(args: argparse.Namespace):
236
+ from sibyl_memory_client.lifecycle import apply as A
237
+ from sibyl_memory_client.lifecycle import policy as P
238
+ pol = P.load(_home())
239
+ root = _root(args)
240
+ cands, rec = A.candidates(_home(), root, pol)
241
+ return cands, rec, pol, root
242
+
243
+
244
+ def _plans(args: argparse.Namespace) -> list[dict[str, Any]]:
245
+ from sibyl_memory_client.lifecycle import apply as A
246
+ cands, _rec, pol, _root = _candidates(args)
247
+ out = []
248
+ for c in cands:
249
+ if not c.trimmable:
250
+ out.append({"file": c.label, "trimmable": False, "reason": c.why_not})
251
+ continue
252
+ pl, reason = A.plan(c, pol)
253
+ d = {"file": c.label, "trimmable": True, "reason": reason}
254
+ if pl is not None:
255
+ d.update({"safe": pl.safe, "sections": pl.sections, "tok_before": pl.tok_before,
256
+ "tok_history": pl.tok_history, "tok_after": pl.tok_after})
257
+ out.append(d)
258
+ return out
259
+
260
+
261
+ def _legacy_notice() -> None:
262
+ """Once: an earlier build stored automatic trims by file NAME; those
263
+ entries are dropped (never guessed at) and the person is told."""
264
+ try:
265
+ from sibyl_memory_client.lifecycle import policy as P
266
+ line = P.take_legacy_notice(_home())
267
+ except Exception:
268
+ line = None
269
+ if line:
270
+ print(a.warn_line(line))
271
+
272
+
273
+ def cmd_debloat(args: argparse.Namespace) -> int:
274
+ action = getattr(args, "action", None)
275
+ if action is not None or not (getattr(args, "json", False) or getattr(args, "fyi", False)):
276
+ _legacy_notice()
277
+ try:
278
+ if action is None:
279
+ return _debloat_measure(args)
280
+ if action == "plan":
281
+ return _debloat_plan(args)
282
+ if action == "apply":
283
+ return _debloat_apply(args)
284
+ if action in ("auto", "manual"):
285
+ return _debloat_auto(args, action == "auto")
286
+ if action == "undo":
287
+ return _debloat_undo(args)
288
+ except KeyboardInterrupt:
289
+ raise
290
+ except Exception as e: # the measurement always exits 0; actions report
291
+ print(a.warn_line(f"debloat: {type(e).__name__}: {e}"))
292
+ if not (action is None and getattr(args, "fyi", False)) and not getattr(args, "json", False):
293
+ _h.handoff("done" if action is None else "sibyl debloat plan")
294
+ return 0 if action is None else 1
295
+ return 0
296
+
297
+
298
+ def _debloat_measure(args: argparse.Namespace) -> int:
299
+ from sibyl_memory_client.lifecycle import measure as M
300
+ from sibyl_memory_client.lifecycle import policy as P
301
+ rec = _measure(args)
302
+ if rec.get("config_error"):
303
+ print(rec["config_error"] + " (defaults used)", file=sys.stderr)
304
+ heavy_next = "sibyl debloat plan" if any(f.get("heavy") for f in rec.get("files") or []) else "done"
305
+ if getattr(args, "json", False):
306
+ out = M.public_record(rec)
307
+ if P.policy_path(_home()).exists():
308
+ out["plan"] = _plans(args)
309
+ print(json.dumps(_h.json_handoff(out, heavy_next, None), indent=2))
310
+ return 0
311
+ if getattr(args, "fyi", False):
312
+ # The one-line FYI is a startup-line format (like --json, one shape):
313
+ # no handoff block.
314
+ if not rec["files"]:
315
+ print("context: no always-load files found")
316
+ else:
317
+ print(M.fyi(rec))
318
+ return 0
319
+ print(M.report(rec))
320
+ _h.handoff(heavy_next)
321
+ return 0
322
+
323
+
324
+ def _debloat_plan(args: argparse.Namespace) -> int:
325
+ plans = _plans(args)
326
+ print()
327
+ if not plans:
328
+ print(a.dim("No instruction files found for this project or your home."))
329
+ _h.handoff("done")
330
+ return 0
331
+ print(a.eyebrow("context trim plan (nothing is changed)"))
332
+ for p in plans:
333
+ if not p.get("trimmable"):
334
+ print(a.kv(p["file"], f"not trimmed: {p['reason']}"))
335
+ elif p.get("safe"):
336
+ secs = ", ".join(p["sections"][:5]) + (" ..." if len(p["sections"]) > 5 else "")
337
+ print(a.kv(p["file"], f"{p['tok_before']} -> {p['tok_after']} tok; would move "
338
+ f"{len(p['sections'])} section(s): {secs}"))
339
+ else:
340
+ print(a.kv(p["file"], p.get("reason") or "nothing to move"))
341
+ print()
342
+ print(a.dim("Apply one with: sibyl debloat apply <file> (asks first; a verified backup is made)"))
343
+ if any(p.get("trimmable") and p.get("safe") for p in plans):
344
+ _h.handoff("sibyl debloat apply <file>",
345
+ human="which file to trim (it asks before writing; a verified backup is made)")
346
+ else:
347
+ _h.handoff("done")
348
+ return 0
349
+
350
+
351
+ def _debloat_apply(args: argparse.Namespace) -> int:
352
+ from sibyl_memory_client.lifecycle import apply as A
353
+ from sibyl_memory_client.lifecycle import policy as P
354
+ from sibyl_memory_client.lifecycle import state as ST
355
+ cands, _rec, pol, root = _candidates(args)
356
+ want = getattr(args, "file", None)
357
+ surface = {c.label for c in cands}
358
+ chosen = [c for c in cands if c.trimmable and (want is None or want in (c.label, c.key))]
359
+ print()
360
+ if want is not None and not chosen:
361
+ print(a.warn_line(f"{want} is not a trimmable instruction file here."))
362
+ for c in cands:
363
+ if want in (c.label, c.key):
364
+ print(a.dim(f" {c.why_not}"))
365
+ _h.handoff("sibyl debloat plan")
366
+ return 1
367
+ pro, _tier = _pro(args)
368
+ destination = pol["destination"] if pro else "sibling"
369
+ client = _client(args) if pro else None # free: no client is constructed for the write
370
+ results = []
371
+ ids: dict[str, str] = {}
372
+ ni_question = None
373
+ declined = False
374
+ for c in chosen:
375
+ pl, reason = A.plan(c, pol)
376
+ if pl is None or not pl.safe:
377
+ print(a.kv(c.label, reason or "nothing to move"))
378
+ continue
379
+ where = ("Sibyl Memory (a reference document) plus a sibling file" if destination == "memory+sibling"
380
+ else "Sibyl Memory (a reference document)" if destination == "memory"
381
+ else f"{A.sibling_path(c.path).name} beside it")
382
+ q = (f"Move {len(pl.sections)} history section(s) of {c.label} ({pl.tok_history} tok) to "
383
+ f"{where}? A verified backup is made first")
384
+ if not _ask(q, yes=bool(getattr(args, "yes", False))):
385
+ print(a.dim(f" {c.label}: left as is."))
386
+ ni_question = ni_question or _NI_QUESTION
387
+ declined = True
388
+ continue
389
+ res = A.apply_one(c, home=_home(), cwd=root, destination=destination, client=client,
390
+ policy=pol, surface_labels=surface)
391
+ results.append(res)
392
+ ids[c.label] = P.auth_id(c.path, _home())
393
+ if res.applied:
394
+ dest = res.key or res.sibling
395
+ print(a.success_line(f"{c.label}: {res.tok_before} -> {res.tok_after} tok; history in {dest}."))
396
+ print(a.dim(f" backup: {res.backup} undo: sibyl debloat undo {shlex.quote(c.label)}"))
397
+ else:
398
+ print(a.warn_line(f"{c.label}: {res.reason}"))
399
+ if results:
400
+ def _upd(st: dict[str, Any]) -> None:
401
+ st.setdefault("debloat", {})["last_apply"] = {
402
+ "ts": time.time(), "results": [{"file": r.file, "id": ids.get(r.file),
403
+ "applied": r.applied,
404
+ "reason": r.reason, "key": r.key,
405
+ "backup": r.backup if r.applied else None}
406
+ for r in results]}
407
+ ST.LifecycleState(_home()).update(_upd)
408
+ if pol.get("journal"):
409
+ rec = _measure(args)
410
+ A.journal(_home(), {"ts": time.time(), "total_tok": rec["total_tok"], "weight": rec["weight"],
411
+ "targets": len(rec["targets"]),
412
+ "applied": len([r for r in results if r.applied])})
413
+ elif not chosen:
414
+ print(a.dim("Nothing to trim."))
415
+ applied = [r.file for r in results if r.applied]
416
+ if results and not all(r.applied for r in results):
417
+ _h.handoff("sibyl debloat plan", later=[f"sibyl debloat undo {shlex.quote(str(f))}" for f in applied])
418
+ elif ni_question and not applied:
419
+ _h.handoff("sibyl debloat apply" + (f" {shlex.quote(str(want))}" if want else "") + " --yes",
420
+ human=ni_question)
421
+ else:
422
+ _h.handoff("done", later=[f"sibyl debloat undo {shlex.quote(str(f))}" for f in applied])
423
+ return 0 if all(r.applied for r in results) else (1 if results else 0)
424
+
425
+
426
+ def _debloat_auto(args: argparse.Namespace, on: bool) -> int:
427
+ from sibyl_memory_client.lifecycle import policy as P
428
+ want = getattr(args, "file", None)
429
+ print()
430
+ if not want:
431
+ print(a.warn_line(f"Usage: sibyl debloat {'auto' if on else 'manual'} <file>"))
432
+ _h.handoff("sibyl debloat plan")
433
+ return 1
434
+ cands, _rec, pol, root = _candidates(args)
435
+ match = [c for c in cands if want in (c.label, c.key)]
436
+ if on:
437
+ if not match or not match[0].trimmable:
438
+ print(a.warn_line(f"{want} is not a trimmable instruction file here."))
439
+ _h.handoff("sibyl debloat plan")
440
+ return 1
441
+ c = match[0]
442
+ fid = P.auth_id(c.path, _home())
443
+ print(f"Automatic context trim for this file at {fid} means:")
444
+ print(a.dim(" at every agent start, Sibyl measures it and, when the deterministic splitter finds"))
445
+ print(a.dim(" accreted history (a sibyl:history region, a History/Changelog heading, dated sections"))
446
+ print(a.dim(f" older than {pol['history_after_days']} days with no open item), it moves that history"))
447
+ print(a.dim(" into Sibyl Memory (searchable), keeps a byte-verified backup, rewrites the file last"))
448
+ print(a.dim(" with a one-line pointer, and tells you in one line. Nothing is ever deleted."))
449
+ print(a.dim(" Only this file at this path: a file with the same name in another project, or in"))
450
+ print(a.dim(" your home, is not affected."))
451
+ print(a.dim(f" Take it back any time: sibyl debloat manual {shlex.quote(c.label)}. Undo a trim: sibyl debloat undo {shlex.quote(c.label)}."))
452
+ pro, _t = _pro(args)
453
+ if not pro:
454
+ print(a.dim(" Automatic trims run on Pro; this choice is kept for when they do."))
455
+ if not _ask(f"Let Sibyl trim this file at {fid} automatically?",
456
+ yes=bool(getattr(args, "yes", False))):
457
+ print(a.dim("Nothing changed."))
458
+ _declined(f"sibyl debloat auto {shlex.quote(str(want))}")
459
+ return 1
460
+ pol = P.set_auto(fid, True, _home())
461
+ print(a.success_line(f"{fid} is on automatic (mode {pol['mode']})."))
462
+ _h.handoff("done")
463
+ return 0
464
+ if match:
465
+ fid = P.auth_id(match[0].path, _home())
466
+ elif P.is_path_id(want):
467
+ fid = P.auth_id(P.id_path(want, _home()), _home())
468
+ else:
469
+ fid = P.auth_id(Path(root) / want, _home())
470
+ if fid not in P.load(_home())["auto_files"]:
471
+ print(a.dim(f"{fid} was not on automatic; nothing changed."))
472
+ _h.handoff("done")
473
+ return 0
474
+ pol = P.set_auto(fid, False, _home())
475
+ print(a.success_line(f"{fid} is back to manual (mode {pol['mode']})."))
476
+ _h.handoff("done")
477
+ return 0
478
+
479
+
480
+ def _debloat_undo(args: argparse.Namespace) -> int:
481
+ from sibyl_memory_client.lifecycle import apply as A
482
+ from sibyl_memory_client.lifecycle import policy as P
483
+ from sibyl_memory_client.lifecycle import state as ST
484
+ want = getattr(args, "file", None)
485
+ cands, _rec, _pol, root = _candidates(args)
486
+ last = ST.LifecycleState(_home()).load().get("debloat", {}).get("last_apply") or {}
487
+ done = [r for r in last.get("results", []) if isinstance(r, dict) and r.get("applied")]
488
+ # The last apply is matched on the FILE it trimmed (its auth_id), never on
489
+ # the bare label: `AGENTS.md` trimmed in one project is not this project's.
490
+ if want is None:
491
+ if not done:
492
+ print(a.dim("No trim to undo."))
493
+ _h.handoff("done")
494
+ return 0
495
+ rid = done[0].get("id")
496
+ if not isinstance(rid, str) or not P.is_path_id(rid):
497
+ print(a.dim(f"The last trim ({done[0].get('file')}) was recorded without its path; "
498
+ "name the file: sibyl debloat undo <file>"))
499
+ _h.handoff("sibyl debloat undo <file>", human="which file to restore (the last trim "
500
+ "was recorded without its path)")
501
+ return 1
502
+ match = [c for c in cands if P.auth_id(c.path, _home()) == rid]
503
+ if not match:
504
+ print(a.warn_line(f"The last trim was {rid}, which is not a file of this project or your "
505
+ "home here; run `sibyl debloat undo <file>` where it lives."))
506
+ _h.handoff("done", human=f"the last trim was {rid}; run sibyl debloat undo in that "
507
+ "project's folder")
508
+ return 1
509
+ want = match[0].label
510
+ else:
511
+ match = [c for c in cands if want in (c.label, c.key)]
512
+ path = match[0].path if match else ((_home() / want[2:]) if str(want).startswith("~/") else root / want)
513
+ fid = P.auth_id(path, _home())
514
+ # The backup the last apply of THIS file recorded (not merely the newest
515
+ # one, which an interrupted later attempt could have made identical to
516
+ # the file as it is now).
517
+ prefer = next((r.get("backup") for r in done if r.get("id") == fid and r.get("backup")), None)
518
+ print()
519
+ which = "the backup its last trim made" if prefer else "its most recent backup"
520
+ if not _ask(f"Restore {want} from {which}? (the current file is backed up first)",
521
+ yes=bool(getattr(args, "yes", False))):
522
+ print(a.dim("Nothing changed."))
523
+ _declined(f"sibyl debloat undo {shlex.quote(str(want))}")
524
+ return 1
525
+ ok, msg, _src = A.undo(path, home=_home(), cwd=root, prefer=prefer)
526
+ print(a.success_line(f"{want}: {msg}") if ok else a.warn_line(f"{want}: {msg}"))
527
+ if ok:
528
+ rec = _measure(args)
529
+ print(a.dim(f" context now ~{rec['total_tok']} tok ({rec['weight']})"))
530
+ _h.handoff("done" if ok else "sibyl debloat plan")
531
+ return 0 if ok else 1
532
+
533
+
534
+ # ----------------------------------------------------------------------
535
+ # sibyl skills
536
+ # ----------------------------------------------------------------------
537
+
538
+ def _present_wirers(args: argparse.Namespace) -> dict[str, Any]:
539
+ from .setup import ClaudeCodeWirer, CodexWirer, HermesWirer
540
+ out: dict[str, Any] = {}
541
+ cc = ClaudeCodeWirer()
542
+ if cc.settings_path.parent.exists():
543
+ out["claude-code"] = cc
544
+ cx = CodexWirer()
545
+ if cx.config_path.parent.exists():
546
+ out["codex"] = cx
547
+ hw = HermesWirer()
548
+ if hw.hermes_home.exists():
549
+ out["hermes"] = hw
550
+ return out
551
+
552
+
553
+ def cmd_skills(args: argparse.Namespace) -> int:
554
+ from sibyl_memory_client import skills as SK
555
+ from .setup import install_shims
556
+ op = getattr(args, "skills_cmd", None) or "status"
557
+ home = _home()
558
+ print()
559
+ if op == "proposals":
560
+ return _proposals(args)
561
+ if op == "signals":
562
+ return _signals(args)
563
+ if op == "install":
564
+ rep = SK.install(home, force=bool(getattr(args, "force", False)))
565
+ print(a.eyebrow(f"skills v{rep.version}"))
566
+ for n, s in rep.results.items():
567
+ print(a.kv(n, s))
568
+ for m in rep.messages:
569
+ print(a.dim(" " + m))
570
+ for name, w in _present_wirers(args).items():
571
+ lines = []
572
+ if name == "codex":
573
+ lines = w.wire_block() + install_shims(name, w.skill_shim_targets())
574
+ else:
575
+ lines = install_shims(name, w.skill_shim_targets())
576
+ for ln in lines:
577
+ print(a.dim(f" {name}: {ln}"))
578
+ _h.handoff("done" if rep.ok else "sibyl skills status")
579
+ return 0 if rep.ok else 1
580
+ if op == "reset":
581
+ name = getattr(args, "name", None)
582
+ if name not in SK.SKILL_NAMES:
583
+ print(a.warn_line(f"Usage: sibyl skills reset {{{'|'.join(SK.SKILL_NAMES)}}}"))
584
+ _h.handoff("sibyl skills status")
585
+ return 1
586
+ if not _ask(f"Replace {name} with the shipped version {SK.version()}? Your edits in it are lost "
587
+ "(copy them first if you want them)", yes=bool(getattr(args, "yes", False))):
588
+ print(a.dim("Nothing changed."))
589
+ _declined(f"sibyl skills reset {name}")
590
+ return 1
591
+ rep = SK.reset(home, name)
592
+ print(a.kv(name, rep.results.get(name, "?")))
593
+ _h.handoff("done" if rep.ok else "sibyl skills status")
594
+ return 0 if rep.ok else 1
595
+ if op == "uninstall":
596
+ if not _ask("Remove the save/debloat files, shims, hooks and the Codex block this plugin "
597
+ "installed? (edited files are kept)", yes=bool(getattr(args, "yes", False))):
598
+ print(a.dim("Nothing changed."))
599
+ _declined("sibyl skills uninstall")
600
+ return 1
601
+ for name, w in _present_wirers(args).items():
602
+ if name == "claude-code":
603
+ for ln in w.unwire_hooks():
604
+ print(a.dim(f" {name}: {ln}"))
605
+ if name == "codex":
606
+ for ln in w.unwire_block():
607
+ print(a.dim(f" {name}: {ln}"))
608
+ for k, v in SK.uninstall(home).items():
609
+ print(a.kv(Path(k).name if "/" in k else k, v))
610
+ _h.handoff("done")
611
+ return 0
612
+ # status
613
+ st = SK.status(home)
614
+ print(a.eyebrow("skills"))
615
+ if not st["exists"]:
616
+ print(a.kv("installed", "no · sibyl skills install (or sibyl setup)"))
617
+ print(a.kv("package", f"v{st['package_version']}"))
618
+ _h.handoff("sibyl skills install")
619
+ return 0
620
+ print(a.kv("version", f"v{st['installed_version'] or '?'} (package v{st['package_version']})"))
621
+ for n, info in st["files"].items():
622
+ extra = ""
623
+ if info.get("upstream_waiting"):
624
+ extra = f" · new version waiting: {', '.join(info['upstream_waiting'])} (sibyl skills reset {n})"
625
+ label = {"ok": "ok", "edited": "edited by you", "outdated": "outdated (sibyl skills install)",
626
+ "missing": "missing", "symlink": "a symlink (refused)", "oversize": "too large (refused)"}
627
+ print(a.kv(n, label.get(info["state"], info["state"]) + extra))
628
+ for p, info in st["shims"].items():
629
+ print(a.kv(info.get("harness") or "shim", f"{p} · {info['state']}"))
630
+ for name, w in _present_wirers(args).items():
631
+ if name == "claude-code":
632
+ hs = w.hooks_state()
633
+ print(a.kv("claude hooks", f"{hs['present']} of 5 wired" + (f" · settings.json {hs['error']}"
634
+ if hs["error"] else "")))
635
+ if name == "codex":
636
+ print(a.kv("codex block", "present" if w.block_state() else "absent"))
637
+ # Rows T2: an outdated file is reinstalled; a new version waiting behind
638
+ # a person's edit is their call.
639
+ files = st["files"]
640
+ waiting = [n for n, info in files.items() if info.get("upstream_waiting")]
641
+ if any(info["state"] in ("outdated", "missing") for info in files.values()):
642
+ _h.handoff("sibyl skills install")
643
+ elif waiting:
644
+ _h.handoff("done", later=[f"sibyl skills reset {n}" for n in waiting],
645
+ human=f"{', '.join(waiting)} {'was' if len(waiting) == 1 else 'were'} edited by you; "
646
+ "resetting replaces your edits")
647
+ else:
648
+ _h.handoff("done")
649
+ return 0
650
+
651
+
652
+ # ----------------------------------------------------------------------
653
+ # sibyl skills proposals (R1, plan 3.3): Pro, local, explicit accept only
654
+ # ----------------------------------------------------------------------
655
+
656
+ def _short_id(pid: str) -> str:
657
+ return str(pid or "")[:8]
658
+
659
+
660
+ def _skill_targets(args: argparse.Namespace, name: str) -> dict[str, Path]:
661
+ """Where an accepted skill goes: ``--to <dir>`` only, else every harness
662
+ folder present on this computer (Claude Code ~/.claude/skills, Codex
663
+ ~/.codex/skills, Hermes $HERMES_HOME/skills)."""
664
+ to = getattr(args, "to", None)
665
+ if to:
666
+ return {"dir": Path(to).expanduser() / name / "SKILL.md"}
667
+ out: dict[str, Path] = {}
668
+ for harness, w in _present_wirers(args).items():
669
+ if harness == "claude-code":
670
+ out[harness] = w.settings_path.parent / "skills" / name / "SKILL.md"
671
+ elif harness == "codex":
672
+ out[harness] = w.config_path.parent / "skills" / name / "SKILL.md"
673
+ elif harness == "hermes":
674
+ out[harness] = w.hermes_home / "skills" / name / "SKILL.md"
675
+ return out
676
+
677
+
678
+ def _find_proposal(learner: Any, ref: str | None) -> Any:
679
+ """A proposal by full id or a unique prefix of at least 6 characters."""
680
+ from sibyl_memory_client.exceptions import NotFoundError
681
+ ref = (ref or "").strip()
682
+ if not ref:
683
+ return None
684
+ try:
685
+ return learner.get_proposal(ref)
686
+ except NotFoundError:
687
+ pass
688
+ if len(ref) < 6:
689
+ return None
690
+ hits = []
691
+ for status in ("pending", "accepted", "rejected"):
692
+ hits += [p for p in learner.list_proposals(status=status, limit=500) if p.id.startswith(ref)]
693
+ return hits[0] if len(hits) == 1 else None
694
+
695
+
696
+ def _proposals(args: argparse.Namespace) -> int:
697
+ from sibyl_memory_client.exceptions import EntitlementError, TierGateError, ValidationError
698
+ from sibyl_memory_client.lifecycle import proposals as PR
699
+ from sibyl_memory_client.lifecycle import state as ST
700
+ action = getattr(args, "proposal_action", None) or "list"
701
+ target = getattr(args, "target", None)
702
+ now = time.time()
703
+ store = ST.LifecycleState(_home())
704
+ print(a.eyebrow("skill proposals"))
705
+ if action in ("mute", "unmute"):
706
+ # Local settings only; they apply on Pro, where proposals exist.
707
+ if not target:
708
+ print(a.warn_line(f"Usage: sibyl skills proposals {action} <kind>"
709
+ + (" | <slug>" if action == "unmute" else "")))
710
+ print(a.dim(" kinds: " + ", ".join(PR.KINDS)))
711
+ _h.handoff("sibyl skills proposals")
712
+ return 1
713
+ if action == "mute":
714
+ if target not in PR.KINDS:
715
+ print(a.warn_line(f"Unknown kind {target!r}. Kinds: {', '.join(PR.KINDS)}"))
716
+ _h.handoff("sibyl skills proposals")
717
+ return 1
718
+ days = getattr(args, "days", None) or PR.MUTE_DAYS_DEFAULT
719
+ if not (1 <= int(days) <= 365):
720
+ print(a.warn_line("--days must be between 1 and 365."))
721
+ _h.handoff("sibyl skills proposals")
722
+ return 1
723
+
724
+ def _mute(st: dict[str, Any]) -> None:
725
+ st.setdefault("skills", ST.default_skills()).setdefault("muted_kinds", {})[target] = \
726
+ now + int(days) * 86400
727
+ store.update(_mute)
728
+ print(a.kv("muted", f"{target} for {int(days)} days (nothing of this kind is proposed)"))
729
+ _h.handoff("done")
730
+ return 0
731
+
732
+ def _unmute(st: dict[str, Any]) -> str:
733
+ sk = st.setdefault("skills", ST.default_skills())
734
+ if target in PR.KINDS:
735
+ sk.setdefault("muted_kinds", {}).pop(target, None)
736
+ return f"{target}: proposed again"
737
+ sk.setdefault("unmuted", {})[target[:80]] = now
738
+ return f"{target[:80]}: may be proposed again (earlier rejections no longer count)"
739
+ print(a.kv("unmuted", store.update(_unmute)))
740
+ _h.handoff("done")
741
+ return 0
742
+ if not _creds(args):
743
+ print(a.warn_line("Not activated. Run `sibyl init`."))
744
+ print(a.dim(" Skill proposals are part of Pro; nothing is proposed without an account."))
745
+ _h.handoff("sibyl init")
746
+ return 0
747
+ client = _client(args)
748
+ try:
749
+ learner = client.learner()
750
+ except TierGateError:
751
+ print(a.kv("proposals", "on Pro · Sibyl proposes skills from your sessions; you decide"))
752
+ print(a.dim(" On the free plan, /sibyl-save still offers skills when you run it yourself."))
753
+ _h.handoff("done", later=("sibyl upgrade",))
754
+ return 0
755
+ except EntitlementError as e:
756
+ print(a.warn_line(str(e).splitlines()[0]))
757
+ _entitlement_handoff(e)
758
+ return 1
759
+ if action == "list":
760
+ st = store.load()
761
+ muted = PR.muted_kinds(st, now)
762
+ rows = learner.list_proposals(status="pending", limit=50)
763
+ if not rows:
764
+ print(a.kv("pending", "none"))
765
+ print(a.dim(" Sibyl proposes a skill when the same work recurs across your sessions."))
766
+ _h.handoff("done")
767
+ return 0
768
+ print(a.kv("pending", f"{len(rows)} · accept or reject: sibyl skills proposals accept|reject <id>"))
769
+ for p in rows:
770
+ ts = sorted(t for t in (ST._iso_to_epoch(e.get("ts")) for e in p.evidence
771
+ if isinstance(e, dict)) if t is not None)
772
+ seen = (f"{_fmt_ts(ts[0])} .. {_fmt_ts(ts[-1])}" if ts else "?")
773
+ flag = " · kind muted" if p.pattern_kind in muted else ""
774
+ print(a.kv(_short_id(p.id), f"{p.proposed_title or p.proposed_slug} · {p.pattern_kind} · "
775
+ f"confidence {p.confidence:.2f} · {len(p.evidence)} events · "
776
+ f"{seen}{flag}"))
777
+ _h.handoff("sibyl skills proposals show <id>",
778
+ human="which proposals to accept or reject (ids above; a skill file is written only "
779
+ "on accept)")
780
+ return 0
781
+ p = _find_proposal(learner, target)
782
+ if p is None:
783
+ print(a.warn_line(f"No proposal {target!r}. Run `sibyl skills proposals` for the ids."))
784
+ _h.handoff("sibyl skills proposals")
785
+ return 1
786
+ if action == "show":
787
+ print(a.kv("id", p.id))
788
+ print(a.kv("title", p.proposed_title or p.proposed_slug))
789
+ print(a.kv("kind", f"{p.pattern_kind} · confidence {p.confidence:.2f} · {len(p.evidence)} events"))
790
+ print(a.kv("status", p.status))
791
+ print()
792
+ print(p.proposed_body)
793
+ if p.status == "pending":
794
+ _h.handoff(f"sibyl skills proposals accept {_short_id(p.id)}",
795
+ later=(f"sibyl skills proposals reject {_short_id(p.id)}",),
796
+ human="accept this proposal (writes the skill file) or reject it; your call")
797
+ else:
798
+ _h.handoff("done")
799
+ return 0
800
+ if action == "reject":
801
+ if p.status != "pending":
802
+ print(a.warn_line(f"This proposal is {p.status}; only a pending one can be rejected."))
803
+ _h.handoff("sibyl skills proposals")
804
+ return 1
805
+ try:
806
+ client.reject_skill_proposal(p.id, note=getattr(args, "note", None))
807
+ except (ValidationError, EntitlementError) as e:
808
+ print(a.warn_line(str(e).splitlines()[0]))
809
+ if isinstance(e, EntitlementError):
810
+ _entitlement_handoff(e)
811
+ else:
812
+ _h.handoff("sibyl skills proposals")
813
+ return 1
814
+ print(a.kv("rejected", f"{p.proposed_slug} · not proposed again for {PR.COOL_OFF_DAYS} days; "
815
+ f"a second rejection mutes it (sibyl skills proposals unmute {p.proposed_slug})"))
816
+ _h.handoff("done")
817
+ return 0
818
+ # accept
819
+ if p.status == "rejected":
820
+ print(a.warn_line("This proposal was rejected. It is not proposed again for a while; "
821
+ f"unmute with sibyl skills proposals unmute {p.proposed_slug}."))
822
+ _h.handoff("done", later=(f"sibyl skills proposals unmute {p.proposed_slug}",))
823
+ return 1
824
+ if p.status == "pending":
825
+ try:
826
+ client.accept_skill_proposal(p.id, note=getattr(args, "note", None))
827
+ except (ValidationError, EntitlementError) as e:
828
+ print(a.warn_line(str(e).splitlines()[0]))
829
+ if isinstance(e, EntitlementError):
830
+ _entitlement_handoff(e)
831
+ else:
832
+ _h.handoff("sibyl skills proposals")
833
+ return 1
834
+ except Exception as e: # the cap gate (a free cap cannot apply on Pro, but never a traceback)
835
+ print(a.warn_line(f"Not accepted: {type(e).__name__}. Nothing was written."))
836
+ nxt, human = _h.from_exception(e, default="sibyl status")
837
+ _h.handoff(nxt, human=human)
838
+ return 1
839
+ print(a.kv("accepted", f"{p.proposed_slug} · reference copy in memory as skill/{p.proposed_slug}"))
840
+ else:
841
+ print(a.kv("accepted", f"{p.proposed_slug} (earlier) · writing its skill files again"))
842
+ from sibyl_memory_client import skills as SK
843
+ name = SK.skill_name(p.proposed_slug)
844
+ text = SK.proposal_skill_text(p)
845
+ problems = SK.validate_skill_text(text, name)
846
+ if problems:
847
+ print(a.warn_line("The skill file did not pass validation: " + "; ".join(problems)))
848
+ _h.handoff("done", human="this proposal's skill file did not pass validation (above); "
849
+ "reject it or write it by hand")
850
+ return 1
851
+ targets = _skill_targets(args, name)
852
+ rc = 0
853
+ for harness, path in targets.items():
854
+ st_ = SK.write_skill(_home(), path, text, harness=harness, slug=p.proposed_slug)
855
+ label = {"installed": "written", "unchanged": "already there", "updated": "updated",
856
+ "exists": "a different file is already there (kept; use --to <dir>)"}.get(st_, st_)
857
+ print(a.kv(harness, f"{path} · {label}"))
858
+ if st_.startswith("refused") or st_ == "exists":
859
+ rc = 1
860
+ if not targets:
861
+ print(a.dim(" No Claude Code, Codex or Hermes folder on this computer: the skill is in memory as "
862
+ f"skill/{p.proposed_slug}. Write the file with --to <dir>."))
863
+ if (_home() / ".cursor").exists():
864
+ print(a.dim(f" Cursor: no skill folder is written; the reference copy is skill/{p.proposed_slug}."))
865
+ if rc:
866
+ _h.handoff(f"sibyl skills proposals accept {_short_id(p.id)} --to <dir>",
867
+ human="a folder to write the skill file to (a different file is already in the "
868
+ "usual place)")
869
+ else:
870
+ _h.handoff("done")
871
+ return rc
872
+
873
+
874
+ # ----------------------------------------------------------------------
875
+ # sibyl skills signals (R2, spec plugin-paid-tier-r2 1.3): Pro, local only
876
+ # ----------------------------------------------------------------------
877
+
878
+ SIGNALS_PRO_LINE = "Skill signals are on Pro."
879
+
880
+
881
+ def _kb(n: Any) -> str:
882
+ return f"{(n or 0) / 1024:.1f} KB" if isinstance(n, int) else "none"
883
+
884
+
885
+ def _signals(args: argparse.Namespace) -> int:
886
+ """status | clear | off | on. Prints counts, size and dates, never an
887
+ entry. Off and clear work on any plan; on and the recording itself need a
888
+ verified paid entitlement."""
889
+ from sibyl_memory_client.lifecycle import signals as SG
890
+ action = getattr(args, "signals_action", None) or "status"
891
+ home = _home()
892
+ print(a.eyebrow("skill signals"))
893
+ pro, _why = _pro(args)
894
+ if action == "clear":
895
+ removed = SG.clear(home)
896
+ print(a.kv("cleared", "signals.json deleted" if removed else "nothing was recorded"))
897
+ print(a.dim(" Nothing recorded before now is kept or proposed."))
898
+ return 0
899
+ if action == "off":
900
+ SG.set_enabled(home, False)
901
+ print(a.kv("recording", "off · nothing new is recorded (sibyl skills signals on)"))
902
+ print(a.dim(" What is already recorded stays until it ages out; sibyl skills signals clear deletes it."))
903
+ return 0
904
+ if not pro:
905
+ print(a.kv("signals", SIGNALS_PRO_LINE))
906
+ if action == "status":
907
+ st = SG.status(home)
908
+ if st["exists"]:
909
+ print(a.dim(f" A file from an earlier Pro period is here ({_kb(st['bytes'])}); "
910
+ "sibyl skills signals clear deletes it."))
911
+ return 0
912
+ if action == "on":
913
+ SG.set_enabled(home, True)
914
+ print(a.kv("recording", "on · from now; nothing from while it was off is read back"))
915
+ return 0
916
+ st = SG.status(home)
917
+ print(a.kv("recording", ("on" if st["on"] else "off (sibyl skills signals on)")
918
+ + " · tool sequences and repeated entity rewrites, on this computer only"))
919
+ print(a.kv("file", f"~/.sibyl-memory/{SG.SIGNALS_NAME} · {_kb(st['bytes'])}" if st["exists"]
920
+ else "none yet"))
921
+ print(a.kv("sequences", str(st["ngrams"])))
922
+ print(a.kv("entities", f"{st['entity_keys']} ({st['entity_writes']} writes)"))
923
+ print(a.kv("oldest", _fmt_ts(st["oldest"])))
924
+ print(a.kv("newest", _fmt_ts(st["newest"])))
925
+ print(a.dim(" Tool and MCP server names are kept; argument names and entity names only as hashes; never a value."))
926
+ return 0
927
+
928
+
929
+ # ----------------------------------------------------------------------
930
+ # sibyl autosave (R1, plan 2.4)
931
+ # ----------------------------------------------------------------------
932
+
933
+ def _autosave_summary(st: dict[str, Any], tid: str | None, now: float) -> str:
934
+ from sibyl_memory_client.lifecycle import state as ST
935
+ cfg = ST.autosave_settings(st)
936
+ if not cfg["enabled"]:
937
+ return "off · sibyl autosave on"
938
+ parts = [f"every {cfg['interval_seconds'] // 60} min of active work"]
939
+ t = st.get("tenants", {}).get(tid or "", {}) if tid else {}
940
+ n = ST.nudges_today(t, now) if t else 0
941
+ parts.append(f"{n} save{'s' if n != 1 else ''} requested today")
942
+ last = t.get("last_nudge_at") if t else None
943
+ if isinstance(last, (int, float)):
944
+ from ._timefmt import utc_hm
945
+ parts.append("last " + (utc_hm(last) or "?"))
946
+ return " · ".join(parts)
947
+
948
+
949
+ def cmd_autosave(args: argparse.Namespace) -> int:
950
+ from sibyl_memory_client.lifecycle import state as ST
951
+ op = getattr(args, "action", None) or "status"
952
+ store = ST.LifecycleState(_home())
953
+ print()
954
+ if op == "every":
955
+ minutes = getattr(args, "minutes", None)
956
+ lo, hi = ST.AUTOSAVE_INTERVAL_MIN // 60, ST.AUTOSAVE_INTERVAL_MAX // 60
957
+ if minutes is None or not (lo <= int(minutes) <= hi):
958
+ print(a.warn_line(f"Usage: sibyl autosave every <minutes> ({lo} to {hi})."))
959
+ _h.handoff("sibyl autosave")
960
+ return 1
961
+
962
+ def _every(st: dict[str, Any]) -> None:
963
+ cfg = ST.autosave_settings(st)
964
+ cfg["interval_seconds"] = int(minutes) * 60
965
+ cfg["enabled"] = True
966
+ st["autosave"] = cfg
967
+ store.update(_every)
968
+ elif op in ("on", "off"):
969
+ def _onoff(st: dict[str, Any]) -> None:
970
+ cfg = ST.autosave_settings(st)
971
+ cfg["enabled"] = op == "on"
972
+ st["autosave"] = cfg
973
+ store.update(_onoff)
974
+ st = store.load()
975
+ tid = _tenant(_creds(args))
976
+ pro, _tier = _pro(args)
977
+ print(a.eyebrow("automatic save"))
978
+ print(a.kv("autosave", _autosave_summary(st, tid, time.time())))
979
+ cfg = ST.autosave_settings(st)
980
+ print(a.kv("rule", f"once early (after 5 memory writes or a compaction), then every "
981
+ f"{cfg['interval_seconds'] // 60} min of active work; at most "
982
+ f"{cfg['max_per_session']} a session and {cfg['max_per_day']} a day"))
983
+ if not pro:
984
+ print(a.kv("plan", "automatic save is on Pro · this setting applies the day you upgrade"))
985
+ if not st.get("reminders", True):
986
+ print(a.dim(" reminders are off (sibyl reminders on): nothing is requested meanwhile."))
987
+ print(a.dim(" Each automatic save is one extra model turn that reads and writes memory."))
988
+ _h.handoff("done", later=() if pro else ("sibyl upgrade",))
989
+ return 0
990
+
991
+
992
+ # ----------------------------------------------------------------------
993
+ # sibyl refresh (R1, plan 5.2): no new endpoint
994
+ # ----------------------------------------------------------------------
995
+
996
+ def _cap_label(cap: Any) -> str:
997
+ if cap is None:
998
+ return "none"
999
+ if isinstance(cap, int) and not isinstance(cap, bool):
1000
+ return f"{cap / (1024 * 1024):.0f} MB"
1001
+ return "?"
1002
+
1003
+
1004
+ def _devices_label(acct: Any) -> str | None:
1005
+ from sibyl_memory_client.exceptions import device_limit_info
1006
+ info = device_limit_info(acct)
1007
+ if info is None:
1008
+ return None
1009
+ lim = info["limit"]
1010
+ return f"{info['n']} of {lim}" if lim is not None else f"{info['n']} (no limit)"
1011
+
1012
+
1013
+ def _refresh_diff(before: dict[str, Any], after: dict[str, Any]) -> list[tuple[str, str]]:
1014
+ rows: list[tuple[str, str]] = []
1015
+ bt, at = before.get("tier"), after.get("tier")
1016
+ src = after.get("src")
1017
+ if bt != at:
1018
+ rows.append(("tier", f"{bt or 'none'} -> {at or 'none'}" + (f" ({src})" if isinstance(src, str) and src
1019
+ and src != at else "")))
1020
+ if "cap" in before or "cap" in after:
1021
+ bc, ac = before.get("cap", "?"), after.get("cap", "?")
1022
+ if bc != ac:
1023
+ rows.append(("cap", f"{_cap_label(bc)} -> {_cap_label(ac)}"))
1024
+ bd, ad = _devices_label(before.get("acct")), _devices_label(after.get("acct"))
1025
+ if ad is not None and bd != ad:
1026
+ rows.append(("computers", f"{bd} -> {ad}" if bd else ad))
1027
+ be = (before.get("acct") or {}).get("email_verified")
1028
+ ae = (after.get("acct") or {}).get("email_verified")
1029
+ if ae is True and be is not True:
1030
+ rows.append(("email", "verified"))
1031
+ if before.get("state") != after.get("state"):
1032
+ rows.append(("access", f"{before.get('state') or 'none'} -> {after.get('state') or 'none'}"))
1033
+ return rows
1034
+
1035
+
1036
+ def cmd_refresh(args: argparse.Namespace) -> int:
1037
+ """Check the account now (one /entitlement call), refresh the procedures,
1038
+ shims and hooks for this computer, and say what changed. Exits 0 with no
1039
+ account (it says what to do), 2 when the server could not be reached."""
1040
+ from . import _account_gate as G
1041
+ from sibyl_memory_client import skills as SK
1042
+ print()
1043
+ cred = _cred(args)
1044
+ creds = _creds(args)
1045
+ if not creds:
1046
+ print(a.warn_line("Not activated. Run `sibyl init`."))
1047
+ print(a.dim(" sibyl refresh picks up a plan change on a signed-in computer; nothing to refresh yet."))
1048
+ from . import cli as _cli
1049
+ _h.handoff(_cli._init_next())
1050
+ return 0
1051
+ print(a.eyebrow("account"))
1052
+ before = G.status_info(cred, refresh=False) or {}
1053
+ after = G.status_info(cred, refresh=True)
1054
+ rc = 0
1055
+ if after is None:
1056
+ print(a.kv("account", "sibyl-memory-client is not installed", value_color="warn"))
1057
+ _h.handoff("pip install -U sibyl-memory-client")
1058
+ return 2
1059
+ outcome = after.get("refreshed")
1060
+ nxt, human = G.access_handoff(after)
1061
+ if outcome in ("ok", "shared"):
1062
+ diff = _refresh_diff(before, after)
1063
+ for k, v in diff:
1064
+ print(a.kv(k, v, value_color="ok"))
1065
+ if not diff:
1066
+ print(a.kv("checked", f"no change · {after.get('tier') or 'no plan'} · "
1067
+ + G.access_row(after)))
1068
+ else:
1069
+ print(a.kv("access", G.access_row(after)))
1070
+ elif outcome == "denied":
1071
+ print(a.kv("access", G.access_row(after), value_color="err"))
1072
+ rc = 1
1073
+ elif after.get("refresh_code") == G.UNTRUSTED_BASE_CODE:
1074
+ # Follow-up D1: the sign-in was not sent (SIBYL_API_BASE is not a Sibyl
1075
+ # address). Not a network fault: no retry, no "connect".
1076
+ from . import cli as _cli
1077
+ _cli._note_untrusted_base(_cli.API_BASE)
1078
+ print(a.kv("account", G.UNTRUSTED_BASE_LINE, value_color="err"))
1079
+ print(a.kv("access", G.access_row(after)))
1080
+ rc = 1
1081
+ nxt, human = G.untrusted_base_handoff()
1082
+ else:
1083
+ print(a.kv("account", "could not reach the server; this is the last check-in", value_color="warn"))
1084
+ print(a.kv("access", G.access_row(after)))
1085
+ rc = 2
1086
+ nxt, human = _h.RETRY, "connect this computer to the internet once"
1087
+ dev = _devices_label(after.get("acct"))
1088
+ if dev:
1089
+ print(a.kv("computers", dev))
1090
+ print()
1091
+ print(a.eyebrow("this computer"))
1092
+ rep = SK.install(_home())
1093
+ print(a.kv("procedures", f"v{rep.version} " + ", ".join(f"{n} {st_}" for n, st_ in rep.results.items())))
1094
+ for m in rep.messages:
1095
+ print(a.dim(" " + m))
1096
+ from .setup import install_shims
1097
+ for name, w in _present_wirers(args).items():
1098
+ lines = install_shims(name, w.skill_shim_targets())
1099
+ if name == "codex":
1100
+ lines = w.wire_block() + lines
1101
+ if name == "claude-code" and w.hooks_state().get("present"):
1102
+ lines += w.wire_hooks() # refresh only hooks already wired (sibyl setup adds them)
1103
+ for ln in lines:
1104
+ print(a.dim(f" {name}: {ln}"))
1105
+ print(a.dim(" Hooks and shims are the same on every plan: Pro behaviour switches on because this "
1106
+ "computer's entitlement says so."))
1107
+ print(a.dim(" Running agents pick this up on their next call."))
1108
+ status_rows(args, creds)
1109
+ print()
1110
+ _h.handoff(nxt, human=human)
1111
+ return rc
1112
+
1113
+
1114
+ # ----------------------------------------------------------------------
1115
+ # sibyl reminders
1116
+ # ----------------------------------------------------------------------
1117
+
1118
+ def cmd_reminders(args: argparse.Namespace) -> int:
1119
+ from sibyl_memory_client.lifecycle import state as ST
1120
+ op = getattr(args, "state", None) or "status"
1121
+ store = ST.LifecycleState(_home())
1122
+ print()
1123
+ if op in ("on", "off", "quiet"):
1124
+ def _set(st: dict[str, Any]) -> None:
1125
+ if op == "on":
1126
+ st["reminders"], st["quiet"] = True, False
1127
+ elif op == "off":
1128
+ st["reminders"] = False
1129
+ else:
1130
+ st["reminders"], st["quiet"] = True, True
1131
+ store.update(_set)
1132
+ st = store.load()
1133
+ val = "off" if not st.get("reminders", True) else ("quiet (Pro reports silenced)" if st.get("quiet") else "on")
1134
+ print(a.kv("reminders", val))
1135
+ _h.handoff("done")
1136
+ return 0
1137
+
1138
+
1139
+ # ----------------------------------------------------------------------
1140
+ # sibyl hook
1141
+ # ----------------------------------------------------------------------
1142
+
1143
+ def cmd_hook(args: argparse.Namespace) -> int:
1144
+ # The installed `sibyl` command reaches hooks.main_hook directly (see
1145
+ # _entry.py) without importing this module; this is the same path.
1146
+ from .hooks import main_hook
1147
+ return main_hook(getattr(args, "event", ""))
1148
+
1149
+
1150
+ # ----------------------------------------------------------------------
1151
+ # sibyl status rows
1152
+ # ----------------------------------------------------------------------
1153
+
1154
+ def status_rows(args: argparse.Namespace, creds: dict[str, Any] | None) -> None:
1155
+ """The `lifecycle` eyebrow of `sibyl status` (spec 4.3). Never raises."""
1156
+ try:
1157
+ _status_rows(args, creds or {})
1158
+ except Exception:
1159
+ pass
1160
+
1161
+
1162
+ def _status_rows(args: argparse.Namespace, creds: dict[str, Any]) -> None:
1163
+ from sibyl_memory_client import skills as SK
1164
+ from sibyl_memory_client.lifecycle import policy as P
1165
+ from sibyl_memory_client.lifecycle import state as ST
1166
+ from sibyl_memory_client.lifecycle.runner import measure_for_reminder
1167
+ tid = _tenant(creds)
1168
+ pro, _tier = _pro(args)
1169
+ _legacy_notice()
1170
+ st = ST.LifecycleState(_home()).load()
1171
+ t = st.get("tenants", {}).get(tid or "", {}) if tid else {}
1172
+ marker = ST.read_save_marker(_db(args), tid) if tid else None
1173
+ last = max([x for x in (marker, t.get("last_save_at")) if isinstance(x, (int, float))], default=None)
1174
+ print()
1175
+ print(a.eyebrow("lifecycle"))
1176
+ save = f"last {_fmt_ts(last)} · {int(t.get('writes_since_save') or 0)} writes since · "
1177
+ save += ("automatic · " + _autosave_summary(st, tid, time.time()) if pro
1178
+ else "manual (automatic on Pro)")
1179
+ print(a.kv("save", save))
1180
+ rec = measure_for_reminder(_home(), Path.cwd())
1181
+ if rec is not None and rec["files"]:
1182
+ heavy = [f["file"] for f in rec["files"] if f["heavy"]]
1183
+ ctx = f"~{rec['total_tok'] / 1000:.1f}k tok always-load ({rec['weight']})"
1184
+ if heavy:
1185
+ ctx += f" · heavy: {', '.join(heavy[:3])}"
1186
+ else:
1187
+ ctx = "no always-load files found here"
1188
+ pol = P.load(_home())
1189
+ if pro:
1190
+ ctx += f" · policy {pol['mode']}"
1191
+ if pol["auto_files"]:
1192
+ ctx += f" ({len(pol['auto_files'])} file{'s' if len(pol['auto_files']) != 1 else ''} auto)"
1193
+ elif pol["auto_files"]:
1194
+ ctx += f" · {len(pol['auto_files'])} file(s) set to auto (runs on Pro)"
1195
+ print(a.kv("context", ctx))
1196
+ sst = SK.status(_home())
1197
+ if sst["exists"]:
1198
+ parts = [f"v{sst['installed_version'] or '?'}"]
1199
+ for n, info in sst["files"].items():
1200
+ parts.append(f"{n} {'edited by you' if info['state'] == 'edited' else info['state']}")
1201
+ harnesses = sorted({i.get('harness') for i in sst['shims'].values() if i.get('state') == 'ok'})
1202
+ if harnesses:
1203
+ parts.append(", ".join(f"{h} wired" for h in harnesses))
1204
+ print(a.kv("skills", " · ".join(parts)))
1205
+ else:
1206
+ print(a.kv("skills", "not installed · sibyl skills install"))
1207
+ if pro and tid:
1208
+ n = _pending_proposals(_db(args), tid)
1209
+ print(a.kv("proposals", f"{n} skill proposal{'s' if n != 1 else ''} pending"
1210
+ + (" · sibyl skills proposals" if n else "")))
1211
+ rem = "off" if not st.get("reminders", True) else ("quiet" if st.get("quiet") else "on")
1212
+ print(a.kv("reminders", rem))
1213
+
1214
+
1215
+ def _pending_proposals(db: Path, tid: str) -> int:
1216
+ """How many proposals are pending, read-only (no gate, no network)."""
1217
+ import sqlite3
1218
+ try:
1219
+ if not db.is_file() or db.is_symlink():
1220
+ return 0
1221
+ con = sqlite3.connect(f"file:{db}?mode=ro", uri=True, timeout=1.0)
1222
+ try:
1223
+ row = con.execute("SELECT count(*) FROM skill_proposals WHERE tenant_id = ? AND "
1224
+ "status = 'pending'", (tid,)).fetchone()
1225
+ finally:
1226
+ con.close()
1227
+ return int(row[0]) if row else 0
1228
+ except sqlite3.Error:
1229
+ return 0
1230
+
1231
+
1232
+ __all__ = ["cmd_autosave", "cmd_debloat", "cmd_hook", "cmd_refresh", "cmd_reminders", "cmd_save",
1233
+ "cmd_skills", "status_rows"]
sibyl-memory-cli/src/sibyl_memory_cli/migrate.py ADDED
@@ -0,0 +1,742 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """`sibyl setup` guided onboarding flow (v2): backup -> wire MCP -> extract -> verify -> debloat.
2
+
3
+ Design (operator-locked 2026-05-31): one dynamic, resumable, guided flow that gets a
4
+ user "set up and optimized" no matter which harness they run. The CLI does the
5
+ DETERMINISTIC work (back up files, detect state, verify the DB, trim files) and
6
+ CONDUCTS; the user's own harness does the semantic EXTRACTION (it has the memory
7
+ tools). Every gap (no plugin, MCP not wired) prints exact per-harness instructions.
8
+
9
+ This module adds the new phases on top of the existing wirers in setup.py
10
+ (HermesWirer / ClaudeCodeWirer) and adds CodexWirer so all three harnesses are
11
+ first-class. Nothing here touches live files except the explicitly-confirmed
12
+ debloat step, and only after a verified backup exists.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import shlex
17
+ import json
18
+ import os
19
+ import shutil
20
+ import sqlite3
21
+ from dataclasses import dataclass, field
22
+ from datetime import datetime, timezone
23
+ from pathlib import Path
24
+ from typing import Callable, Optional
25
+
26
+ # ----------------------------------------------------------------------
27
+ # 1. Memory/agent file discovery (per harness)
28
+ # ----------------------------------------------------------------------
29
+ # Candidate memory + agent files we back up + (optionally) extract from.
30
+ # Globs are resolved relative to `home`. Directories are copied whole.
31
+
32
+ HARNESS_FILES: dict[str, list[str]] = {
33
+ "claude-code": ["CLAUDE.md", ".claude/CLAUDE.md", ".claude/settings.json"],
34
+ "codex": ["AGENTS.md", ".codex/config.toml", ".codex/AGENTS.md"],
35
+ "hermes": [".hermes/config.yaml", ".hermes/memory"],
36
+ "generic": ["AGENTS.md", "MEMORY.md", "memory.md", ".cursorrules", ".cursor/rules"],
37
+ }
38
+
39
+
40
+ # Save/debloat build (spec plugin-save-debloat 6.1): one surface definition.
41
+ # CONTEXT_FILES are the instruction files an agent loads on every session
42
+ # (measured by `sibyl debloat`, trimmable by the migrate trim step);
43
+ # CONFIG_FILES are backed up and extracted from, NEVER trimmed. The union is
44
+ # every HARNESS_FILES entry (a test keeps the three from drifting).
45
+ try:
46
+ from sibyl_memory_client.lifecycle.measure import CONFIG_FILES, CONTEXT_FILES
47
+ except Exception: # pragma: no cover - client without the lifecycle package
48
+ CONTEXT_FILES = frozenset({"CLAUDE.md", ".claude/CLAUDE.md", "AGENTS.md", ".codex/AGENTS.md",
49
+ "MEMORY.md", "memory.md", ".cursorrules", ".cursor/rules"})
50
+ CONFIG_FILES = frozenset({".claude/settings.json", ".codex/config.toml",
51
+ ".hermes/config.yaml", ".hermes/memory"})
52
+
53
+
54
+ @dataclass
55
+ class FoundFile:
56
+ harness: str
57
+ path: Path # absolute
58
+ rel: str # path relative to home (for backup layout)
59
+ is_dir: bool
60
+ size: int
61
+ matched: str = "" # the HARNESS_FILES entry it matched (root-relative name)
62
+
63
+
64
+ def _backup_rel(p: Path, home: Path, cwd: Optional[Path]) -> str:
65
+ """Collision-free backup path for a source file. Files under home keep their
66
+ home-relative path; files outside home (a project elsewhere) get a `project/`
67
+ prefix; anything else `external/<name>`. This prevents a home file and a
68
+ same-named project file from clobbering each other in the backup (data-loss bug)."""
69
+ try:
70
+ if p.is_relative_to(home):
71
+ return str(p.relative_to(home))
72
+ except (ValueError, OSError):
73
+ pass
74
+ if cwd:
75
+ try:
76
+ cwd = Path(cwd)
77
+ if p.is_relative_to(cwd):
78
+ return "project/" + str(p.relative_to(cwd))
79
+ except (ValueError, OSError):
80
+ pass
81
+ return "external/" + p.name
82
+
83
+
84
+ def scan_memory_files(home: Optional[Path] = None, cwd: Optional[Path] = None) -> list[FoundFile]:
85
+ """Find existing memory/agent files across harnesses. De-dupes by resolved path.
86
+ Looks in both the user's home and the current project dir (CLAUDE.md lives in projects)."""
87
+ home = Path(home).expanduser() if home else Path.home()
88
+ roots = [home]
89
+ if cwd:
90
+ roots.append(Path(cwd))
91
+ seen: set[Path] = set()
92
+ found: list[FoundFile] = []
93
+ for harness, rels in HARNESS_FILES.items():
94
+ for rel in rels:
95
+ for root in roots:
96
+ p = (root / rel)
97
+ if not p.exists():
98
+ continue
99
+ try:
100
+ key = p.resolve()
101
+ except OSError:
102
+ key = p
103
+ if key in seen:
104
+ continue
105
+ seen.add(key)
106
+ is_dir = p.is_dir()
107
+ size = _tree_size(p) if is_dir else p.stat().st_size
108
+ found.append(FoundFile(harness, p, _backup_rel(p, home, cwd), is_dir, size, rel))
109
+ return found
110
+
111
+
112
+ def _tree_size(p: Path) -> int:
113
+ """Sum the byte size of every regular file under ``p``.
114
+
115
+ B005 (audit #19): a permission-denied file or a broken symlink raises
116
+ OSError on ``is_file()``/``stat()``. A single un-statable entry must not
117
+ abort the whole size estimate, so each entry is guarded independently and
118
+ the offending one is simply skipped (counted as zero).
119
+ """
120
+ total = 0
121
+ for f in p.rglob("*"):
122
+ try:
123
+ if f.is_file():
124
+ total += f.stat().st_size
125
+ except OSError:
126
+ continue
127
+ return total
128
+
129
+
130
+ def _fsync_path(p: Path) -> None:
131
+ """Best-effort fsync of a file or directory so a crash right after backup
132
+ can't leave a partially-flushed copy. CLI-9: backups must survive a power
133
+ loss before we trust them enough to trim the originals."""
134
+ try:
135
+ if p.is_dir():
136
+ flags = getattr(os, "O_DIRECTORY", 0)
137
+ fd = os.open(str(p), os.O_RDONLY | flags)
138
+ else:
139
+ fd = os.open(str(p), os.O_RDONLY)
140
+ try:
141
+ os.fsync(fd)
142
+ finally:
143
+ os.close(fd)
144
+ except (OSError, ValueError):
145
+ # Directory fsync is not portable everywhere; never fail the backup on it.
146
+ pass
147
+
148
+
149
+ # ----------------------------------------------------------------------
150
+ # 2. Backup (deterministic, verified, timestamped) — the safety win
151
+ # ----------------------------------------------------------------------
152
+
153
+ @dataclass
154
+ class BackupResult:
155
+ backup_dir: Path
156
+ files: list[str] = field(default_factory=list)
157
+ total_bytes: int = 0
158
+ ok: bool = True
159
+ error: Optional[str] = None
160
+
161
+
162
+ def backup_dir_name(now: Optional[datetime] = None) -> str:
163
+ now = now or datetime.now(timezone.utc)
164
+ return "sibyl-migration-backup-" + now.strftime("%Y-%m-%dT%H_%M_%S")
165
+
166
+
167
+ def run_backup(files: list[FoundFile], dest_parent: Path, *, now: Optional[datetime] = None) -> BackupResult:
168
+ """Copy each found file/dir into a fresh timestamped backup folder under dest_parent.
169
+ Verifies byte counts. Never modifies sources. Aborts (ok=False) on first failure."""
170
+ dest_parent = Path(dest_parent).expanduser()
171
+ backup = dest_parent / backup_dir_name(now)
172
+ res = BackupResult(backup_dir=backup)
173
+ try:
174
+ backup.mkdir(parents=True, exist_ok=False)
175
+ except Exception as e:
176
+ res.ok = False; res.error = f"could not create backup dir: {e}"
177
+ return res
178
+ for f in files:
179
+ target = backup / f.rel
180
+ try:
181
+ target.parent.mkdir(parents=True, exist_ok=True)
182
+ if f.is_dir:
183
+ shutil.copytree(f.path, target, dirs_exist_ok=True)
184
+ src_sz, dst_sz = _tree_size(f.path), _tree_size(target)
185
+ # CLI-9: fsync every copied file in the tree so the backup is
186
+ # durable before we ever trim an original.
187
+ for cf in target.rglob("*"):
188
+ if cf.is_file():
189
+ _fsync_path(cf)
190
+ else:
191
+ shutil.copy2(f.path, target)
192
+ src_sz, dst_sz = f.path.stat().st_size, target.stat().st_size
193
+ _fsync_path(target) # CLI-9: durable copy before any trim
194
+ if src_sz != dst_sz:
195
+ res.ok = False; res.error = f"byte mismatch on {f.rel} ({src_sz} != {dst_sz})"
196
+ return res
197
+ res.files.append(f.rel); res.total_bytes += dst_sz
198
+ except Exception as e:
199
+ res.ok = False; res.error = f"copy failed on {f.rel}: {type(e).__name__}: {e}"
200
+ return res
201
+ # CLI-9: fsync the backup directory itself so its directory entries (the
202
+ # newly-created files) are persisted, not just the file contents.
203
+ _fsync_path(backup)
204
+ return res
205
+
206
+
207
+ # ----------------------------------------------------------------------
208
+ # 3. Wirers live in setup.py (canonical). Codex now auto-wires config.toml;
209
+ # Claude Code registers via `claude mcp add --scope user`.
210
+ # ----------------------------------------------------------------------
211
+
212
+ from .setup import CodexWirer, ClaudeCodeWirer, HermesWirer # noqa: E402 (canonical wirers)
213
+
214
+
215
+ # Per-harness wiring instructions for the guided flow (no silent edits across the board;
216
+ # we print and let the user run them, matching the operator's 'walk them through' intent).
217
+ def wire_instructions(harness: str) -> list[str]:
218
+ if harness == "claude-code":
219
+ return ["Open a new terminal and run:",
220
+ " claude mcp add sibyl-memory -- sibyl-memory-mcp",
221
+ "Restart Claude Code (or /mcp -> reconnect sibyl-memory), then return here."]
222
+ if harness == "codex":
223
+ return CodexWirer().instructions()
224
+ if harness == "hermes":
225
+ return ["Open a new terminal and run:",
226
+ " sibyl setup hermes",
227
+ "It installs the plugin and sets memory.provider: sibyl in your Hermes config.yaml. Restart Hermes."]
228
+ return ["Register an MCP server named 'sibyl-memory' with command 'sibyl-memory-mcp' in your agent's MCP config, then restart it."]
229
+
230
+
231
+ # ----------------------------------------------------------------------
232
+ # 4. Extraction handoff — the harness does the semantic work, from the backup
233
+ # ----------------------------------------------------------------------
234
+
235
+ def extraction_prompt(harness: str, backup_dir: Path) -> str:
236
+ """Tailored backup-first prompt the user runs IN their harness. Reads only from
237
+ the backup; never edits live files. Mirrors the beta-page conventions."""
238
+ tool = "sibyl_remember" if harness in ("claude-code", "codex") else "your memory tool"
239
+ return (
240
+ f"Read ONLY from the backup folder at {backup_dir} (never touch my live files). "
241
+ "For every piece of accumulated memory in those files (facts and configs, preferences "
242
+ "and patterns, project context, people and relationship notes), write each one into Sibyl "
243
+ f"Memory using {tool}:\n"
244
+ " - facts/configs/env: structured key-value content\n"
245
+ " - preferences/patterns: tagged as preference\n"
246
+ " - project context/history: under a project namespace\n"
247
+ " - people/relationships: with the person's name as context\n"
248
+ "Do not edit, trim, or delete any live file. When done, tell me how many entries you wrote "
249
+ "in each category."
250
+ )
251
+
252
+
253
+ # ----------------------------------------------------------------------
254
+ # 5. Verify — count what actually landed in the local Sibyl DB
255
+ # ----------------------------------------------------------------------
256
+
257
+ # Sentinel returned by db_baseline when the path EXISTS but is not a readable
258
+ # SQLite database (garbage bytes, wrong magic, locked, corrupt). Distinct from
259
+ # 0 (a valid empty DB / no DB yet). CLI-3 migrate half: the orchestrator must
260
+ # ABORT verify + debloat on this, never silently treat it as a 0-row DB and
261
+ # proceed to trim the user's real files against a backup it can't trust.
262
+ DB_UNREADABLE = -1
263
+
264
+
265
+ def _is_readable_db(db_path: Path) -> bool:
266
+ """True if `db_path` is a non-empty file that opens as a real SQLite DB.
267
+
268
+ A 0-byte file is treated as a fresh/empty DB by sqlite and counts as
269
+ readable (no rows yet). Anything that fails the header check or PRAGMA is
270
+ unreadable."""
271
+ try:
272
+ if not db_path.is_file():
273
+ return False
274
+ if db_path.stat().st_size == 0:
275
+ return True
276
+ with open(db_path, "rb") as fh:
277
+ if fh.read(16) != b"SQLite format 3\x00":
278
+ return False
279
+ con = sqlite3.connect(str(db_path))
280
+ try:
281
+ con.execute("PRAGMA schema_version")
282
+ finally:
283
+ con.close()
284
+ return True
285
+ except (OSError, sqlite3.Error):
286
+ return False
287
+
288
+
289
+ def db_baseline(db_path: Path) -> int:
290
+ """Total entity count now, to diff against after extraction.
291
+
292
+ Returns 0 if no DB exists yet (or an empty DB with no rows), and
293
+ DB_UNREADABLE (-1) when the path exists but is not a usable SQLite DB —
294
+ CLI-3: the caller must distinguish "no DB" from "unreadable DB"."""
295
+ db_path = Path(db_path).expanduser()
296
+ if not db_path.exists():
297
+ return 0
298
+ if not _is_readable_db(db_path):
299
+ return DB_UNREADABLE
300
+ # B001 (audit #19): close the connection on the error path too. If the
301
+ # COUNT raises (e.g. no `entities` table yet), the bare con.close() below
302
+ # the query would be skipped and the connection would leak.
303
+ try:
304
+ con = sqlite3.connect(str(db_path)); con.row_factory = sqlite3.Row
305
+ try:
306
+ n = con.execute("SELECT COUNT(*) c FROM entities").fetchone()["c"]
307
+ finally:
308
+ con.close()
309
+ return int(n)
310
+ except sqlite3.Error:
311
+ # Readable SQLite file but no `entities` table yet (fresh schema) —
312
+ # that's 0 baseline, not an unreadable DB.
313
+ return 0
314
+
315
+
316
+ def verify_new_entries(db_path: Path, baseline_total: int) -> dict:
317
+ """Return {'new_total': N, 'by_category': {...}, 'ok': bool}. ok = new_total > 0.
318
+
319
+ CLI-3: if the DB path exists but is unreadable, set ok=False and flag
320
+ `unreadable` so the orchestrator aborts rather than reporting 0 new
321
+ entries (which would falsely gate a debloat)."""
322
+ db_path = Path(db_path).expanduser()
323
+ out = {"new_total": 0, "by_category": {}, "ok": False}
324
+ if not db_path.exists():
325
+ return out
326
+ if not _is_readable_db(db_path):
327
+ out["unreadable"] = True
328
+ out["error"] = "database file exists but is not a readable SQLite database"
329
+ return out
330
+ # B001 (audit #19): wrap connect+query in try/finally so the connection is
331
+ # always closed. The previous bare con.close() ran only after both queries
332
+ # succeeded — any sqlite3.Error mid-query leaked the open connection.
333
+ try:
334
+ con = sqlite3.connect(str(db_path)); con.row_factory = sqlite3.Row
335
+ try:
336
+ total = con.execute("SELECT COUNT(*) c FROM entities").fetchone()["c"]
337
+ cats = con.execute("SELECT category, COUNT(*) c FROM entities GROUP BY category ORDER BY c DESC").fetchall()
338
+ finally:
339
+ con.close()
340
+ out["new_total"] = max(0, int(total) - int(baseline_total))
341
+ out["by_category"] = {r["category"]: int(r["c"]) for r in cats}
342
+ out["ok"] = out["new_total"] > 0
343
+ except sqlite3.Error as e:
344
+ out["error"] = str(e)
345
+ return out
346
+
347
+
348
+ # ----------------------------------------------------------------------
349
+ # 6. Debloat — confirmed trim of the live file; safe because backup exists
350
+ # ----------------------------------------------------------------------
351
+
352
+ KEEP_START, KEEP_END = "<!-- sibyl:keep -->", "<!-- /sibyl:keep -->"
353
+
354
+
355
+ def heuristic_lean(text: str) -> str:
356
+ """Conservative lean version when the agent didn't provide one.
357
+ If the file marks a keep-block, keep exactly that. Otherwise keep everything up to
358
+ the first H2 section (identity/rules usually live at the top) and append a pointer.
359
+ The full original is always in the backup, so this is reversible."""
360
+ if KEEP_START in text and KEEP_END in text:
361
+ core = text.split(KEEP_START, 1)[1].split(KEEP_END, 1)[0].strip()
362
+ else:
363
+ lines, core_lines = text.splitlines(), []
364
+ seen_h2 = 0
365
+ for ln in lines:
366
+ if ln.startswith("## "):
367
+ seen_h2 += 1
368
+ if seen_h2 > 1: # keep the first ## section (identity/core), trim the rest
369
+ break
370
+ core_lines.append(ln)
371
+ core = "\n".join(core_lines).strip()
372
+ # The pointer claims only what is true: the whole file is in the backup,
373
+ # and the migrate extraction stored entries (not necessarily this text)
374
+ # in Sibyl Memory.
375
+ pointer = ("\n\n<!-- Trimmed by sibyl migrate: a full copy of this file is in the pre-migration "
376
+ "backup; the migrate extraction stored entries in Sibyl Memory, recalled on demand. -->\n")
377
+ return core + pointer
378
+
379
+
380
+ def verify_backup_of(live_path: Path, backup_dir: Path, *, home: Path, cwd: Optional[Path]) -> bool:
381
+ """Re-stat the SPECIFIC backup copy of `live_path` and confirm it exists
382
+ with a matching byte count.
383
+
384
+ CLI-9: before trimming an original we must verify the backup file on disk
385
+ right now — not trust the in-memory `bk.ok` flag from earlier, which can't
386
+ catch a backup that was deleted/truncated/corrupted in the meantime."""
387
+ try:
388
+ rel = _backup_rel(Path(live_path), Path(home), cwd)
389
+ backup_copy = Path(backup_dir) / rel
390
+ if not backup_copy.is_file():
391
+ return False
392
+ return backup_copy.stat().st_size == Path(live_path).stat().st_size
393
+ except OSError:
394
+ return False
395
+
396
+
397
+ def debloat_file(live_path: Path, lean_text: str, *, backup_exists: bool, dry_run: bool = False) -> dict:
398
+ """Atomically replace live_path with lean_text. REFUSES unless backup_exists is True.
399
+ Returns {before, after, written, error}."""
400
+ live_path = Path(live_path).expanduser()
401
+ out = {"before": 0, "after": len(lean_text.encode()), "written": False}
402
+ if not backup_exists:
403
+ out["error"] = "refused: no verified backup exists"; return out
404
+ # CLI-8: refuse to trim through a symlink. os.replace on a symlinked target
405
+ # would clobber whatever the link points at — potentially a file outside
406
+ # the intended scope. The debloat is the highest-blast-radius step; it must
407
+ # only ever rewrite a regular file we backed up.
408
+ if live_path.is_symlink():
409
+ out["error"] = "refused: live file is a symlink"; return out
410
+ if not live_path.exists():
411
+ out["error"] = "live file not found"; return out
412
+ out["before"] = live_path.stat().st_size
413
+ if dry_run:
414
+ return out
415
+ # CLI-8: mkstemp (unique per-process) + fsync + atomic os.replace, instead
416
+ # of a fixed `.sibyl-tmp` name that two runs could collide on.
417
+ data = lean_text.encode("utf-8")
418
+ import tempfile
419
+ fd, tmp = tempfile.mkstemp(dir=str(live_path.parent),
420
+ prefix=live_path.name + ".", suffix=".sibyl-tmp")
421
+ try:
422
+ os.write(fd, data)
423
+ os.fsync(fd)
424
+ except BaseException:
425
+ os.close(fd)
426
+ try:
427
+ os.unlink(tmp)
428
+ except OSError:
429
+ pass
430
+ raise
431
+ else:
432
+ os.close(fd)
433
+ os.replace(tmp, str(live_path))
434
+ out["written"] = True
435
+ return out
436
+
437
+
438
+ # ----------------------------------------------------------------------
439
+ # 7. Orchestrator — the guided, resumable flow
440
+ # ----------------------------------------------------------------------
441
+
442
+ def detect_state(home: Optional[Path] = None, cwd: Optional[Path] = None, db_path: Optional[Path] = None) -> dict:
443
+ """Snapshot for resumability: what's present, what's wired, how much memory exists."""
444
+ from .setup import HermesWirer, ClaudeCodeWirer
445
+ home = Path(home).expanduser() if home else Path.home()
446
+ db_path = Path(db_path).expanduser() if db_path else (home / ".sibyl-memory" / "memory.db")
447
+ wirers = {"claude-code": ClaudeCodeWirer(), "codex": CodexWirer(), "hermes": HermesWirer()}
448
+ return {
449
+ "files": scan_memory_files(home, cwd),
450
+ "harnesses": {n: {"present": w.is_present(), **w.current_state()} for n, w in wirers.items()},
451
+ "db_entries": db_baseline(db_path),
452
+ "db_path": db_path,
453
+ }
454
+
455
+
456
+ class GuidedIO:
457
+ """IO seam so the guided flow is testable non-interactively. Pass `scripted`
458
+ answers (list) to drive confirms/pauses without a TTY."""
459
+ def __init__(self, scripted=None):
460
+ self.scripted = list(scripted or [])
461
+ self.lines: list[str] = []
462
+ # True when the last confirm/pause hit end of input (no terminal):
463
+ # the flow then says which default it took (agent handoff, N6 / N9).
464
+ self.last_eof = False
465
+
466
+ def say(self, s: str = "") -> None:
467
+ self.lines.append(str(s))
468
+
469
+ def confirm(self, q: str, *, default: bool = True) -> bool:
470
+ self.last_eof = False
471
+ if self.scripted:
472
+ ans = self.scripted.pop(0)
473
+ else:
474
+ try:
475
+ ans = input(f"{q} [{'Y/n' if default else 'y/N'}]: ").strip()
476
+ except EOFError:
477
+ ans = ""
478
+ self.last_eof = True
479
+ return default if not ans else ans.strip().lower().startswith("y")
480
+
481
+ def pause(self, q: str = "press Enter to continue") -> None:
482
+ self.last_eof = False
483
+ if self.scripted:
484
+ self.scripted.pop(0)
485
+ return
486
+ try:
487
+ input(q)
488
+ except EOFError:
489
+ self.last_eof = True
490
+
491
+
492
+ def run_guided_setup(*, home=None, cwd=None, db_path=None, backup_parent=None,
493
+ io: Optional[GuidedIO] = None, wirers: Optional[dict] = None,
494
+ extract_fn: Optional[Callable[[Path, Path], None]] = None,
495
+ debloat: bool = True, force: bool = False, now=None) -> dict:
496
+ """The assembled guided flow: backup -> auto-wire each harness (instructions on
497
+ failure) -> extraction handoff -> verify -> confirmed debloat. Returns a structured
498
+ report. `extract_fn(backup_dir, db_path)` performs/simulates extraction; default
499
+ prints the prompt for the user to run in their own harness. `wirers` is injectable
500
+ so tests (and isolation) never touch real config."""
501
+ from .setup import ALL_WIRERS
502
+ io = io or GuidedIO()
503
+ home = Path(home).expanduser() if home else Path.home()
504
+ db_path = Path(db_path).expanduser() if db_path else (home / ".sibyl-memory" / "memory.db")
505
+ backup_parent = Path(backup_parent).expanduser() if backup_parent else home
506
+ # Agent handoff (spec 2026-10-03 rows N4 to N10): `handoff` is the block of
507
+ # a failing phase; `later` collects follow-ups for the final block.
508
+ report: dict = {"ok": True, "phases": {}, "later": []}
509
+
510
+ # 1. scan + backup (deterministic, first, never modifies sources)
511
+ files = scan_memory_files(home, cwd)
512
+ report["files"] = [f.rel for f in files]
513
+ if not files:
514
+ io.say("No memory/agent files found. Nothing to migrate.")
515
+ report["ok"] = False
516
+ report["handoff"] = {"next": "sibyl setup", "human": None}
517
+ return report
518
+ bk = run_backup(files, backup_parent, now=now)
519
+ report["phases"]["backup"] = {"ok": bk.ok, "dir": str(bk.backup_dir), "files": len(bk.files)}
520
+ if not bk.ok:
521
+ io.say(f"Backup failed: {bk.error}. Aborting; nothing else touched.")
522
+ report["ok"] = False
523
+ report["handoff"] = {
524
+ "next": "sibyl migrate --backup-dir <dir>",
525
+ "human": f"the backup folder {backup_parent} could not be written ({bk.error}); pick "
526
+ "another with --backup-dir"}
527
+ return report
528
+ io.say(f"Backed up {len(bk.files)} files -> {bk.backup_dir} (originals untouched)")
529
+
530
+ # 2. detect + auto-wire each present harness; fall back to instructions
531
+ if wirers is None:
532
+ wirers = {n: cls() for n, cls in ALL_WIRERS.items()}
533
+ detected = {n: w for n, w in wirers.items() if w.is_present()}
534
+ wire_report = {}
535
+ for name, w in detected.items():
536
+ if w.current_state().get("wired_with_sibyl"):
537
+ wire_report[name] = "already"
538
+ continue
539
+ outcome = w.wire(force=force)
540
+ wire_report[name] = outcome.status
541
+ if outcome.status not in ("wired", "already"):
542
+ io.say(f"{name}: auto-wire incomplete ({outcome.message}). Do this manually:")
543
+ for ln in wire_instructions(name):
544
+ io.say(" " + ln)
545
+ io.say(f"ask your human: run the steps above, restart {getattr(w, 'display_name', name)}, "
546
+ "then tell me")
547
+ report["later"].append(f"sibyl setup {name} --force")
548
+ report["phases"]["wire"] = wire_report
549
+
550
+ # 3. extraction (the harness does it; default prints the prompt + pauses)
551
+ baseline = db_baseline(db_path)
552
+ # CLI-3: if the DB path exists but is unreadable, do NOT proceed to verify
553
+ # + debloat. A debloat trims the user's live files; gating it on a DB we
554
+ # cannot read would be unsafe. Abort cleanly with the originals intact.
555
+ if baseline == DB_UNREADABLE:
556
+ io.say("Sibyl memory DB exists but is unreadable (not a valid SQLite database).")
557
+ io.say("Aborting before verify/trim — your originals and backup are intact.")
558
+ report["phases"]["verify"] = {"new_total": 0, "by_category": {}, "ok": False, "unreadable": True}
559
+ report["ok"] = False
560
+ report["handoff"] = {"next": "sibyl status",
561
+ "human": f"{db_path} is not a readable SQLite file; move it aside or "
562
+ "point --db elsewhere"}
563
+ return report
564
+ target = next(iter(detected), "claude-code")
565
+ if extract_fn is not None:
566
+ extract_fn(bk.backup_dir, db_path)
567
+ else:
568
+ io.say("Run this in your agent (it reads the backup, writes to Sibyl):")
569
+ io.say(extraction_prompt(target, bk.backup_dir))
570
+ io.pause("After it finishes, press Enter to verify")
571
+ if io.last_eof:
572
+ io.say("no terminal to wait on: verify runs now and will count 0; after your agent runs "
573
+ "the prompt above, check with sibyl memory list and trim with sibyl debloat plan")
574
+ io.say("ask your human: nothing; I run the extraction prompt above myself in this session")
575
+
576
+ # 4. verify
577
+ v = verify_new_entries(db_path, baseline)
578
+ report["phases"]["verify"] = v
579
+ io.say(f"Verified {v['new_total']} new entries in Sibyl Memory.")
580
+
581
+ # 5. debloat (confirmed per file; safe because the backup exists).
582
+ # Save/debloat build (spec 6.2): every instruction file the scan found is a
583
+ # candidate (CLAUDE.md, AGENTS.md, .cursorrules, ...), not a hardcoded
584
+ # CLAUDE.md; configuration files are never candidates; .cursor/rules is a
585
+ # directory (measured by `sibyl debloat`, never trimmed). A project
586
+ # .debloat.json "surface" narrows the candidates. One question per file,
587
+ # default No; --yes never answers it.
588
+ if debloat and v["ok"]:
589
+ records: list[dict] = []
590
+ for f, why in trim_candidates(files, home=home, cwd=cwd):
591
+ if why:
592
+ io.say(f"{f.matched or f.path.name}: {why}; left as is.")
593
+ continue
594
+ label = _trim_label(f, home=home, cwd=cwd)
595
+ try:
596
+ text = f.path.read_bytes().decode("utf-8")
597
+ except (OSError, UnicodeDecodeError):
598
+ io.say(f"{label}: not UTF-8 text; left as is.")
599
+ _later_once(report, "sibyl debloat plan")
600
+ continue
601
+ lean = lean_text_for(text, f.path.name, bk.backup_dir)
602
+ if lean is None:
603
+ io.say(f"{label}: no safe trim found; left as is.")
604
+ _later_once(report, "sibyl debloat plan")
605
+ continue
606
+ if not io.confirm(f"Trim {label} to lean now? Full backup is safe at {bk.backup_dir}",
607
+ default=False):
608
+ if io.last_eof:
609
+ io.say(f"no terminal: {label} not trimmed (default no); later: "
610
+ f"sibyl debloat apply {shlex.quote(label)} --yes")
611
+ records.append({"file": label, "written": False, "declined": True,
612
+ "before": f.path.stat().st_size, "after": 0})
613
+ _later_once(report, "sibyl debloat plan")
614
+ continue
615
+ # CLI-9: re-verify the actual backup copy of THIS file on disk right
616
+ # now, instead of trusting the earlier in-memory bk.ok.
617
+ backup_ok_now = bk.ok and verify_backup_of(f.path, bk.backup_dir, home=home, cwd=cwd)
618
+ if not backup_ok_now:
619
+ io.say(f"Backup of {label} could not be re-verified; skipping trim. Original untouched.")
620
+ records.append({"file": label, "written": False, "before": f.path.stat().st_size,
621
+ "after": 0, "error": "backup re-verification failed"})
622
+ _later_once(report, "sibyl debloat plan")
623
+ continue
624
+ d = debloat_file(f.path, lean, backup_exists=backup_ok_now)
625
+ records.append({"file": label, "written": d["written"], "before": d["before"],
626
+ "after": d["after"], **({"error": d["error"]} if d.get("error") else {})})
627
+ if d["written"]:
628
+ io.say(f"Trimmed {label}. Backup safe at {bk.backup_dir}")
629
+ if records:
630
+ report["phases"]["debloat"] = records
631
+ return report
632
+
633
+
634
+ def _later_once(report: dict, cmd: str) -> None:
635
+ later = report.setdefault("later", [])
636
+ if cmd not in later:
637
+ later.append(cmd)
638
+
639
+
640
+ def _trim_label(f: FoundFile, *, home: Path, cwd: Optional[Path]) -> str:
641
+ """The name a person recognises: project files relative to the project,
642
+ home files as ~/<rel>."""
643
+ if cwd is not None:
644
+ try:
645
+ return str(Path(f.path).relative_to(Path(cwd)))
646
+ except ValueError:
647
+ pass
648
+ try:
649
+ return "~/" + str(Path(f.path).relative_to(Path(home)))
650
+ except ValueError:
651
+ return f.path.name
652
+
653
+
654
+ def _within_roots(p: Path, home: Path, cwd: Optional[Path]) -> bool:
655
+ ap = Path(os.path.normpath(str(p)))
656
+ for base in [home] + ([Path(cwd)] if cwd is not None else []):
657
+ bp = Path(os.path.normpath(str(base)))
658
+ try:
659
+ if ap == bp or ap.is_relative_to(bp):
660
+ return True
661
+ except ValueError:
662
+ continue
663
+ return False
664
+
665
+
666
+ def _project_surface(cwd: Optional[Path], home: Path) -> Optional[set]:
667
+ """Resolved absolute paths named by a project .debloat.json "surface", or
668
+ None when there is none. Entries outside home and the project are ignored."""
669
+ if cwd is None:
670
+ return None
671
+ cfg = Path(cwd) / ".debloat.json"
672
+ try:
673
+ if not cfg.is_file() or cfg.is_symlink() or cfg.stat().st_size > 64 * 1024:
674
+ return None
675
+ data = json.loads(cfg.read_text(encoding="utf-8"))
676
+ except (OSError, ValueError):
677
+ return None
678
+ surface = data.get("surface") if isinstance(data, dict) else None
679
+ if not isinstance(surface, list):
680
+ return None
681
+ out = set()
682
+ for entry in surface:
683
+ if not isinstance(entry, str) or not entry:
684
+ continue
685
+ p = Path(entry) if Path(entry).is_absolute() else Path(cwd) / entry
686
+ if _within_roots(p, home, cwd):
687
+ out.add(os.path.normpath(str(p)))
688
+ return out
689
+
690
+
691
+ def trim_candidates(files: list[FoundFile], *, home: Path, cwd: Optional[Path]
692
+ ) -> list[tuple[FoundFile, str]]:
693
+ """(file, reason-it-is-skipped or '') for every scanned file that is an
694
+ instruction file, in scan order. Config files never appear; a directory
695
+ (.cursor/rules) appears with its reason; an empty file is skipped."""
696
+ surface = _project_surface(cwd, Path(home))
697
+ out: list[tuple[FoundFile, str]] = []
698
+ for f in files:
699
+ if f.matched not in CONTEXT_FILES:
700
+ continue
701
+ if surface is not None and os.path.normpath(str(f.path)) not in surface:
702
+ continue
703
+ if f.is_dir:
704
+ out.append((f, "a directory (measured by sibyl debloat, never trimmed)"))
705
+ continue
706
+ if f.size <= 0:
707
+ continue
708
+ if f.path.is_symlink():
709
+ out.append((f, "a symlink"))
710
+ continue
711
+ out.append((f, ""))
712
+ return out
713
+
714
+
715
+ def lean_text_for(text: str, name: str, backup_dir: Path, *, now=None) -> Optional[str]:
716
+ """The lean version of an instruction file, or None when there is no safe
717
+ trim. The safe splitter's CURRENT projection when it finds history
718
+ (spec 6.2), else the first-H2 rule (heuristic_lean). A result that keeps
719
+ under 10 % or over 90 % of the original is not a safe trim; neither is a
720
+ file that is not Markdown or plain text."""
721
+ try:
722
+ from sibyl_memory_client.lifecycle import splitter as S
723
+ except Exception: # pragma: no cover
724
+ S = None
725
+ kind = S.kind_for(name) if S is not None else ("markdown" if name.endswith(".md") else None)
726
+ if kind is None:
727
+ return None
728
+ lean = None
729
+ if S is not None:
730
+ pl = S.split(text, kind=kind, now=now)
731
+ if pl.safe:
732
+ eol = "\r\n" if "\r\n" in text else "\n"
733
+ sep = "" if (pl.current == "" or pl.current.endswith("\n")) else eol
734
+ lean = (pl.current + sep + "<!-- Trimmed by sibyl migrate: a full copy of this file is in "
735
+ f"the backup at {backup_dir}; the migrate extraction stored entries in Sibyl "
736
+ "Memory, recalled on demand. -->" + eol)
737
+ if lean is None:
738
+ lean = heuristic_lean(text)
739
+ before, after = len(text.encode("utf-8")), len(lean.encode("utf-8"))
740
+ if before == 0 or after >= before * 0.9 or after <= before * 0.1:
741
+ return None
742
+ return lean
sibyl-memory-cli/src/sibyl_memory_cli/setup.py ADDED
The diff for this file is too large to render. See raw diff
 
sibyl-memory-cli/tests/_harness_fixtures.py ADDED
@@ -0,0 +1,52 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Shared helpers for the 2026-11-13 harness tests (DeepSeek Harness wirer,
2
+ doctor harness checks, backups under the plugin home, Codex stale path).
3
+
4
+ ``isolate_path`` gives a test an isolated PATH: a temp bin directory holding
5
+ only a fake ``sibyl-memory-mcp``, then /usr/bin and /bin. ``shutil.which`` is
6
+ wrapped so the harness binaries (claude, codex, cursor, cursor-agent, hermes,
7
+ dsh) are never found, whatever is installed on the machine running the suite:
8
+ the real ``claude`` is on PATH on the build box, and the harness section of
9
+ doctor would otherwise depend on it. Nothing here runs a harness binary."""
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ import shutil
14
+ from pathlib import Path
15
+
16
+ HIDDEN_BINARIES = ("claude", "codex", "cursor", "cursor-agent", "hermes", "dsh")
17
+ SCRUBBED_ENV = ("DSH_HOME", "SIBYL_MEMORY_MCP_OUTPUT_TOKENS", "SIBYL_MEMORY_RANKED_MIN_TOKENS",
18
+ "CLAUDE_CONFIG_DIR", "SIBYL_MEMORY_INSTRUCTIONS")
19
+
20
+ _REAL_WHICH = shutil.which
21
+
22
+
23
+ def isolate_path(monkeypatch, tmp_path: Path) -> Path:
24
+ bindir = tmp_path / "isolated-bin"
25
+ bindir.mkdir(exist_ok=True)
26
+ fake = bindir / "sibyl-memory-mcp"
27
+ fake.write_text("#!/bin/sh\nexit 0\n")
28
+ fake.chmod(0o755)
29
+ monkeypatch.setenv("PATH", f"{bindir}:/usr/bin:/bin")
30
+
31
+ def which(cmd, mode=os.F_OK | os.X_OK, path=None):
32
+ if os.path.basename(str(cmd)) in HIDDEN_BINARIES:
33
+ return None
34
+ return _REAL_WHICH(cmd, mode=mode, path=path)
35
+
36
+ monkeypatch.setattr(shutil, "which", which)
37
+ for name in SCRUBBED_ENV:
38
+ monkeypatch.delenv(name, raising=False)
39
+ return fake
40
+
41
+
42
+ def backups_dir(harness: str, sub: str = "") -> Path:
43
+ d = Path.home() / ".sibyl-memory" / "backups" / harness
44
+ return d / sub if sub else d
45
+
46
+
47
+ def leftovers(directory: Path) -> list:
48
+ """Temp files or .bak files of ours left in a harness directory."""
49
+ if not directory.is_dir():
50
+ return []
51
+ return sorted(p.name for p in directory.iterdir()
52
+ if p.name.endswith((".tmp", ".sibyl-tmp", ".bak")))
sibyl-memory-cli/tests/conftest.py ADDED
@@ -0,0 +1,203 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ import pytest
2
+ from sibyl_memory_cli import setup as _setup
3
+ from sibyl_memory_client.testing import (
4
+ TestSigner,
5
+ forbid_external_network,
6
+ install_entitled_home,
7
+ patch_trusted_keys,
8
+ )
9
+
10
+
11
+ @pytest.fixture(autouse=True)
12
+ def _no_real_claude_cli(monkeypatch):
13
+ """SAFETY + determinism: by default pretend the `claude` CLI is absent, so the
14
+ settings.json-fallback tests are deterministic and NO test ever shells out to the
15
+ real `claude mcp` (which would mutate this machine's actual MCP config). Tests that
16
+ exercise the CLI path re-patch _claude_cli + _run explicitly."""
17
+ monkeypatch.setattr(_setup.ClaudeCodeWirer, "_claude_cli", staticmethod(lambda: None))
18
+ yield
19
+
20
+
21
+ # ---- 0.5.0 account gate (spec 4.4) -----------------------------------------
22
+ # The gate (sibyl-memory-client) reads entitlement.json beside the credentials
23
+ # file and may refresh it over the network. In tests: a throwaway Ed25519 key is
24
+ # monkeypatched into TRUSTED_KEYS (the production pinned key is untouched),
25
+ # every refresh is routed to that test signer, non-loopback sockets are refused,
26
+ # and HOME plus the CLI's import-time default paths point at a per-test fake
27
+ # home, so no test can read or write a real ~/.sibyl-memory or reach an api.
28
+
29
+ @pytest.fixture(scope="session")
30
+ def test_signer() -> TestSigner:
31
+ return TestSigner()
32
+
33
+
34
+ @pytest.fixture(scope="session", autouse=True)
35
+ def _session_gate_guard(test_signer):
36
+ mp = pytest.MonkeyPatch()
37
+ patch_trusted_keys(mp, test_signer)
38
+ forbid_external_network(mp)
39
+ yield
40
+ mp.undo()
41
+
42
+
43
+ @pytest.fixture
44
+ def entitled_home(_isolated_home):
45
+ """The activated fake home's ~/.sibyl-memory directory."""
46
+ return _isolated_home / ".sibyl-memory"
47
+
48
+
49
+ @pytest.fixture(autouse=True)
50
+ def _isolated_home(tmp_path_factory, monkeypatch, test_signer):
51
+ from sibyl_memory_cli import cli
52
+ home = tmp_path_factory.mktemp("cli-home")
53
+ monkeypatch.setenv("HOME", str(home))
54
+ monkeypatch.setenv("USERPROFILE", str(home))
55
+ monkeypatch.setenv("HERMES_HOME", str(home / ".hermes"))
56
+ monkeypatch.delenv("SIBYL_MEMORY_DB", raising=False)
57
+ patch_trusted_keys(monkeypatch, test_signer)
58
+ # The CLI's own defaults point at an EMPTY directory (as the suite always
59
+ # had: no credentials unless a test writes them), while the SDK's default
60
+ # home (~/.sibyl-memory) is activated, because test code that SEEDS a store
61
+ # through MemoryClient (what an agent does) needs an account.
62
+ d = home / "cli-default"
63
+ monkeypatch.setattr(cli, "DEFAULT_CRED_PATH", d / "credentials.json")
64
+ monkeypatch.setattr(cli, "DEFAULT_DB_PATH", d / "memory.db")
65
+ monkeypatch.setattr(cli, "DEFAULT_TIER_CACHE_PATH", d / "tier_cache.json")
66
+ monkeypatch.setattr(cli, "_ENT_CRED_PATH", d / "credentials.json")
67
+ install_entitled_home(home, test_signer)
68
+ return home
69
+
70
+
71
+ # ---- network guard (0.9.0 gate fix) -----------------------------------------
72
+ # A previous build's suite reached the production api by accident. The guard is
73
+ # installed at conftest import (so collection-time code is covered too), stays
74
+ # installed for the whole session (the session fixture above re-applies it), and
75
+ # EVERY test fails if it made a refused non-loopback connection or name lookup,
76
+ # even one it caught and ignored. tests/test_network_guard_2026_09_27.py proves
77
+ # the guard itself.
78
+ from sibyl_memory_client.testing import ( # noqa: E402
79
+ assert_no_external_attempts as _assert_no_external_attempts,
80
+ forbid_external_network as _forbid_external_network,
81
+ refused_connections as _refused_connections,
82
+ )
83
+
84
+ _IMPORT_TIME_GUARD = pytest.MonkeyPatch()
85
+ _forbid_external_network(_IMPORT_TIME_GUARD)
86
+
87
+
88
+ @pytest.fixture(autouse=True)
89
+ def _no_external_network_attempts():
90
+ start = len(_refused_connections())
91
+ yield
92
+ _assert_no_external_attempts(start)
93
+
94
+
95
+ # ---- real-home guard (save/debloat build 2026-09-27) --------------------------
96
+ # Every test must see a temporary HOME (asserted per test), and at session end
97
+ # none of the paths the save/debloat build writes (skills, lifecycle, hooks,
98
+ # shims) may have changed under the account's real home.
99
+ from sibyl_memory_client.testing import ( # noqa: E402
100
+ assert_home_is_not_real as _assert_home_is_not_real,
101
+ real_home_changes as _real_home_changes,
102
+ real_home_snapshot as _real_home_snapshot,
103
+ )
104
+
105
+ _REAL_HOME_BEFORE = _real_home_snapshot()
106
+
107
+
108
+ @pytest.fixture(autouse=True)
109
+ def _home_is_never_the_real_home(_isolated_home):
110
+ _assert_home_is_not_real()
111
+ yield
112
+ _assert_home_is_not_real()
113
+
114
+
115
+ def pytest_sessionfinish(session, exitstatus):
116
+ changed = _real_home_changes(_REAL_HOME_BEFORE)
117
+ if changed:
118
+ print(f"\nREAL HOME CHANGED during the test session: {changed}")
119
+ session.exitstatus = 1
120
+
121
+
122
+ # ---- agent handoff (spec agent-handoff-messages 2026-10-03, 4.1 / 4.2) -------
123
+ # `handoff(out)` parses the convention block from captured stdout;
124
+ # `assert_convention(out, err)` is the lint every stop must pass.
125
+ import re as _re # noqa: E402
126
+
127
+ HANDOFF_KEYS = ("later: ", "ask your human: ", "next: ")
128
+ _NEXT_PREFIXES = ("sibyl ", "pip ", "pipx ", "claude ", "sibyl-memory-hermes ")
129
+ _NEXT_WORDS = ("done", "retry", "sibyl-memory-mcp")
130
+ _PLACEHOLDER = _re.compile(r"<[a-z_|\-]+>")
131
+
132
+
133
+ def handoff(out: str) -> dict:
134
+ """Parse the convention block from captured stdout. Raises if the last
135
+ non-empty line is not `next:`; returns {next, human, later: [...], waiting,
136
+ block: [lines]}. `waiting` lists every `waiting:` line anywhere in out."""
137
+ lines = [ln for ln in out.splitlines()]
138
+ while lines and not lines[-1].strip():
139
+ lines.pop()
140
+ if not lines or not lines[-1].startswith("next: "):
141
+ raise AssertionError(f"last non-empty line is not `next:`: {lines[-1:]!r}")
142
+ block = []
143
+ for ln in reversed(lines):
144
+ if ln.startswith(HANDOFF_KEYS):
145
+ block.insert(0, ln)
146
+ else:
147
+ break
148
+ human = [ln[len("ask your human: "):] for ln in block if ln.startswith("ask your human: ")]
149
+ return {
150
+ "next": block[-1][len("next: "):],
151
+ "human": human[0] if human else None,
152
+ "later": [ln[len("later: "):] for ln in block if ln.startswith("later: ")],
153
+ "waiting": [ln for ln in out.splitlines() if ln.startswith("waiting: ")],
154
+ "block": block,
155
+ }
156
+
157
+
158
+ def json_handoff(payload: dict) -> dict:
159
+ assert "next" in payload and "human_action" in payload, payload
160
+ return payload
161
+
162
+
163
+ def _next_ok(value: str) -> bool:
164
+ if value in _NEXT_WORDS:
165
+ return True
166
+ if _re.fullmatch(r"retry in \d+ minutes", value):
167
+ return True
168
+ return value.startswith(_NEXT_PREFIXES)
169
+
170
+
171
+ def assert_convention(out: str, err: str = "") -> dict:
172
+ """The 4.2 lint: last line `next:`; at most one `ask your human:`, directly
173
+ above `next:`; `later:` lines first; a placeholder needs an ask line; no
174
+ ANSI, no indentation, no em dash in the block; the `next` grammar; nothing
175
+ on stderr."""
176
+ h = handoff(out)
177
+ block = h["block"]
178
+ kinds = ["later" if b.startswith("later: ") else "ask" if b.startswith("ask your human: ")
179
+ else "next" for b in block]
180
+ assert kinds.count("next") == 1, block
181
+ assert kinds.count("ask") <= 1, block
182
+ if "ask" in kinds:
183
+ assert kinds[-2] == "ask", block
184
+ assert kinds == sorted(kinds, key=["later", "ask", "next"].index), block
185
+ for b in block:
186
+ assert "\x1b" not in b and b == b.lstrip() and "\u2014" not in b, b
187
+ for b in block:
188
+ if b.startswith(("later: ", "next: ")) and _PLACEHOLDER.search(b):
189
+ assert h["human"], f"placeholder without an ask line: {block}"
190
+ assert _next_ok(h["next"]), h["next"]
191
+ assert err == "", err
192
+ return h
193
+
194
+
195
+ @pytest.fixture(autouse=True)
196
+ def _reset_untrusted_base_note(monkeypatch):
197
+ """The untrusted-base explanation prints once per process (follow-up D1);
198
+ each test is its own process for that purpose."""
199
+ try:
200
+ from sibyl_memory_cli import cli as _cli
201
+ except Exception: # pragma: no cover
202
+ return
203
+ monkeypatch.setattr(_cli, "_UNTRUSTED_NOTED", set())
sibyl-memory-cli/tests/fixtures/deepseek/bom.yml ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ # with a BOM
2
+ []
sibyl-memory-cli/tests/fixtures/deepseek/broken.yml ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ - insert: [
2
+ - id: x
sibyl-memory-cli/tests/fixtures/deepseek/broken_with_fake_value.yml ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ - insert:
2
+ - id: sibyl-memory
3
+ config: {env: {GITHUB_TOKEN: FAKESECRET123 ]]]
sibyl-memory-cli/tests/fixtures/deepseek/comment_only.yml ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ # only comments here
2
+ # nothing else
sibyl-memory-cli/tests/fixtures/deepseek/crlf.yml ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ - id: some-builtin-row
2
+ config:
3
+ theme: dark
sibyl-memory-cli/tests/fixtures/deepseek/debian_dsh_home/dsh.conf ADDED
@@ -0,0 +1 @@
 
 
1
+ verbose = 1
sibyl-memory-cli/tests/fixtures/deepseek/debian_dsh_home/group/all ADDED
@@ -0,0 +1 @@
 
 
1
+ host1
sibyl-memory-cli/tests/fixtures/deepseek/debian_dsh_home/machines.list ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ host1
2
+ host2
sibyl-memory-cli/tests/fixtures/deepseek/duplicate_in_file.yml ADDED
@@ -0,0 +1,11 @@
 
 
 
 
 
 
 
 
 
 
 
 
1
+ - insert:
2
+ - id: sibyl-memory
3
+ name: '@deepseek-ai/dsh-mcp-client'
4
+ config:
5
+ serverName: sibyl-memory
6
+ command: "/a/sibyl-memory-mcp"
7
+ - id: sibyl-memory-2
8
+ name: '@deepseek-ai/dsh-mcp-client'
9
+ config:
10
+ serverName: sibyl-memory-2
11
+ command: "/b/sibyl-memory-mcp"
sibyl-memory-cli/tests/fixtures/deepseek/flow_list.yml ADDED
@@ -0,0 +1 @@
 
 
1
+ [{id: x, disabled: true}]
sibyl-memory-cli/tests/fixtures/deepseek/foreign_flow_row.yml ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ - insert:
2
+ - {id: sibyl-memory, name: '@deepseek-ai/dsh-mcp-client', config: {serverName: engram, command: engram}}
sibyl-memory-cli/tests/fixtures/deepseek/foreign_same_id.yml ADDED
@@ -0,0 +1,16 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # keep this comment
2
+ - insert:
3
+ - id: sibyl-memory
4
+ name: '@deepseek-ai/dsh-mcp-client'
5
+ config:
6
+ serverName: engram
7
+ transport: stdio
8
+ command: engram
9
+ args: [mcp]
10
+ env:
11
+ ENGRAM_DIR: /data/engram
12
+ cwd: !!js process.cwd()
13
+ - id: after-row
14
+ name: other
15
+ - id: tail-override
16
+ config: {a: 1}
sibyl-memory-cli/tests/fixtures/deepseek/indented_list.yml ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ - id: indented
2
+ config: {a: 1}