feat: trusted recall and memory write surface (v1.35.0)

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "open-second-brain",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Plugin-first second brain package for AI agents and humans.",
   "author": {
     "name": "Open Second Brain contributors"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "open-second-brain",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
   "skills": "./skills",
   "hooks": "./hooks/hooks.json",

CHANGELOG.md

@@ -5,6 +5,32 @@ 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.35.0] - 2026-07-19
+
+A trusted recall and memory write surface wave: ten units that carry vault knowledge to the agent at the moment it matters and make every step accountable. An opt-in bounded recall brief lands on each prompt, retrieval zero-ranks quarantined material and hands back receipts naming every exclusion, a supersede relation on a successor fades the superseded note without editing it, and MCP agents gain the full atomic note lifecycle: update, append, and all-or-nothing mixed batches. Two shared kernels carry the wave: a deterministic retrieval rank-adjustment stage and an atomic multi-operation write core. The kernel still calls no LLM, and every new surface is byte-identical when its flag or param is omitted.
+
+### Added
+
+- Bounded recall inject on UserPromptSubmit: with `recall_inject_enabled: "true"` (env `OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED`) a hook relevance-recalls a small brief of vault notes into each prompt under hard caps (4 notes, 900 chars, a fixed time budget), abstains below a confidence floor, injects nothing on any internal error or timeout, and writes one audit line per decision (inject, abstain, error) recording counts and scores, never content. The brief is fenced as untrusted content with neutralized titles; the hook process itself stays fail-open for the session.
+- Retrieval trust gate plus per-pack receipts: with `search_trust_gate_enabled: "true"` (env `OPEN_SECOND_BRAIN_SEARCH_TRUST_GATE`), material carrying quarantine signals (self-approval quarantine state, untrusted-source provenance, entity-contamination marker) is zero-ranked out of both semantic and lexical search through a new deterministic rank-adjustment stage, and every search outcome carries two compact-reference receipts, `memory_trust_assessment` and `retrieval_decision_trace`, counting each exclusion with its reason so nothing is dropped silently.
+- Relation-only supersede fade: with `search_supersede_fade_enabled: "true"` (env `OPEN_SECOND_BRAIN_SEARCH_SUPERSEDE_FADE`), an inbound `supersedes` or `superseded_by` relation authored on a successor fades the unchanged superseded note by a named multiplier on both search paths, so deprecating a note takes one edit on its replacement; the existing tombstone drop is untouched.
+- `brain_update_note` and `brain_append_note` MCP tools: update an existing note's body and/or merge frontmatter keys, or append to its body, under the exact create-note safety envelope (path traversal, Brain machinery root, vault-scope exclusions), with atomic write semantics and a typed error when the target does not exist.
+- `brain_write_batch` MCP tool: an ordered mixed batch (create note, update note body or frontmatter, append note, apply evidence, append log line) validated and projected in memory first, then committed all-or-nothing; the first invalid operation aborts with a typed error naming its index and nothing touches disk; a duplicate note target within one batch is refused.
+- `include_raw` on session recall (`brain_session_grep`): responses carry the original raw capture inline beside each derived record, and every item is stamped with an `extracted` boolean discriminator (derived versus raw); an optional `raw_budget_chars` clips raw payloads while identity fields survive.
+- Knowledge-gap loop: with `gap_loop_enabled: "true"` (env `OPEN_SECOND_BRAIN_GAP_LOOP_ENABLED`, threshold via `gap_loop_threshold`), recurring recall gaps aggregated from existing gap-count telemetry promote at session end into durable task notes under `Brain/gap-tasks/` (stable-key dedup, never the kanban board), open gap tasks render as a session-start agenda, and a later confident recall on the topic auto-closes the task; gap tasks never match their own text.
+- Typed age-labeled session-start timeline: the morning brief renders recalled items as one chronological Recent activity timeline with a per-item structural type marker and relative age label built by a pure rendering helper; the underlying data arrays are unchanged.
+- Clip-protected pack identity: `agent_id` joins `session_id` on pack and continuity identity, and the new `clipPayloadToBudget` primitive retains both fields under any output-budget truncation while dropping non-protected keys.
+- Fail-fast doctor readiness probes: `o2b doctor --readiness` runs three functional probes (model-inference key resolvable, embedding provider loadable with model and dims, runtime-adapter wiring) with per-check timeouts and outcomes pass, fail with a reason, or skipped-not-configured; any failure exits non-zero, and without the flag doctor output stays byte-identical.
+
+### Changed
+
+- The MCP tool surface grows from 103 to 106 tools (`brain_update_note`, `brain_append_note`, `brain_write_batch`); `brain_session_grep` gains optional `include_raw` and `raw_budget_chars` params and stays byte-identical when they are omitted.
+- Search ranking flows through a deterministic rank-adjustment stage (`src/core/search/rank-adjust.ts`); with no adjusters registered the stage returns its input unchanged.
+
+### Fixed
+
+- The temporal-replace lifecycle test derived its expected log day from the wall clock and failed on any date after its authoring day; it now derives the day from the operation result.
+
 ## [1.34.0] - 2026-07-18
 
 A source pipeline integrity and operator tooling wave: eleven units that make vault intake trustworthy end to end (scoped and gated discovery, reconciled dispatch, deterministic pre-extraction, citation provenance), extend the query surface (configurable FTS tokenizer, graph-degree predicates), and give the operator a repairing doctor plus one consolidated status snapshot. Two shared kernels carry the wave: a gitignore-semantics path-scope engine and a diagnostics-signal registry whose next-command hints travel with the issue definitions. Everything stays deterministic (the kernel calls no LLM) and every new surface is byte-identical when unused.
@@ -6556,6 +6582,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.35.0]: https://github.com/itechmeat/open-second-brain/compare/v1.34.0...v1.35.0
 [1.34.0]: https://github.com/itechmeat/open-second-brain/compare/v1.33.0...v1.34.0
 [1.33.0]: https://github.com/itechmeat/open-second-brain/compare/v1.32.0...v1.33.0
 [1.32.0]: https://github.com/itechmeat/open-second-brain/compare/v1.31.0...v1.32.0

README.md

@@ -8,7 +8,7 @@ Open Second Brain plugs into [Hermes Agent](https://github.com/NousResearch/herm
 
 ## What is new
 
-Open Second Brain 1.34.0 is a source pipeline integrity and operator tooling release. Getting sources into the vault is now trustworthy end to end: ingest can be scoped to one monorepo subtree with gitignore-style excludes, the hygiene scan honors nested `.gitignore` files with git semantics, the schema `extractable` flag actually gates page discovery, a deterministic no-LLM pre-pass extracts code structure (classes, functions, imports, inheritance) as seeds before agent ingest, and every batch plan can be reconciled so a source an agent silently dropped is named instead of lost. Prose citations like `[Source: name, YYYY-MM-DD]` become dated provenance events on the temporal timeline, the FTS tokenizer becomes configurable for non-English vaults, and search gains graph-degree predicates for orphan and hub queries. On the operator side, `o2b brain doctor --repair` turns diagnostics into guarded one-command fixes, `o2b brain status` consolidates every health signal into one snapshot with an exact next command per problem, and piping any CLI into `head` finally exits clean. The kernel still calls no LLM.
+Open Second Brain 1.35.0 is a trusted recall and memory write surface release. Vault knowledge now reaches the agent at the moment it matters: an opt-in hook injects a bounded, fenced recall brief on every prompt (hard caps, confidence floor, one audit line per decision, nothing injected on any error), the morning brief renders a typed age-labeled activity timeline, and recurring recall gaps stop evaporating - they become durable task notes, surface as a session-start agenda, and close themselves once the gap is filled. What retrieval returns can be trusted: an opt-in gate zero-ranks quarantined material out of both semantic and lexical search and attaches two receipts naming every exclusion, a `supersedes` relation on a successor fades the outdated note without editing it, session recall can inline the raw capture beside each derived record with an `extracted` discriminator, and budget clipping can no longer strip `session_id` or `agent_id` from a pack. MCP agents gain the full write lifecycle - `brain_update_note`, `brain_append_note`, and the all-or-nothing `brain_write_batch` - and `o2b doctor --readiness` answers the Day-0 wiring question with three functional probes and a real exit code. The kernel still calls no LLM.
 
 ## Why
 

docs/brainstorm/recall-trust-and-write-surface/cli-output/claude.md

@@ -0,0 +1,40 @@
+### Variant 1: Kernel-first (four seams extracted up front)
+
+- **Approach**: Land four pure-refactor commits first, before any feature: (1) a retrieval rank-adjustment pipeline (ordered list of deterministic scorers/sinks between ranker and pack builder), (2) an atomic multi-operation write core generalized from `runPinnedContextBatch`, (3) a unified injection surface abstracting SessionStart and UserPromptSubmit context assembly, (4) a pack-shape module owning budget clipping and protected fields. The ten tasks then plug into these seams as thin consumers, sequenced freely since dependencies are already satisfied.
+- **Trade-offs**:
+  - Pro: each concern gets exactly one home from day one; no file is rewritten twice inside the PR.
+  - Pro: the byte-identical-opt-out gate is easiest to prove - each refactor commit can be verified behavior-neutral in isolation before features stack on it.
+  - Pro: parallelizable - once the four kernels exist, the ten tasks have almost no cross-dependencies.
+  - Con: seams 3 and 4 are designed before their consumers exist; the injection abstraction especially risks being wrong (SessionStart digest, prompt-time recall, and gap agenda have different lifecycles, budgets, and fail-open/fail-closed rules).
+  - Con: four refactor commits inflate the PR and delay the first visible feature; a review objection to one kernel blocks everything behind it.
+  - Con: highest chance of speculative generality, which conflicts with the "no stubs, no do-nothing fallbacks" convention.
+- **Complexity**: large
+- **Risk**: medium
+
+### Variant 2: Feature-first with second-consumer extraction
+
+- **Approach**: Sequence the ten tasks by theme and extract a shared kernel only at the moment a second consumer arrives. Concretely: supersede fade lands inline in `ranker.ts`/`result-filters.ts`; when the trust gate arrives next it extracts the rank-adjustment layer and migrates the fade into it. Likewise `brain_update_note`/`brain_append_note` land on `writeFrontmatterAtomic` first, and the batch tool later generalizes `runPinnedContextBatch` and rebases the note tools onto the shared core.
+- **Trade-offs**:
+  - Pro: every seam is shaped by two real consumers, so the abstractions are guaranteed to fit; zero speculative design.
+  - Pro: each commit ships user-visible value; review can proceed task by task without first approving abstract infrastructure.
+  - Con: files are rewritten mid-PR (ranker touched by commit N, restructured by commit N+2), which muddies "one atomic commit per task" and doubles test churn on the hottest files.
+  - Con: extraction happens under feature pressure inside the same PR, the classic condition for an asymmetric seam biased toward whichever consumer landed second.
+  - Con: sequencing becomes strictly serial along each extraction chain, lengthening the critical path of a ten-task wave.
+- **Complexity**: medium
+- **Risk**: medium
+
+### Variant 3: Two-kernel pragmatic (extract only the seams with two proven consumers; keep injection and budget as conventions)
+
+- **Approach**: Extract exactly two kernels, each of which has two concrete consumers inside this wave: (1) a retrieval-stage rank-adjustment sink between `ranker.ts` and the pack builder, with the trust gate contributing zero-rank verdicts plus receipts and the supersede fade contributing a multiplier - both covering the pure-lexical path; (2) an atomic batch write core generalized from `runPinnedContextBatch` (validate-and-project in memory, commit-or-rollback), on which `brain_update_note`/`brain_append_note` are single-op batches and t_7718ab22 is the multi-op surface that also fixes the operation vocabulary. Seams 3 and 4 are deliberately NOT abstracted: the recall hook, timeline, and gap agenda each stay at their own existing hook/brief anchor sharing only a rendering helper, and clip-protected identity is a small protected-field contract in `token-impact.ts` that `include_raw` simply respects. Sequence: rider test fix; then D (t_cc234ff5, independent); then kernel 1 + t_5f61130a + t_c4a9cef8; then kernel 2 + t_3ff3fe77 + t_7718ab22; then t_5be0654d + t_ac1d36ea; then A-theme t_4adb0b8b, t_2ce46130, t_67d38036 last (the gap loop depends on recall telemetry paths the hook exercises).
+- **Trade-offs**:
+  - Pro: both extracted kernels are justified by two in-wave consumers, so no speculative abstraction, and both are deterministic pure functions - a natural fit for the no-LLM kernel and the language-agnostic trust-gate constraint.
+  - Pro: respects the real asymmetry in theme A - SessionStart is fail-open, the prompt-time recall hook is fail-closed with audit; a shared injection surface would have to encode both policies and would blur exactly the guarantee t_2ce46130 must keep crisp.
+  - Pro: shortest critical path - three independent tracks (rank track, write track, injection track) can proceed in parallel after the two small kernel commits.
+  - Con: if a future wave adds a third injection consumer, the A-theme code pays a later extraction cost.
+  - Con: the protected-fields "convention" in `token-impact.ts` relies on the regression test (tiny-budget clip retains identity) rather than a structural home; a future clipper could bypass it.
+- **Complexity**: medium
+- **Risk**: low
+
+### Recommended: Variant 3
+
+**Rationale**: The two kernels it extracts are the only candidate seams with two concrete consumers shipping in this very wave, so they cannot be speculatively wrong, while Variant 1 forces an injection abstraction across surfaces with contradictory failure policies (fail-open session hooks vs the fail-closed audited recall hook) and Variant 2 rewrites the ranker and write path twice inside a ten-commit PR, breaking the one-atomic-commit-per-task convention. Variant 3 also yields three parallel tracks with the rider fix and doctor probes landing first, which de-flakes CI before the heavier commits and keeps every commit byte-identical when its flag is omitted.