Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

fix(hermes): bound long prefetch recall queries (#304)

Elysio Pires3742a2af9041
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4932350c..21c1ae27 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **A schema apply is attested on a machine that holds only `shared`.** A store-only apply writes its audit row to `shared`, beside the schema settings records it attests, so such a machine reports another device's apply as `ok` instead of `modified` or unverified. The shared row carries the attestation and the mutation list; the reason stays on the whole row in `private`, where audit rows always went on a machine that holds it, and a batch or reason that names a private page or carries a `<private>` region leaves only the attestation on the shared row.
- **Private evidence no longer moves a shared preference.** An `apply-evidence` event that lands in `private` because its note or artifact names a private page no longer confirms, quarantines, retires or re-scores a shared preference in dream or in the review candidates, and no longer turns the preference itself private, is copied as a private record by a merge and left out of the merge's sums, and no longer makes every dream pass rewrite the preference; it still counts toward a preference that is private, and in the counters a local caller of a machine that holds `private` reads; a remote MCP caller is shown the counters of the shared evidence alone.
- **The seen-shards ledger is updated under a device-local lock.** Two processes on one machine could interleave their read-modify-write of the ledger, so a tracking read could bring back entries `o2b store partition leave` had just cleared, or a leave could drop a shard another process had just recorded; every update now re-reads the ledger under the lock, and a lock left by a crashed process costs a process one short wait. The procedural usage file is read and written under its lock the same way, so a reconcile no longer drops a use another process counted.
+- **Hermes recalls on a long prompt instead of failing on its length.** Before the recall gate and the ranked context pack, the provider bounds a long turn to 2,000 code points while retaining its beginning and end, so the query stays within both tools' length limits; the reduction is logged without the prompt's contents, and skill attachment still receives the original turn. A turn that is blank after trimming, or a query that is not a string, is passed on unchanged as before, so the gate still refuses it and nothing is recalled.
- **The search index writer lock stays fresh through long synchronous work, and a writer that lost it no longer touches its successor's lock.** The lock's heartbeat ran on the event loop, so a holder blocked in synchronous work - a snapshot's `tar` or `zstd` run, the store archive's integrity scan and `VACUUM INTO`, the restore that holds the lock from its recovery point through the swap, an FTS rebuild, a migration, the index walk between embedding batches - left the lock untouched for longer than its 60-second stale window on a large vault, and a second writer took it over while the first was still writing. Each of those steps now keeps the lock fresh from a worker thread for a stated bound (the tool's kill timeout, or fifteen minutes for an in-process step without one), and the index walk refreshes it as it goes; past the bound the worker stops, so a holder wedged inside the step still goes stale and is taken over one window later, and a crashed or killed holder goes stale as before. Every refresh and the release first check that the lock is still the one this holder stamped (its mtime, which carries a random sub-millisecond fraction, and its inode): a lock another writer took over is never refreshed or removed, also at process exit, and neither is one so close to its stale window that a contender may be taking it over at that moment. Each protected step refuses with `INDEX_LOCKED` when the lock is not provably this holder's before it starts and again when it ends, and the holder's commits - the reindex swap, right before its first rename, and the restore swap, before the Brain renames and again before the store replacement, undoing the renames when the lock was lost in between - refuse with nothing touched instead of replacing what the other writer committed, and a write-mode store stops at the moment it sees the loss: its connection turns read-only and the loss is raised as `INDEX_LOCKED`, which from the heartbeat ends the process as the old lock library did. The brain store catch-up and the link and relation passes of an index run keep the lock fresh too. The on-disk lock is unchanged, so older releases on the same index exclude and are excluded by it; an older release still removes the lock without checking whose it is, which this release detects and refuses its commit on. `OPEN_SECOND_BRAIN_WRITER_LOCK_STALE_MS` sets the stale window (one minute by default, at most one day); the lock beats at least every 20 seconds whatever the window, so an older release never sees a live lock as stale, and a value below one minute is unsafe while an older release shares the index and is warned about.
- **Two Windows-flaky tests are fixed at their cause.** The hung and TERM-ignoring version-child tests read the child's pid from a shell `$$` that the 150 ms budget could cut off mid-write, and that is not the native pid on Windows; the child is now a Bun process that writes its native pid atomically, and a run whose child the budget cut off before it reported is repeated at a doubled budget instead of failing on a pid it never wrote. The concurrent `o2b store init` test started six full CLI processes at once and raced their startup against its 30-second budget on a loaded runner; six processes now load the init verb's handler, report ready and start together on one signal, so the test races the store creation itself and process start is no longer part of the race, and a racer never outlives the test.
diff --git a/plugins/hermes/provider.py b/plugins/hermes/provider.py
index 9f5d9a5e..11499658 100644
--- a/plugins/hermes/provider.py
+++ b/plugins/hermes/provider.py
@@ -153,6 +153,25 @@ _PREFETCH_RECEIPT_HOST = "hermes"
# relevance rather than filtering them, so a natural-language turn spends the
# budget on what matters instead of substring-missing every page.
_PREFETCH_QUERY_MODE = "ranked"
+# The ranked query limit counts Unicode codepoints; the gate counts UTF-16
+# code units. At most 2,000 codepoints also fit the gate's 4,000-unit limit.
+_PREFETCH_QUERY_MAX = 2000
+_PREFETCH_QUERY_OMISSION = "\n...\n"
+
+
+def _bounded_prefetch_query(query: str) -> str:
+ """Keep both the opening context and the final question within the caps.
+
+ A non-string, or a turn that is blank after trimming, travels unchanged,
+ so the bridge refuses it as before; bounding a blank turn would leave
+ only the omission marker, a non-blank query with nothing to recall on.
+ """
+ if not isinstance(query, str) or not query.strip() or len(query) <= _PREFETCH_QUERY_MAX:
+ return query
+ retained = _PREFETCH_QUERY_MAX - len(_PREFETCH_QUERY_OMISSION)
+ head = retained // 2
+ tail = retained - head
+ return query[:head] + _PREFETCH_QUERY_OMISSION + query[-tail:]
# A provider instance is created per AIAgent, but the MCP server is a gateway
# resource rather than a session resource. Keep one bridge per effective server
@@ -812,8 +831,14 @@ class OpenSecondBrainMemoryProvider(MemoryProvider):
parts: list[str] = []
sid = session_id or self._session_id
turn_id = str(_kwargs.get("turn_id") or "")
+ recall_query = _bounded_prefetch_query(query)
+ if recall_query != query:
+ logger.info(
+ "%s: prefetch recall query reduced to %d codepoints (original %d)",
+ self.PROVIDER_NAME, len(recall_query), len(query),
+ )
gate_args: dict[str, Any] = {
- "prompt": query,
+ "prompt": recall_query,
"telemetry_host": _PREFETCH_RECEIPT_HOST,
}
if sid:
@@ -833,8 +858,8 @@ class OpenSecondBrainMemoryProvider(MemoryProvider):
# turn and excludes none, so the budget decides what is dropped.
# The server refuses a mode with no query, so both travel or
# neither does.
- if query.strip():
- pack_args["query"] = query
+ if recall_query.strip():
+ pack_args["query"] = recall_query
pack_args["query_mode"] = _PREFETCH_QUERY_MODE
if sid:
pack_args["session_id"] = sid
diff --git a/tests/core/brain/store-only-operator-readers.test.ts b/tests/core/brain/store-only-operator-readers.test.ts
index 042a68cd..44ce7557 100644
--- a/tests/core/brain/store-only-operator-readers.test.ts
+++ b/tests/core/brain/store-only-operator-readers.test.ts
@@ -7,7 +7,7 @@
* switched machine that has data, the inventory's top reader risk.
*/
import { beforeAll, describe, expect, test } from "bun:test";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";
import {
@@ -16,6 +16,8 @@ import {
readAllRetiredRecords,
} from "../../../src/core/brain/doctor/records.ts";
import { runDoctor } from "../../../src/core/brain/doctor.ts";
+import { brainDirs, preferencePath } from "../../../src/core/brain/paths.ts";
+import { moveToRetired, writePreference } from "../../../src/core/brain/preference.ts";
import { STORE_CLOCK_AHEAD_CODE } from "../../../src/core/brain/doctor/store-check.ts";
import { computeSemanticHealth } from "../../../src/core/brain/doctor/semantic-health-check.ts";
import { resolveArtifactRef } from "../../../src/core/brain/artifact-ref-resolve.ts";
@@ -404,6 +406,88 @@ describe("legacy pages left in place on a switched machine", () => {
}
});
+describe("legacy record listing order", () => {
+ // `readdir` answers in the filesystem's order: hash order on ext4,
+ // creation order on btrfs, newest first on tmpfs. Writing the pages in an
+ // order that is neither name order nor its reverse puts the listing out
+ // of name order on each of them; the store side is always in path order.
+ // Twelve names a folder, so a hash order that happens to be name order
+ // is a one in 479 million chance.
+ const WRITE_ORDER = [
+ "order-f",
+ "order-b",
+ "order-h",
+ "order-a",
+ "order-e",
+ "order-c",
+ "order-g",
+ "order-d",
+ "order-p",
+ "order-k",
+ "order-t",
+ "order-i",
+ "order-x",
+ "order-m",
+ "order-r",
+ "order-j",
+ "order-w",
+ "order-l",
+ "order-u",
+ "order-n",
+ "order-s",
+ "order-o",
+ "order-v",
+ "order-q",
+ ];
+ const RETIRED = WRITE_ORDER.slice(0, 12);
+ const NAME_ORDER = WRITE_ORDER.toSorted();
+
+ test("the preference and retired snapshots come in name order whatever readdir answers", () => {
+ const answer = withMemoryFixture(
+ "legacy",
+ (env) => {
+ for (const slug of WRITE_ORDER) {
+ writePreference(
+ env.vault,
+ {
+ slug,
+ topic: slug,
+ principle: `principle ${slug}`,
+ created_at: "2026-11-01T00:00:00Z",
+ unconfirmed_until: "2026-11-30T00:00:00Z",
+ status: "unconfirmed",
+ evidenced_by: [],
+ },
+ { authority: "agent" },
+ );
+ }
+ for (const slug of RETIRED) {
+ moveToRetired(env.vault, preferencePath(env.vault, slug), "stale-no-evidence", {
+ now: FIXTURE_NOW,
+ retired_by: "[[Brain/log/2026-11-06]]",
+ authority: "agent",
+ });
+ }
+ const dirs = brainDirs(env.vault);
+ return {
+ listed: [readdirSync(dirs.preferences), readdirSync(dirs.retired)],
+ preferences: readAllPreferenceRecords(env.vault).map((r) => r.pref.id),
+ retired: readAllRetiredRecords(env.vault).map((r) => r.retired.id),
+ };
+ },
+ { seed: false },
+ );
+ if (process.platform === "linux") {
+ // The bad order is forced: the listing itself is out of name order.
+ for (const names of answer.listed) expect(names).not.toEqual(names.toSorted());
+ }
+ expect(answer.preferences).toEqual(
+ NAME_ORDER.filter((slug) => !RETIRED.includes(slug)).map((slug) => `pref-${slug}`),
+ );
+ expect(answer.retired).toEqual(RETIRED.toSorted().map((slug) => `ret-${slug}`));
+ });
+});
+
describe("operator snapshot on a switched machine", () => {
test("counts the memory records as on an unswitched machine, and not as none", async () => {
const fromLegacy = await snapshotCounts("legacy");
diff --git a/tests/python/test_memory_provider.py b/tests/python/test_memory_provider.py
index 3e36ede9..76b9b067 100644
--- a/tests/python/test_memory_provider.py
+++ b/tests/python/test_memory_provider.py
@@ -881,6 +881,73 @@ class ProviderLifecycleTests(unittest.TestCase):
self.assertEqual(gate_args["turn_id"], "turn-7")
self.assertEqual(gate_args["telemetry_host"], "hermes")
+ def test_prefetch_bounds_long_queries_and_keeps_the_ends(self):
+ for query in (
+ "A" * 2000,
+ "Start " + "x" * 1981 + " end question?",
+ "Start " + "x" * 1990 + " end question?",
+ "Start " + "x" * 4000 + " end question?",
+ "Start " + "😀" * 4001 + " end question?",
+ ):
+ with self.subTest(length=len(query)):
+ bridge = FakeBrainBridge(results={
+ "brain_recall_gate": {"structuredContent": {"retrieve": True}},
+ "brain_context_pack": {"content": [{"type": "text", "text": "RECALLED"}]},
+ })
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ with patch.object(provider_module.logger, "info") as log:
+ result = provider.prefetch(query, session_id="sess-1")
+ gate = next(a for n, a in bridge.calls if n == "brain_recall_gate")
+ pack = next(a for n, a in bridge.calls if n == "brain_context_pack")
+ self.assertIn("RECALLED", result)
+ self.assertEqual(gate["prompt"], pack["query"])
+ self.assertLessEqual(len(pack["query"]), 2000)
+ self.assertLessEqual(len(gate["prompt"].encode("utf-16-le")) // 2, 4000)
+ self.assertEqual(next(a for n, a in bridge.calls if n == "skills_attach")["query"], query)
+ reduced = [c for c in log.call_args_list if "query reduced" in c.args[0]]
+ if len(query) > 2000:
+ self.assertEqual(len(pack["query"]), 2000)
+ self.assertTrue(pack["query"].startswith("Start "))
+ self.assertTrue(pack["query"].endswith(" end question?"))
+ self.assertEqual(len(reduced), 1)
+ else:
+ self.assertEqual(pack["query"], query)
+ self.assertEqual(reduced, [])
+
+ def test_prefetch_leaves_a_long_blank_turn_unbounded(self):
+ # Bounding a turn that is blank after trimming would leave only the
+ # omission marker, a non-blank query that recalls on nothing. The turn
+ # travels as before: the gate refuses it and the pack gets no query.
+ query = " \n\t" * 1000
+ bridge = FakeBrainBridge(results={
+ "brain_recall_gate": {"structuredContent": {"retrieve": True}},
+ "brain_context_pack": {"content": [{"type": "text", "text": "RECALLED"}]},
+ })
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ with patch.object(provider_module.logger, "info") as log:
+ provider.prefetch(query, session_id="sess-1")
+ gate = next(a for n, a in bridge.calls if n == "brain_recall_gate")
+ pack = next(a for n, a in bridge.calls if n == "brain_context_pack")
+ self.assertEqual(gate["prompt"], query)
+ self.assertNotIn("query", pack)
+ self.assertNotIn("query_mode", pack)
+ self.assertFalse(any("query reduced" in c.args[0] for c in log.call_args_list))
+
+ def test_prefetch_forwards_a_non_string_query_without_raising(self):
+ # A host that hands over None or a non-string still reaches the bridge,
+ # which answers fail-soft; the bound must not raise first.
+ for query in (None, 12345):
+ with self.subTest(query=query):
+ bridge = FakeBrainBridge(
+ results={"brain_recall_gate": {"structuredContent": {"retrieve": False}}}
+ )
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ provider.prefetch(query, session_id="sess-1")
+ gate = next(a for n, a in bridge.calls if n == "brain_recall_gate")
+ self.assertIs(gate["prompt"], query)
+ attach = next(a for n, a in bridge.calls if n == "skills_attach")
+ self.assertIs(attach["query"], query)
+
def test_prefetch_keeps_the_server_receipt_as_sample_id(self):
# The sample id an agent later posts an outcome against must be the
# id the server wrote a receipt under, never a locally hashed