diff --git a/hermes_state.py b/hermes_state.py index d118f536eb6..f1015a15b14 100644 --- a/hermes_state.py +++ b/hermes_state.py @@ -820,6 +820,16 @@ class SessionDB: _WRITE_RETRY_MAX_S = 0.150 # 150ms # Attempt a PASSIVE WAL checkpoint every N successful writes. _CHECKPOINT_EVERY_N_WRITES = 50 + # Merge fragmented FTS5 segments every N successful writes. The message + # triggers append one segment per insert; left unmaintained these grow + # into tens of thousands of segments, so every MATCH must scan them all + # and every insert pays a growing automerge cost — which lengthens the + # write-lock hold time and starves competing writers (gateway + cron + # processes share one state.db), surfacing as "database is locked". + # 'optimize' is a no-op once the index is already merged, so an idle DB + # pays almost nothing; the cadence is deliberately coarse so the one-off + # merge cost is amortised far below the checkpoint cadence. + _OPTIMIZE_EVERY_N_WRITES = 1000 def __init__(self, db_path: Path = None, read_only: bool = False): self.db_path = db_path or DEFAULT_DB_PATH @@ -1088,10 +1098,12 @@ class SessionDB: except Exception: pass raise - # Success — periodic best-effort checkpoint. + # Success — periodic best-effort checkpoint + FTS merge. self._write_count += 1 if self._write_count % self._CHECKPOINT_EVERY_N_WRITES == 0: self._try_wal_checkpoint() + if self._write_count % self._OPTIMIZE_EVERY_N_WRITES == 0: + self._try_optimize_fts() return result except sqlite3.OperationalError as exc: err_msg = str(exc).lower() @@ -1142,6 +1154,22 @@ class SessionDB: except Exception: pass # Best effort — never fatal. + def _try_optimize_fts(self) -> None: + """Best-effort FTS5 segment merge. Never raises. + + Runs on the ``_OPTIMIZE_EVERY_N_WRITES`` cadence from the write hot + path (off the lock — ``optimize_fts`` re-acquires ``self._lock`` + itself, mirroring ``_try_wal_checkpoint``). ``read_only`` connections + never reach the write path, so this is implicitly skipped for them. + Once the index is merged the 'optimize' command is close to free, so + the steady-state cost is negligible; the expensive case is only the + first merge of a long-neglected index. + """ + try: + self.optimize_fts() + except Exception: + pass # Best effort — never fatal. + def close(self): """Close the database connection. diff --git a/tests/test_hermes_state.py b/tests/test_hermes_state.py index d79fb95303f..98cdd83ed29 100644 --- a/tests/test_hermes_state.py +++ b/tests/test_hermes_state.py @@ -3838,6 +3838,40 @@ class TestOptimizeFts: # Search still works after repeated optimization. assert len(db.search_messages("repeat")) == 1 + def test_write_path_optimizes_fts_on_cadence(self, db, monkeypatch): + """Writes periodically merge FTS segments so they never accumulate + into the tens-of-thousands that lengthen the write-lock hold and + starve competing writers ("database is locked").""" + db._OPTIMIZE_EVERY_N_WRITES = 5 + calls = {"n": 0} + real_optimize = db.optimize_fts + + def _counting_optimize(): + calls["n"] += 1 + return real_optimize() + + monkeypatch.setattr(db, "optimize_fts", _counting_optimize) + # create_session is write #1; appends are #2.. -> #5 and #10 trigger. + db.create_session(session_id="s1", source="cli") + for i in range(9): + db.append_message(session_id="s1", role="user", content=f"needle {i}") + assert calls["n"] == 2 + # The auto-merge is layout-only: search is unaffected. + assert len(db.search_messages("needle")) == 9 + + def test_write_path_optimize_failure_never_breaks_write(self, db, monkeypatch): + """A failing periodic optimize must not fail the surrounding write.""" + db._OPTIMIZE_EVERY_N_WRITES = 2 + + def _boom(): + raise sqlite3.OperationalError("simulated optimize failure") + + monkeypatch.setattr(db, "optimize_fts", _boom) + db.create_session(session_id="s1", source="cli") # write #1 + # write #2 trips the cadence; the swallowed failure must not propagate. + db.append_message(session_id="s1", role="user", content="still persists") + assert len(db.get_messages("s1")) == 1 + class TestAutoMaintenance: def _make_old_ended(self, db, sid: str, days_old: int = 100):