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): record context-pack receipts and explicit outcomes (#179)

Yori9406195102f1429b0a
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 3f99c56d..887f7c0f 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.52.0",
+ "version": "1.52.1",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 507c1751..42357253 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.52.0",
+ "version": "1.52.1",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3fad92f4..388f96d7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.52.1] - 2026-08-24
+
+The context-pack outcome ledger shipped with receipts on the read side and nothing on the Hermes side to carry them, so a deployment that injected recall on every turn still recorded zero outcomes. Contributed by [@Yori940619](https://github.com/Yori940619) ([#179](https://github.com/itechmeat/open-second-brain/pull/179)), with one course correction along the way that is worth recording: the first revision inferred success and repair from hardcoded phrase lists in a single language, and the rework removed raw-text inference entirely - the honest shape, and now the pinned one.
+
+### Fixed
+
+- **The Hermes provider closes the context-pack outcome loop - structurally, not linguistically.** `prefetch` now requests a context receipt and opt-in telemetry from the same `brain_context_pack` call and appends a small structured metadata line (sample id, tool name, `outcome: unknown_until_explicit_tool_call`) to the injected recall, so the calling agent - the party that actually understands the user's language - posts `brain_context_pack_outcome` itself when the user explicitly confirms or corrects. The provider infers nothing from raw turn text, in any language, and a regression test pins that; an unsignaled turn stays unknown rather than being guessed into a vanity metric. `brain_context_pack_outcome` joins the curated Hermes tool surface with its schema vendored against the live server.
+
## [1.52.0] - 2026-08-23
Nine tracker cards read against the live source before anything was designed, and the reading did most of the work. One card described a feature that already shipped end to end - closed, not built. One asked for privacy by riding a predicate that is inert in every default install - refused as designed, redesigned down to the truth it can tell today. Four more had premises the source contradicted: the "localized" stamp would have touched sixty-eight writers, the counter had no chokepoint to count at, the resume half already existed on the ingest lane, and the raise-on-attach the card wanted was already there behind a documented default. What survived is one rule applied eight ways: nothing writes silently, nothing degrades silently.
@@ -7349,6 +7357,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[1.52.1]: https://github.com/itechmeat/open-second-brain/compare/v1.52.0...v1.52.1
[1.52.0]: https://github.com/itechmeat/open-second-brain/compare/v1.51.0...v1.52.0
[1.51.0]: https://github.com/itechmeat/open-second-brain/compare/v1.50.3...v1.51.0
[1.50.3]: https://github.com/itechmeat/open-second-brain/compare/v1.50.2...v1.50.3
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index d8c72027..14a20157 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "1.52.0",
+ "version": "1.52.1",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index 9fb65f73..2342f55a 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.52.0",
+ "version": "1.52.1",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index ddc17f8a..4e44338d 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.52.0"
+version: "1.52.1"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index eee4a201..dc2a7772 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "1.52.0",
+ "version": "1.52.1",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/_schemas.py b/plugins/hermes/_schemas.py
index 4c1c180d..702e7580 100644
--- a/plugins/hermes/_schemas.py
+++ b/plugins/hermes/_schemas.py
@@ -602,6 +602,114 @@ STATIC_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = (
'dependentRequired': {'recall_scores': ['match_quality'],
'match_quality': ['recall_scores']},
'additionalProperties': False}},
+ {
+ "name": "brain_context_pack_outcome",
+ "description": "Context-pack outcome loop. `post` records an outcome row for a carried sample id — first-pass/repair/retry counters plus three SEPARATE token signals (exact, modeled, observed) — calibrates the token-impact ledger, and records the kernel's on-disk evidence. `list`/`summary` read rows. Gated.",
+ "inputSchema": {
+ "type": "object",
+ "properties": {
+ "operation": {
+ "type": "string",
+ "enum": ["post", "list", "summary"],
+ "description": "post writes one opt-in outcome row; list/summary read the durable ledger.",
+ },
+ "sample_id": {
+ "type": "string",
+ "description": "post: the carried recall/context-pack quality-sample id (a context-receipt id or opaque request hash) — never a raw prompt. Also a list/summary filter.",
+ },
+ "first_pass_success": {
+ "type": "boolean",
+ "description": "post: whether the packed context led to a first-pass success.",
+ },
+ "repair_required": {
+ "type": "boolean",
+ "description": "post (optional): whether the agent had to repair the first completion.",
+ },
+ "retry_count": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "post (optional): how many retries the completion needed.",
+ },
+ "follow_up_tokens": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "post (optional): tokens spent on follow-up turns after the first pass.",
+ },
+ "exact_prompt_token_savings": {
+ "type": "number",
+ "minimum": 0,
+ "description": "post (optional): EXACT tokenizer-aware prompt-token savings (a measurement). Kept separate from the modeled and observed signals.",
+ },
+ "modeled_inference_avoidance": {
+ "type": "number",
+ "minimum": 0,
+ "description": "post (optional): MODELED confidence-banded inference-avoidance estimate (a model). Kept separate from the exact and observed signals.",
+ },
+ "observed_provider_tokens": {
+ "type": "number",
+ "minimum": 0,
+ "description": "post (optional): OBSERVED provider-reported token usage. Kept separate from the exact and modeled signals; also calibrates the token-impact ledger.",
+ },
+ "evidence_claim": {
+ "type": "object",
+ "description": "post (optional): what you assert about this sample; kernel reads its receipt off disk, records match|mismatch|unclaimed|unresolved. Malformed = INVALID_PARAMS.",
+ "properties": {
+ "final_text_hash": {
+ "type": "string",
+ "description": "Claimed SHA-256 of the assembled pack text.",
+ },
+ "item_count": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Claimed number of artifacts the pack injected.",
+ },
+ "final_text_chars": {
+ "type": "integer",
+ "minimum": 0,
+ "description": "Claimed codepoint length of the assembled pack text.",
+ },
+ },
+ "additionalProperties": False,
+ },
+ "host": {
+ "type": "string",
+ "description": "Optional host/runtime label; also a filter.",
+ },
+ "session_id": {
+ "type": "string",
+ "description": "Optional session id recorded on the row.",
+ },
+ "turn_id": {
+ "type": "string",
+ "description": "Optional turn id recorded on the row.",
+ },
+ "agent_id": {
+ "type": "string",
+ "description": "post (optional): the ACTING agent, recorded on all three rows this post lands. Self-asserted, never a verifier; omitted records no actor rather than a guess.",
+ },
+ "since": {
+ "type": "string",
+ "description": "Optional inclusive lower timestamp bound.",
+ },
+ "until": {
+ "type": "string",
+ "description": "Optional inclusive upper timestamp bound.",
+ },
+ "limit": {
+ "type": "integer",
+ "minimum": 1,
+ "description": "Optional maximum record count for list.",
+ },
+ "max_samples": {
+ "type": "integer",
+ "minimum": 1,
+ "description": "Optional cap on the most-recent rows aggregated by summary.",
+ },
+ },
+ "required": ["operation"],
+ "additionalProperties": False,
+ },
+ },
{'name': 'brain_pre_compact_extract',
'description': 'Extract typed Decision/Commitment/Outcome/Rule/Open question records from '
'bounded text into continuity storage.',
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index ddc17f8a..4e44338d 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "1.52.0"
+version: "1.52.1"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/hermes/provider.py b/plugins/hermes/provider.py
index 2c1cf8f3..65a7aacd 100644
--- a/plugins/hermes/provider.py
+++ b/plugins/hermes/provider.py
@@ -48,6 +48,7 @@ MEMORY_TOOLS: tuple[str, ...] = (
"brain_recall_gate",
"brain_context",
"brain_context_pack",
+ "brain_context_pack_outcome",
# continuity
"brain_pre_compact_extract",
)
@@ -143,6 +144,7 @@ SESSION_TRANSCRIPT_FILENAME = "session-transcript.jsonl"
# Token budget for the recall slice fetched on each prefetch.
_PREFETCH_MAX_TOKENS = 1024
+_PREFETCH_RECEIPT_HOST = "hermes"
# 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
@@ -286,6 +288,7 @@ class OpenSecondBrainMemoryProvider(MemoryProvider):
self._sync_threads: list[threading.Thread] = []
self._queued_query: str = ""
+
# -- required surface ----------------------------------------------------
@property
@@ -594,6 +597,13 @@ class OpenSecondBrainMemoryProvider(MemoryProvider):
# -- lifecycle hooks -----------------------------------------------------
+ @staticmethod
+ def _receipt_id(pack: Any) -> str | None:
+ """Return the server-issued opaque receipt id, if this pack has one."""
+ structured = OpenSecondBrainMemoryProvider._structured(pack)
+ receipt_id = structured.get("receipt_id")
+ return str(receipt_id) if receipt_id else None
+
def system_prompt_block(self) -> str:
"""Static provider context: the current active-preferences body."""
result = self._safe_call("brain_context", {})
@@ -607,12 +617,36 @@ class OpenSecondBrainMemoryProvider(MemoryProvider):
always appended when an agent identity is configured.
"""
parts: list[str] = []
+ sid = session_id or self._session_id
gate = self._structured(self._safe_call("brain_recall_gate", {"prompt": query}))
if gate.get("retrieve"):
- pack = self._safe_call("brain_context_pack", {"max_tokens": _PREFETCH_MAX_TOKENS})
+ pack = self._safe_call(
+ "brain_context_pack",
+ {
+ "max_tokens": _PREFETCH_MAX_TOKENS,
+ "receipt": True,
+ "receipt_host": _PREFETCH_RECEIPT_HOST,
+ "telemetry": True,
+ "telemetry_host": _PREFETCH_RECEIPT_HOST,
+ **({"session_id": sid} if sid else {}),
+ },
+ )
recalled = self._context_pack_text(pack)
if recalled:
parts.append(recalled)
+ receipt_id = self._receipt_id(pack)
+ if receipt_id:
+ parts.append(
+ "[O2B context-pack metadata] "
+ + json.dumps(
+ {
+ "sample_id": receipt_id,
+ "outcome": "unknown_until_explicit_tool_call",
+ "tool": "brain_context_pack_outcome",
+ },
+ ensure_ascii=False,
+ )
+ )
# Skill auto-attach (Agent Surface Suite): the TS side gates on the
# skill_auto_attach config key and returns an empty block when off,
# so the default injection stays byte-identical. Fail-soft like every
diff --git a/pyproject.toml b/pyproject.toml
index e5a2e2c1..c3b4e964 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "1.52.0"
+version = "1.52.1"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/tests/python/test_memory_provider.py b/tests/python/test_memory_provider.py
index a78e3286..7213e687 100644
--- a/tests/python/test_memory_provider.py
+++ b/tests/python/test_memory_provider.py
@@ -802,6 +802,102 @@ class ProviderLifecycleTests(unittest.TestCase):
self.assertIn("RECALLED", out)
self.assertIn("@pf-agent", out)
+ def test_prefetch_exposes_receipt_and_agent_posts_structured_outcome(self):
+ bridge = FakeBrainBridge(
+ results={
+ "brain_recall_gate": {"structuredContent": {"retrieve": True}},
+ "brain_context_pack": {
+ "structuredContent": {
+ "receipt_id": "receipt-1",
+ "items": [{"title": "decision", "body": "keep RRF"}],
+ }
+ },
+ "brain_context_pack_outcome": {"structuredContent": {"recorded": True}},
+ }
+ )
+ with tempfile.TemporaryDirectory() as hermes_home:
+ provider = self._init(bridge, hermes_home=hermes_home)
+ out = provider.prefetch("what did we decide", session_id="sess-1")
+ provider.handle_tool_call(
+ "brain_context_pack_outcome",
+ {
+ "operation": "post",
+ "sample_id": "receipt-1",
+ "first_pass_success": False,
+ "repair_required": True,
+ "host": "hermes",
+ "session_id": "sess-1",
+ },
+ )
+
+ self.assertIn('"sample_id": "receipt-1"', out)
+ pack_args = next(a for n, a in bridge.calls if n == "brain_context_pack")
+ self.assertIs(pack_args["receipt"], True)
+ self.assertEqual(pack_args["receipt_host"], "hermes")
+ self.assertIs(pack_args["telemetry"], True)
+ self.assertEqual(pack_args["telemetry_host"], "hermes")
+ self.assertEqual(pack_args["session_id"], "sess-1")
+
+ outcome_args = next(a for n, a in bridge.calls if n == "brain_context_pack_outcome")
+ self.assertEqual(outcome_args["operation"], "post")
+ self.assertEqual(outcome_args["sample_id"], "receipt-1")
+ self.assertIs(outcome_args["first_pass_success"], False)
+ self.assertIs(outcome_args["repair_required"], True)
+ self.assertEqual(outcome_args["session_id"], "sess-1")
+
+ def test_prefetch_leaves_neutral_outcome_unknown(self):
+ bridge = FakeBrainBridge(
+ results={
+ "brain_recall_gate": {"structuredContent": {"retrieve": True}},
+ "brain_context_pack": {
+ "structuredContent": {
+ "receipt_id": "receipt-neutral",
+ "items": [{"title": "decision", "body": "keep RRF"}],
+ }
+ },
+ }
+ )
+ provider = self._init(bridge, hermes_home="/tmp/hh")
+ provider.prefetch("what did we decide", session_id="sess-1")
+ provider.prefetch("tell me something else", session_id="sess-1")
+ self.assertEqual(
+ [name for name, _ in bridge.calls if name == "brain_context_pack_outcome"], []
+ )
+
+ def test_prefetch_never_infers_outcome_from_raw_turn_text(self):
+ gate_calls = 0
+
+ def gate(_args):
+ nonlocal gate_calls
+ gate_calls += 1
+ return {"structuredContent": {"retrieve": gate_calls == 1}}
+
+ bridge = FakeBrainBridge(
+ results={
+ "brain_recall_gate": gate,
+ "brain_context_pack": {
+ "structuredContent": {
+ "receipt_id": "receipt-unknown",
+ "items": [{"title": "decision", "body": "keep RRF"}],
+ }
+ },
+ }
+ )
+ with tempfile.TemporaryDirectory() as hermes_home:
+ provider = self._init(bridge, hermes_home=hermes_home)
+ provider.prefetch("what did we decide", session_id="sess-1")
+ provider.prefetch("tell me something else", session_id="sess-1")
+ provider.prefetch("我之前说过,不对", session_id="sess-1")
+
+ self.assertEqual(gate_calls, 3)
+ self.assertEqual(
+ [name for name, _ in bridge.calls if name == "brain_context_pack"],
+ ["brain_context_pack"],
+ )
+ self.assertEqual(
+ [name for name, _ in bridge.calls if name == "brain_context_pack_outcome"], []
+ )
+
def test_prefetch_uses_structured_items_bodies_and_skips_preview_envelope(self):
# Regression: when brain_context_pack returns both structuredContent
# items[*].body AND a content[0].text envelope carrying the