chore: catch fork main up to upstream v0.21.0-rc2 (47 commits behind)

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -44,7 +44,7 @@ body:
     attributes:
       label: Version and branch
       description: hermes-lcm version, branch, commit, or release tag.
-      placeholder: v0.20.0, main, or commit SHA
+      placeholder: v0.21.0-rc2, main, or commit SHA
     validations:
       required: true
 

.github/release-notes/v0.21.0-rc1.md

@@ -0,0 +1,25 @@
+# hermes-lcm v0.21.0-rc1
+
+Lossless Context Management for Hermes: an RC for the merged experience-memory, exact-evidence, citable-retrieval, and large-store reliability wave.
+
+## Highlights
+
+- Adds the trajectory/experience-memory subsystem plus opt-in assertion, query-view, pre-answer evidence, and adaptive-retrieval paths; stock installs retain the previous behavior until operators enable those paths.
+- Keeps the core SQLite schema at version 5. New feature stores use additive named migrations in the same profile database; existing v0.20 databases need no manual migration or embedding backfill.
+- Hardens large-store and startup behavior with bounded vector/metadata work, WAL-conversion lock retry, and eventual background temporal-rollup maintenance.
+- Carries reference-strict citable delivery, direct source identity for summary recall hits, and configurable query embedding spend limits. Committed benchmark results apply only to their documented harness and corpus.
+
+## Changes
+
+- #436 Consolidate trajectory/experience memory, exact evidence, citable retrieval, privacy, scaling, and release-validation work.
+- #361 Retry WAL conversion on lock contention during connection setup.
+- #440 Defer temporal-rollup maintenance from the session-start critical path.
+- #446 Batch embedding-backfill fixture setup for release-scale validation.
+- #447 Batch large vector-metadata fixture setup for release-scale validation.
+
+## Contributors
+
+- @stephenschoettler
+- @100yenadmin
+- @ai-ag2026
+- @Tosko4

.github/release-notes/v0.21.0-rc2.md

@@ -0,0 +1,16 @@
+# hermes-lcm v0.21.0-rc2
+
+Lossless Context Management for Hermes: a release candidate limited to the merged CJK-safe trajectory-state token chunking correction.
+
+## Highlights
+
+- Preserves UTF-8 character boundaries when the optional `tiktoken` path splits oversized trajectory-state documents.
+- Keeps each decoded chunk within the requested token budget and fails explicitly when that budget cannot contain one complete Unicode character.
+
+## Changes
+
+- #492 corrects fixed-width token-ID slicing that could split a multibyte character and introduce U+FFFD replacement characters when chunks were decoded independently.
+
+## Contributors
+
+- @stephenschoettler

.github/workflows/release.yml

@@ -15,49 +15,19 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Generate changelog
-        id: changelog
-        env:
-          GH_TOKEN: ${{ github.token }}
+      - name: Validate curated release notes
         run: |
-          CURRENT_TAG="${{ github.ref_name }}"
-          PREV_TAG=$(git tag --sort=-v:refname | grep -Fxv "$CURRENT_TAG" | head -1)
-
-          if [ -z "$PREV_TAG" ]; then
-            RANGE="$CURRENT_TAG"
-          else
-            RANGE="$PREV_TAG..$CURRENT_TAG"
-          fi
-
-          echo "body<<EOF" >> "$GITHUB_OUTPUT"
-
-          if [ -z "$PREV_TAG" ]; then
-            echo "Initial release." >> "$GITHUB_OUTPUT"
-          else
-            git log --pretty=format:"- %s (%h)" "$RANGE" >> "$GITHUB_OUTPUT"
+          NOTES_FILE=".github/release-notes/${GITHUB_REF_NAME}.md"
+          if [ ! -s "$NOTES_FILE" ]; then
+            echo "Missing curated release notes: $NOTES_FILE" >&2
+            exit 1
           fi
 
-          echo "" >> "$GITHUB_OUTPUT"
-          echo "## Contributors" >> "$GITHUB_OUTPUT"
-          if [ -n "$PREV_TAG" ]; then
-            CONTRIBUTORS=$(curl -fsSL \
-              -H "Authorization: Bearer ${GH_TOKEN}" \
-              -H "Accept: application/vnd.github+json" \
-              "https://api.github.com/repos/${{ github.repository }}/compare/${PREV_TAG}...${CURRENT_TAG}" \
-              | jq -r '[.commits[].author.login // empty] | unique | .[] | "- @\(.)"')
-            if [ -n "$CONTRIBUTORS" ]; then
-              printf '%s\n' "$CONTRIBUTORS" >> "$GITHUB_OUTPUT"
-            else
-              echo "- No GitHub usernames found" >> "$GITHUB_OUTPUT"
-            fi
-          else
-            echo "- No GitHub usernames found" >> "$GITHUB_OUTPUT"
-          fi
-
-          echo "EOF" >> "$GITHUB_OUTPUT"
-
       - name: Create GitHub Release
         uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
         with:
-          body: ${{ steps.changelog.outputs.body }}
+          body_path: .github/release-notes/${{ github.ref_name }}.md
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          make_latest: ${{ contains(github.ref_name, '-') && 'false' || 'true' }}
           generate_release_notes: false

CHANGELOG.md

@@ -4,13 +4,62 @@ This repo also publishes GitHub Releases. This file is the repo-root release sur
 
 ## Unreleased
 
-## v0.20.0 - 2026-07-29
-
-Release focus: benchmark-driven retrieval scaling, evidence provenance, and bounded query embedding spend.
-
-- Removed the large-corpus recall ceilings by scanning the full summary and chunk corpora in bounded batches and sanitizing raw natural-language FTS queries before fallback. (#169)
-- Made the query-path embedding spend guard configurable with a generous default while preserving the exempt backfill contract. (stephenschoettler/hermes-lcm#434)
-- Preserved a direct source `store_id` on summary recall hits so strict evidence renderers can validate their source identity. (#164)
+No additional changes yet.
+
+## v0.21.0-rc2 - 2026-08-05
+
+### Changed
+
+- #492 corrects the optional `tiktoken` trajectory-state chunking path to
+  preserve UTF-8 character boundaries while keeping each decoded chunk within
+  its token budget. If the budget cannot contain one complete Unicode
+  character, the path fails explicitly instead of emitting replacement
+  characters.
+
+## v0.21.0-rc1 - 2026-08-03
+
+### Highlights
+
+- Add the trajectory/experience-memory subsystem and the opt-in assertion,
+  evidence, query-view, and adaptive-retrieval surfaces delivered by the
+  consolidated wave-1 merge (#436).
+- Keep the core SQLite schema at version 5. New feature stores use additive,
+  named migrations in the same profile database, while disabled/default-off
+  installs do not create optional assertion, query-view, or embedding tables.
+- Improve large-store and startup behavior with bounded vector/metadata work,
+  lock-contention retry during WAL conversion, and deferred temporal-rollup
+  maintenance (#361, #440, #446, #447).
+
+### Changed
+
+- #436 adds the consolidated trajectory/experience-memory, retrieval,
+  exact-evidence, citable-delivery, privacy, scale, and release-validation wave.
+  Its committed benchmark results are directional evidence for the documented
+  harness and corpus, not universal provider or workload guarantees.
+- #361 retries WAL conversion when connection setup meets lock contention.
+- #440 moves temporal-rollup maintenance off the session-start critical path;
+  bounded background work is eventual and `lcm_recent` retains its fallback.
+- #446 and #447 batch large fixture setup for embedding/vector metadata release
+  coverage without changing runtime behavior.
+
+### Upgrade notes
+
+- Back up `lcm.db`, update the plugin checkout, restart Hermes, send one normal
+  message, then verify `plugin_version: 0.21.0-rc1` and the expected database
+  path with `lcm_status`. The core schema remains version 5.
+- No manual core migration or embedding backfill is required from v0.20.0.
+- Query/evidence tool schemas are exposed after upgrade, but assertion
+  extraction, assertion storage, query-view storage, pre-answer evidence, and
+  adaptive retrieval remain opt-in. Review provider/privacy boundaries before
+  enabling model- or embedding-backed paths.
+
+## v0.20.0 - 2026-07-23
+
+Release focus: Lossless-Claw parity plus the merged cross-session recall and temporal retrieval stack.
+
+- Completed the five selected Lossless-Claw parity behaviors: recoverable active-replay stubs for large externalized tool results; token-bounded fresh tails that preserve the newest message and complete tool-call/result groups; dry-run-first historical tool-output backfill with guarded rollback; bounded active-session externalized-payload search with strict ownership and recoverability checks; and bounded atomic threshold full sweeps with one final active-context publication. (#380, #381, #382, #413)
+- Shipped the merged #413 recall and temporal surface: `lcm_recall`, `lcm_recent`, and `lcm_load_session`; semantic and hybrid retrieval over summaries and message chunks; temporal rollups with bounded fallback; optional proactive recall; and the corresponding benchmark and reproduction documentation.
+- Release boundary: stock installs keep large-output externalization, active-replay stubbing, embeddings, temporal rollups, proactive recall, and threshold full sweeps disabled by default. Payload search requires explicit `content_scope`; historical backfill remains an operator-invoked, dry-run-first command. Committed benchmark results are directional evidence under their documented model and harness, not a universal provider-parity claim. This release does not include the later work tracked in #423, #434, or #436.
 
 ## v0.19.0 - 2026-07-07
 

FINDINGS-VERDICTS-UP1.md

@@ -0,0 +1,13 @@
+# FINDINGS-VERDICTS-UP1
+- Source head: `ccc76ee4f30fa6203d50e73fb0eeb0eb8983b2aa`; branch `fix/upstream-followup-1`.
+- 3649814070 VALIDATED/FIXED: finite coverage now counts distinct grounded `exact_ref` values.
+- 3672539167 VALIDATED/FIXED: hit CAS checks generation/rowcount and re-reads readiness before returning `hit`.
+- 3672539173 VALIDATED/FIXED: persisted slot refs are intersected with the selected evidence set.
+- 3668416705 VALIDATED/FIXED: existing trajectory schema version is rejected before schema/FTS repair DDL.
+- 3672539191 VALIDATED/FIXED: deadline-expired paths skip `COUNT(*)`; in-memory totals remain meaningful.
+- Focused regressions: 9 passed; see `laneUP1-logs/focused-up1.xml`.
+- Ruff: whole repository clean; see `laneUP1-logs/ruff-up1.txt`.
+- Full suite: 2709 passed, 35 failed, 1 skipped, 12 xfailed; 0 new and 0 missing failure names vs baseline.
+- Full-suite evidence: `laneUP1-logs/full-suite-up1.xml` and `full-suite-up1-comparison.txt`.
+- Surface verdict: no validation evidence contradicted the NON-V1-delivery triage classification.
+- No push, merge, release, deploy, or runtime mutation performed.

README.md

@@ -195,17 +195,17 @@ Expected signals:
 
 - plugin list includes `hermes-lcm`
 - selected context engine is `lcm`
-- tool list includes `lcm_grep`, `lcm_load_session`, `lcm_describe`,
-  `lcm_expand`, `lcm_expand_query`, `lcm_status`, `lcm_inspect`, and
-  `lcm_doctor`
+- tool list includes `lcm_grep`, `lcm_recall`, `lcm_recent`,
+  `lcm_load_session`, `lcm_describe`, `lcm_expand`, `lcm_expand_query`,
+  `lcm_status`, `lcm_inspect`, and `lcm_doctor`
 - the normal available-skills index includes `hermes-lcm`; current hosts can
   also resolve the explicit plugin-qualified skill `hermes-lcm:hermes-lcm`
 
 Typical output:
 
 ```text
 Plugins (1):
-  ✓ hermes-lcm v0.20.0 (8 tools)
+  ✓ hermes-lcm v0.21.0-rc2 (15 tools)
 
 Provider Plugins:
   Context Engine: lcm
@@ -218,7 +218,7 @@ best-effort git identity:
 
 If startup logs say LCM tools are available through `context-engine schemas` or
 mention the `Path B fallback`, that is expected on older Hermes hosts such as
-Hermes Agent v0.16. The seven `lcm_*` tools remain available through the
+Hermes Agent v0.16. All 15 `lcm_*` tools remain available through the
 context-engine path; standalone plugin-registry registration is not required
 there.
 
@@ -244,6 +244,17 @@ If you installed a symlink from a separate checkout:
 
 Restart Hermes after updating.
 
+For the `v0.21.0-rc2` line, take a normal backup of `lcm.db` before updating,
+then update the checkout and restart Hermes. No manual core migration or
+backfill is required: the core schema remains version 5. New assertion,
+query-view, and adaptive-retrieval state is additive, created only after the
+corresponding opt-in is enabled, and stored in the same profile database under
+named feature markers. The five new query/evidence tool schemas are visible in
+the tool list on stock installs, but automatic extraction, pre-answer evidence,
+assertion storage, query-view storage, and adaptive retrieval remain off. See
+[the operator upgrade and opt-in notes](docs/operator-guide.md#upgrade-from-v0200-to-v0210-rc2)
+before enabling them.
+
 ## Commands and tools
 
 ### Agent tools

__init__.py

@@ -186,6 +186,9 @@ def _pre_llm_context(active_engine, recall_policy: str, payload: dict) -> dict:
             contract = compile_answer_contract(question, question_date)
             if contract.status != "planned":
                 return {"context": recall_policy}
+            baseline_was_internal = not isinstance(
+                payload.get("baseline_refs"), (list, tuple)
+            )
             baseline_refs = _answer_ready_baseline(active_engine, question, payload)
             result = compile_preanswer_evidence(
                 question,
@@ -196,6 +199,7 @@ def _pre_llm_context(active_engine, recall_policy: str, payload: dict) -> dict:
                     "lcm_recall", recall_args
                 ),
                 enabled=True,
+                render_baseline_context=baseline_was_internal,
             )
             try:
                 active_engine._last_preanswer_evidence_trace = result
@@ -258,6 +262,7 @@ def _pre_llm_context(active_engine, recall_policy: str, payload: dict) -> dict:
                     question,
                     baseline_refs=compiler_refs,
                     question_date=question_date,
+                    engine=active_engine,
                 )
                 if prepared["status"] == "selector_required":
                     proposal, selector_usage = call_selective_auxiliary_selector(

adaptive_retrieval.py

@@ -22,6 +22,7 @@
 import uuid
 
 from .query_view_store import (
+    CorpusSnapshot,
     QueryViewBuildInProgressError,
     QueryViewIdentity,
     QueryViewStore,
@@ -333,6 +334,7 @@ class RetrievalState:
     view_delta_events: tuple[dict[str, Any], ...] = ()
     view_delta_truncated: bool = False
     cached_trace: dict[str, Any] | None = None
+    view_corpus_snapshot: CorpusSnapshot | None = None
 
 
 def _parse_requirements(raw: Any) -> tuple[EvidenceRequirement, ...]:
@@ -902,6 +904,11 @@ def start(
                 created_at=now,
                 updated_at=now,
                 slot_refs={item.slot_id: [] for item in parsed_requirements},
+                view_corpus_snapshot=(
+                    self._query_views.corpus_snapshot()
+                    if self._query_views is not None
+                    else None
+                ),
             )
             if self._query_views is not None:
                 lookup = self._query_views.lookup(parsed_identity, record_hit=False)
@@ -1188,7 +1195,10 @@ def _persist_view(
             return {"status": "skipped", "reason": "computation did not validate"}
         token = None
         try:
-            token = self._query_views.claim_build(state.identity)
+            token = self._query_views.claim_build(
+                state.identity,
+                corpus_snapshot=state.view_corpus_snapshot,
+            )
             dependencies = [
                 self._query_views.snapshot_dependency(
                     item.store_id,

answer_contract.py

@@ -380,6 +380,28 @@ def _named_operands(text: str, operation: str) -> tuple[str, ...]:
             )
             if len(values) == 2:
                 return values
+    if operation == "sum":
+        enumeration = re.search(
+            r"\b(?:spend|spent)\s+(?:on\s+)?(.{1,240}?)(?:\?|$)|"
+            r"\b(?:across|of|for|on)\s+(.{1,240}?)(?:\?|$)",
+            normalized,
+            re.IGNORECASE,
+        )
+        if enumeration:
+            tail = next(group for group in enumeration.groups() if group is not None)
+            parts = [part.strip() for part in tail.split(",")]
+            if len(parts) >= 3:
+                parts[-1] = re.sub(
+                    r"^(?:and|plus)\s+", "", parts[-1], flags=re.IGNORECASE
+                )
+                values = tuple(
+                    value
+                    for raw in parts
+                    if (value := _clean_operand(raw)) is not None
+                )
+                if len(values) == len(parts) and len(values) <= 8:
+                    return values
+                return ()
     pair = re.search(
         r"\b(?:spend|spent|across|between|from|of|for|doing|on)\s+(.{1,80}?)\s+"
         r"(?:and|plus)\s+(?:doing|on|the)?\s*(.{1,80}?)(?:\?|$)",
@@ -450,9 +472,9 @@ def _time_window(text: str, canonical_as_of: str | None) -> TemporalWindow | Non
             raw = rolling.group(1)
             amount = int(raw) if raw.isdigit() else _WORD_NUMBERS[raw]
             if rolling.group(2) == "day":
-                start = anchor - timedelta(days=amount)
+                start = anchor - timedelta(days=amount - 1)
             elif rolling.group(2) == "week":
-                start = anchor - timedelta(days=amount * 7)
+                start = anchor - timedelta(days=amount * 7 - 1)
             else:
                 month_index = anchor.year * 12 + anchor.month - 1 - amount
                 year, month_zero = divmod(month_index, 12)