fix(session): survive, prevent, and explain missing SQLite FTS5 by teknium1 · Pull Request #35103 · NousResearch/hermes-agent

teknium1 · 2026-05-30T02:55:40Z

Summary

Hermes no longer dies with Could not open session database: no such module: fts5 on installs whose bundled SQLite lacks FTS5, and the supported installer now guarantees an FTS5-capable Python so it doesn't happen in the first place.

Three layers:

Survive it — SessionDB opens without FTS5, keeping session/message persistence and disabling only full-text search.
Prevent it — install.sh probes the resolved uv-managed Python for FTS5 and reinstalls a current build if a stale one lacks it.
Explain it — when FTS5 is genuinely missing at runtime, the warning names the likely cause (unsupported / pip-managed Python) and links the supported install.

Supersedes #10972 — includes @LeonSGP43's graceful-degradation commit (authorship preserved) plus follow-ups. Fixes #10897.

Root cause

SessionDB.__init__ unconditionally runs CREATE VIRTUAL TABLE ... USING fts5(...). SQLite builds compiled without the FTS5 module raise OperationalError: no such module: fts5, which propagated out of __init__ and took down the entire session store. uv's python-build-standalone distributions only gained FTS5 in mid-2025 (astral-sh/python-build-standalone#694), so a stale interpreter already in uv's store — which uv python find reuses without checking — can ship a SQLite 3.49.x without FTS5.

Changes

hermes_state.py: _fts_enabled flag; guard both messages_fts and the messages_fts_trigram CJK index so an FTS5-unavailable error degrades (one warning) instead of raising. search_messages() early-returns [] when disabled. Warning now points at the supported install.
scripts/install.sh: _python_has_fts5() probe + ensure_fts5() — after check_python resolves an interpreter, verify FTS5; if missing, uv python install <ver> --reinstall and re-resolve. Warns and continues if an FTS5 build still can't be obtained (offline / pinned env).
tests/test_hermes_state.py: regression test simulating a no-FTS5 SQLite runtime; mock fails both virtual tables so the test exercises a faithful no-FTS5 build.

Validation

	Before	After
Init on no-FTS5 build	`OperationalError` (DB unusable)	opens, `_fts_enabled=False`, one actionable warning
Session/message persistence	dead	works
`search_messages()` (no FTS5)	n/a	`[]`
`optimize_fts()` (no FTS5)	n/a	safe no-op
Normal FTS5 build	works	unchanged (`_fts_enabled=True`, search hits)
Supported install w/ stale Python	silently no FTS5	reinstalls to an FTS5 build

Installer probe verified both ways against real interpreters (true-positive on FTS5 python, true-negative on a simulated no-FTS5 one); runtime path E2E-verified with real imports; targeted tests 4/4.

Closes #10897. Supersedes #10972.

Infographic

The salvaged contributor commit guarded only messages_fts. Current main also creates a second virtual table, messages_fts_trigram (CJK substring search), whose CREATE VIRTUAL TABLE ... USING fts5 still raised "no such module: fts5" on builds without FTS5 — re-crashing SessionDB init. Wrap the trigram setup with the same guard, and broaden the test's no-fts5 mock to fail BOTH tables so the regression test actually exercises a faithful no-FTS5 build.

uv's python-build-standalone distributions only gained FTS5 in mid-2025 (#694). A stale interpreter already in uv's store — which `uv python find` reuses without checking — can lack it, leaving the supported install with a SQLite that can't create the FTS5 virtual tables hermes_state.py needs for full-text session search ("no such module: fts5"). check_python now probes the resolved interpreter for FTS5 and, if missing, reinstalls the latest patch for $PYTHON_VERSION (which has FTS5) and re-resolves. If an FTS5-capable Python still can't be obtained (offline, pinned env), it warns and continues — Hermes degrades gracefully and only disables session search. No bundled second SQLite, no user action.

When FTS5 is missing the warning now explains the likely cause (an unsupported / pip-managed Python whose bundled SQLite lacks FTS5) and links the supported install at hermes-agent.nousresearch.com, instead of just logging the raw error.

github-actions · 2026-05-30T02:56:29Z

🔎 Lint report: `fix/installer-ensure-fts5` vs `origin/main`

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 9466 on HEAD, 9466 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 4919 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.

obtitus · 2026-05-30T05:53:22Z

I tried testing this and it seems to not work as intended. Workaround (posted on discord) works:

$ uv python uninstall cpython-3.11.13-linux-x86_64-gnu # remove the 'broken' python bundled with uv
$ sudo apt-get install python3.11 # install system python, fts5 capable
$ cd ~/.hermes/hermes-agent
$ rm -r venv
$ ./setup-hermes.sh
$ ./venv/bin/python test_script.py
sqlite version 3.45.1
version 2.6.0
path: /usr/lib/python3.11/sqlite3/__init__.py
FTS5 results: [('Python Tutorial', 'Learn SQLite FTS5 in Python.')
$ hermes sessions list
No sessions found.

Removing my workaround by deleting the working system python:

$ sudo apt-get uninstall python3.11 && sudo apt autoremove
$ apt list --installed | grep python3.11
<empty>
$ rm -r ~/.hermes/hermes-agent/venv

$ hermes update
$ hermes debug share
Upload failed: Failed to upload to any paste service:
  paste.rs: <urlopen error [Errno 101] Network is unreachable>
  dpaste.com: <urlopen error [Errno 101] Network is unreachable>

Full report printed below — copy-paste it manually:

[hermes debug share: log content redacted at upload time. run with --no-redact to disable]
--- hermes dump ---
version:          0.15.1 (2026.5.29) [aa32edca]
os:               Linux 6.8.0-62-generic x86_64
python:           3.11.13
openai_sdk:       2.24.0
profile:          default
hermes_home:      ~/.hermes
$ ./venv/bin/python test_script.py # Now I am back to uv managed python3.11 which fails:
sqlite version 3.49.1
version 2.6.0
path: /home/ob/.local/share/uv/python/cpython-3.11.13-linux-x86_64-gnu/lib/python3.11/sqlite3/__init__.py
Traceback (most recent call last):
  File "/home/ob/tmp/explore_hermes_db.py", line 14, in <module>
    cursor.execute("CREATE VIRTUAL TABLE posts USING fts5(title, body);")
sqlite3.OperationalError: no such module: fts5
$ hermes	sessions list # Is this not supposed to gracefully fallback?
Error: Could not open session database: no such module: fts5

I manually checked ~/.hermes/hermes-agent/install.sh and it does have the fix in this PR. I can get my system working again, so I am providing this just to help others.

…roken install NousResearch#35103

obtitus · 2026-05-30T06:47:19Z

Took a stab at the "survive" part of this PR and simplified it a bit so its actually working, let me know if I should open a PR: main...obtitus:hermes-agent:fix/survive-missing-fts5

Note: This does not fix the missing fts5 when using uv installed python, but ensure you can still use e.g. hermes sessions list without crashing

LeonSGP43 and others added 4 commits May 29, 2026 19:51

fix(session): degrade gracefully when SQLite lacks FTS5

7bc4a16

teknium1 mentioned this pull request May 30, 2026

fix(session): degrade gracefully when SQLite lacks FTS5 #35086

Closed

alt-glitch added type/bug Something isn't working comp/agent Core agent loop, run_agent.py, prompt builder P1 High — major feature broken, no workaround labels May 30, 2026

teknium1 merged commit a7421dc into main May 30, 2026
23 checks passed

teknium1 deleted the fix/installer-ensure-fts5 branch May 30, 2026 03:11

obtitus added a commit to obtitus/hermes-agent that referenced this pull request May 30, 2026

simplify fts5 survive path so hermes sessions list still works on a b…

34e6e9e

…roken install NousResearch#35103

helix4u mentioned this pull request May 30, 2026

fix(session): survive missing FTS5 runtimes #35452

Merged

19 tasks

teknium1 mentioned this pull request May 30, 2026

fix(install): refresh stale uv so installs actually get FTS5 Python #35541

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(session): survive, prevent, and explain missing SQLite FTS5#35103

fix(session): survive, prevent, and explain missing SQLite FTS5#35103
teknium1 merged 4 commits into
mainfrom
fix/installer-ensure-fts5

teknium1 commented May 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 30, 2026

Uh oh!

Uh oh!

obtitus commented May 30, 2026

Uh oh!

obtitus commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

teknium1 commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root cause

Changes

Validation

Infographic

Uh oh!

github-actions Bot commented May 30, 2026

🔎 Lint report: fix/installer-ensure-fts5 vs origin/main

ruff

ty (type checker)

Uh oh!

Uh oh!

obtitus commented May 30, 2026

Uh oh!

obtitus commented May 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

teknium1 commented May 30, 2026 •

edited

Loading

🔎 Lint report: `fix/installer-ensure-fts5` vs `origin/main`