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

feat: Link & Recall Intelligence Suite - alias resolution, bridge discovery, communities, recall benchmark, self-tuning (#77)

Sol Aitken6d09d3ce134d
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 16c3ab09..c3936d13 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.44.0",
+ "version": "0.45.0",
"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 c89823c1..074889dd 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.44.0",
+ "version": "0.45.0",
"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 eae982eb..7cf1e5f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,102 @@ 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).
+## [0.45.0] - 2026-06-05
+
+Link & Recall Intelligence Suite: the graph self-organizes and recall
+quality becomes measurable. Wikilinks to frontmatter aliases resolve
+at index materialization; an orphan-first bridge pass over the vec
+index proposes links between embedding-near notes that never name
+each other, as a reviewable artifact with an accept/dismiss
+lifecycle; deterministic label propagation discovers graph-wide
+communities and materializes derived cluster digests; a fixed-dataset
+recall benchmark (hit@k + MRR) gates ranking regressions in CI and
+scores operator vaults on demand; a bounded, replayable self-tuning
+fold selects retrieval parameters judged by that benchmark, applied
+only under an explicit opt-in flag; and a bare query can expand into
+the existing structured lex/vec/hyde lanes with no model and no paid
+call. Every feature reports run-level numbers into one
+schema-versioned `Brain/metrics/` layer - the stable on-disk contract
+the upcoming dashboard plugin reads without importing internals. A
+vault that enables none of it behaves bit-identically. MCP tool count
+grows 73 -> 77.
+
+### Added
+
+- **Dashboard-ready metrics layer.** One append-only JSONL file per
+ surface under `Brain/metrics/` (`index`, `bridge_discovery`,
+ `communities`, `recall_benchmark`, `self_tuning`), envelope
+ `{schema: "o2b.metrics.v1", surface, run_at, payload}` with the
+ continuity-record evolution rule (additive fields keep the
+ version). Run-level only - per-query events stay in recall
+ telemetry. Contract documented in `docs/metrics.md`.
+- **Vault-wide alias resolution** (schema v7). The indexer extracts
+ frontmatter `aliases:` arrays into a `doc_aliases` table
+ (NFC-normalised, lower-cased - the `alias-index.ts` rule); after
+ exact-path resolution a shadowing-safe alias pass materializes
+ `target_document_id` for slash-free wikilink targets, so traversal,
+ backlinks, and link constraints see `[[PA]] -> project-alpha.md`.
+ Exact paths always win; a real document basename is never shadowed;
+ collisions resolve first-wins by sorted path.
+ `IndexStats.aliasResolved` counts the pass.
+- **Bridge discovery** (`o2b brain bridges`, MCP `brain_bridges`).
+ Orphan-first scan (ascending inbound-link order) takes chunk
+ embeddings to sqlite-vec KNN, converts unit-vector L2 to cosine,
+ aggregates to document level, and proposes pairs above the
+ similarity threshold that share no edge in either direction.
+ Output is the regenerated reviewable
+ `Brain/proposals/bridges.md`; `dismiss` persists pair suppressions;
+ `accept` writes exactly one `related:` wikilink into the source
+ frontmatter, idempotently, honoring schema-pack link constraints.
+ Fail-soft without an index or embeddings.
+- **Community detection with cluster notes** (`o2b brain clusters`,
+ MCP `brain_clusters`). Deterministic synchronous label propagation
+ (sorted sweeps, lowest-label tie-break, iteration cap against
+ bipartite oscillation) over the resolved doc-level link graph;
+ communities of size >= 4 materialize
+ `Brain/clusters/cluster-<id>.md` digests - members by internal
+ degree, shared entities, link density, no LLM prose. Derived notes
+ regenerate every run; stale generated notes are removed;
+ hand-written files in the directory are never touched;
+ `brain-cluster` joins the frontmatter tier map as framework-owned.
+- **Reproducible recall benchmark** (`o2b brain benchmark`, MCP
+ `brain_benchmark`). `runRecallBenchmark` scores hit@k and MRR per
+ query and aggregate against the live hybrid pipeline; the committed
+ 15-note fixture vault + 12-query dataset pin CI thresholds
+ (hit@5 >= 0.9, MRR >= 0.85; measured 1.000/0.958 with the
+ deterministic local embedding provider), so a ranking regression
+ fails the suite. The same runner scores operator vaults on demand
+ and serves as the self-tuner's objective function.
+- **Deterministic query expansion** (`o2b search --expand`,
+ `search(config, {expand: true})`). A bare query becomes a
+ structured lex/vec/hyde document locally: stopword-stripped lex
+ terms for the implicit-AND FTS lane, an entity-context vec line
+ from the vault's own registry, one template hyde passage. Opt-in
+ per call, never silently active, no GGUF model, no paid call.
+- **Opt-in self-tuning recall** (`o2b brain tune`, MCP `brain_tune`).
+ `tuneRecall` grid-evaluates bounded parameters (keyword pool
+ multiplier {3,4,5}, traversal depth {1,2}, learned weights on/off,
+ expansion on/off) with the benchmark as the objective and persists
+ the winner - with every evaluated score and the dataset hash - to
+ `Brain/search/tuning.json`. `search()` applies the re-validated
+ grid point only when `search_self_tuning_enabled` /
+ `OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING` is on; an explicit `expand`
+ always wins; the tuned state joins the query-cache key; reset
+ deletes the file and nothing else changes. The keyword candidate
+ pool becomes the configurable `search_pool_multiplier` (default 3,
+ byte-identical).
+- **Maintenance-lane passes.** `o2b brain maintenance run` gains
+ `bridges` and `clusters` tasks after `reindex`, riding the existing
+ quiet window, busy gate, and lease.
+
+### Notes
+
+- The bridge verb ships as `bridges` because `o2b brain links` is the
+ v0.38.0 wikilink-normalize contract.
+- Re-scope: the upstream benchmark task referenced a nonexistent
+ yantrikdb integration directory; the benchmark targets Open Second
+ Brain's own hybrid search instead.
+
## [0.44.0] - 2026-06-05
Write-Time Integrity & Governance Suite: every write into the Brain
@@ -4726,6 +4822,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.
+[0.45.0]: https://github.com/itechmeat/open-second-brain/compare/v0.44.0...v0.45.0
[0.44.0]: https://github.com/itechmeat/open-second-brain/compare/v0.43.1...v0.44.0
[0.43.1]: https://github.com/itechmeat/open-second-brain/compare/v0.43.0...v0.43.1
[0.43.0]: https://github.com/itechmeat/open-second-brain/compare/v0.42.0...v0.43.0
diff --git a/README.md b/README.md
index 64c83e53..ad58d588 100644
--- a/README.md
+++ b/README.md
@@ -114,7 +114,7 @@ The capabilities you actually feel day to day:
These are the headline capabilities. The full surface also includes: importing Claude Code memory directories, daily logging-discipline cron with a complexity-to-thinking warning, cross-project pointers for shared vaults, transient pinned session context through `brain_pinned_context` / `Brain/pinned.md`, source-agent query and comparison (`brain_agent_query`, `brain_agent_diff`, `o2b brain agent-query`, `o2b brain agent-diff`), the codegraph partner skill, vault hygiene lints, per-MOC coverage audit, concept synthesis, an operator dashboard, configurable Markdown-link presentation output, MCP output-contract checks for core agent-facing tools, private-region stripping with `<private>...</private>`, the v0.12.0 Brain Integrity Suite (content-hash drift detection, durable workrun checkpoints, destructive-from-confirmed retire gate, and the `brain_review_candidates` MCP tool that previews what the next dream pass would do without writing anything), the v0.13.0 Hybrid Search and Recall Quality suite (explainable recall, MMR diversity, link-graph traversal, entity-boosted retrieval, header-anchored chunking), the v0.14.0 Semantic Brain Health and Self-Maintenance suite (cross-preference contradiction detection, concept-gap and stale-claim surfacing, per-preference edit-history, a clean/watch/investigate reconciliation verdict via `brain_health`, and dependency-ordered `doctor --remediate`), the v0.17.0 Brain Lifecycle Review Suite (`intent-review`, `retention`, `monthly`, lifecycle schemas, and discipline complexity ratio), and the v0.18.0 MCP context economy (a per-tool preview budget that returns a bounded inline preview and parks the full payload in a vault-local artifact the agent fetches on demand with `brain_artifact_get`, plus a `recall_hint` one-liner on search results), and the v0.19.0 typed graph semantics (typed frontmatter relationships - `related` / `extends` / `contradicts` / `superseded_by` - that surface inline on search results, a `visibility:` scoping axis for `brain_search`, and a `brain_mcp_landscape` view of the Model Context Protocol servers configured across the vault), and the v0.20.0 Recall and Ranking Quality suite (a configurable Weibull recency-decay curve, structural query-intent classification that re-weights ranking by query shape, language-agnostic synonym expansion via local co-occurrence, per-memory and total recall character budgets for `brain_context_pack`, a persistent query cache that self-invalidates on a corpus-generation change, and a `brain_pre_compress_pack` tool that returns a budgeted top-preferences addendum for a host runtime to inject before context compression), and the v0.21.0 Brain Lifecycle Suite (a per-preference mutation audit trail keyed by preference id - create / promote / update / retire / merge with revision + content-hash before/after, via `o2b brain audit` and `brain_audit`; a multi-phase `dream` pipeline that names its close / reconcile / synthesize / heal / log seams and reports a structured per-phase summary without rewriting the proven internals; deterministic reconcile-phase domain classification that buckets contradictions into claims / entity / decisions / source-freshness, auto-resolves only the decisive source-freshness case, and surfaces the rest as open questions instead of forcing a merge; a budgeted `o2b brain morning-brief` / `brain_morning_brief` session-start summary of top preferences, recent open questions, and recent notes; language-agnostic ISO-8601 temporal extraction that fills preference validity windows from signal text; and opt-in heal-phase vault enrichment that links exact title mentions across user pages), and the v0.22.0 Vault portability + session economy suite (a deterministic lossless session codec - `expand(compress(x)) === x` for all input, opt-in on the signal store and exposed as `o2b brain codec`; an `o2b brain sources` / `brain_sources` read-only dashboard of signals by agent and source type; vault-map `{{role}}` tokens resolved via an optional `Brain/_vault-map.yaml` and wired into scan-inline read paths and graph import; named multi-vault profiles with `o2b vault profile` + a `brain_switch_vault` tool, activated by a pointer in config; and `o2b brain graph-export` / `graph-import` for moving a vault's knowledge graph between layouts with skip/overwrite/merge conflict modes). Browse [`docs/cli-reference.md`](docs/cli-reference.md) for every verb and [`docs/how-it-works.md`](docs/how-it-works.md) for the mental model.
-The v0.26.0 surface adds audited schema mutation/admin tools, real-time lifecycle capture hooks for prompt markers and `brain_feedback` tool calls, CJK-aware FTS recall, and `brain_watchdog` / `o2b brain watchdog` recovery probes. The v0.27.0 surface adds recall-control and trust tools: structured search query documents, session focus, MCP `brain_recall_gate`, polarity-aware context lanes, and opt-in evidence packs for CLI/MCP search. The v0.28.0 surface adds a deterministic prompt-injection guard for automatically surfaced Brain context, agent-blind `$secret:NAME` references, and preview foundations for source-scoped forget, privacy-scanned knowledge packs, and oversized payload externalization. The v0.29.0 surface adds opt-in context receipts and recall telemetry, read-only context budget presets, pre-compaction extraction, and a continuity-backed session recall DAG. The v0.33.0 surface adds the Recall Trust Suite: relation-aware recall polarity for typed memory edges, an explicit retrieval feedback loop with bounded learned weights (`o2b search feedback` / `weights`, MCP `brain_recall_feedback`), time-aware recall (`--since` / `--until` with natural-language ranges), verified multi-record recall (per-token union records, IDF-weighted coverage, rare-term abstention), and a search-completeness verdict with a false-absence guard. The v0.34.0 surface adds the Token Diet: a budgeted SessionStart injection of `Brain/active.md` (default 8,000 chars, `active.inject_budget_chars`) with the post-compaction path moved to the supported SessionStart `compact` matcher, a once-per-session post-write reminder cadence, frontmatter escape-amplification fixed at the parser with a one-shot `o2b brain upgrade --apply` repair for already-corrupted preference files, three consolidated read tools (`brain_brief`, `brain_analytics`, `schema_inspect`) with 18 hidden deprecated aliases, registry description caps with a contract guard, preview budgets by default, and a `scripts/measure-token-surface.ts` report. The v0.35.0 surface adds the Memory Integrity Suite: a canonical entity registry under `Brain/entities/` (one Markdown entity per `(category, name)` with alias resolution, archive/restore, typed relations, `o2b brain entity` CLI verbs, a read-only `brain_entity` MCP tool, doctor duplicate/relation lints, and alias-aware search boost with `entity_canonical` explanations), per-device Brain log shards (`Brain/log/<date>.<deviceId>.jsonl` + `.md` keyed by a device-local id, merged reads through `readLogDay`/`listLogDates`, no more Syncthing write conflicts, legacy days untouched), capture boundaries (a `sessions:` block with ignored/stateless session globs and message suppression regexes, applied before any extraction at both live-hook and import seams, counted but never stored raw; keep suppression regexes simple - they run on every message, and a catastrophic-backtracking pattern slows capture), and deterministic regex fact extraction (seven precision-first families over user turns, `source_type: extracted` signals with family-scoped dedup and canonical entity anchors). The v0.36.0 surface adds the Embedding Provider Suite: an offline `local` embedding provider (deterministic feature hashing, no cloud, no key, no model download - set `embedding_provider: local` for a privacy-first recall path), a CLI provider registry (`o2b search provider add | list | show | remove`, persisted to `Brain/search/embedding-providers.json` storing only environment-variable names, resolved after the built-ins so a configured key is never shadowed), an embedding cost gate (`embedding_cost_gate_usd`, default 0 = off; refuses an over-budget run unless `o2b search index --force-cost`) with the active `<provider>:<model>:<dimension>` signature and a refresh-cost estimate in `o2b search status`, and an opt-in Reciprocal Rank Fusion mode (`search_fusion_mode: rrf`, `search_rrf_k` default 60) that fuses the keyword and semantic lanes by rank position instead of weighted magnitude while the default `linear` mode stays bit-identical and storage remains SQLite + sqlite-vec + FTS5. The v0.37.0 surface adds the Agent Surface Suite: skills as callable MCP tools (`list_skills` / `get_skill` over the shipped `skills/` plus vault-local `Brain/skills/`), two-pass tool catalog hydration (a compact `catalog` scope where `tool_hydrate` returns the sorted catalog and per-name full schemas while every tool stays callable), five named tool-surface profiles with fail-open fallback (`mcp_tool_profile` / `o2b mcp --tool-profile`), deterministic BM25-style skill auto-attach (`skills_attach`, gated by `skill_auto_attach`), config-level capture role filtering (`session_capture_roles`), session-scoped search focus with SessionEnd auto-clear and gated context-pack promotion (`--session`, `focus_session`, `search_focus_context_pack`), operator-readable handoff notes (`o2b brain handoff`, gated SessionEnd generation via `session_handoff`), and scoped current-intention chains with a move-to-history lifecycle (`o2b brain intention`, MCP `brain_intention`). The v0.38.0 surface adds the Workspace Insight Suite: project vault pointers (`o2b brain project link | list | remove | status` writes a `.o2b-vault.json` into any project directory and `resolveVault` honours it from anywhere under that tree), read-only recall sources (`o2b brain source add | list | remove` with self/duplicate/circular validation and BROKEN flagging), cross-vault union search (`o2b search <query> --global`, `brain_search { global: true }` - origin-labelled results, external vaults never written to), a configurable wikilink path format (`wiki_link_format`: preserve/full/short plus `o2b brain links normalize`), a shell-native surface (`o2b brain profile` materializes `Brain/profile.md` + a `.o2bfs` root marker; `o2b brain sgrep` is grep-shaped semantic search), a grounded trigger queue with an anti-nag lifecycle (`o2b brain trigger scan | list | ack | dismiss | act | history`, MCP `brain_trigger`, cooldown-key dedup, morning-brief delivery once per `trigger_cooldown_days`), deep vault synthesis (`o2b brain deep-synthesis <topic>`, MCP `brain_deep_synthesis` - a deterministic dossier of agreements, contradictions, stale claims, and knowledge gaps), idea discovery (`o2b brain ideas`, MCP `brain_idea_discovery`), and opt-in recall-gate telemetry (`recall_gate_telemetry`, hashed prompts only, gate_list / gate_summary operations). The v0.39.0 surface adds the Memory Observability Suite: a contract-wide continuity schema version (`o2b.continuity.v1`, legacy records read as v1, dedup ids unchanged), a lazy gated telemetry emit kernel with structural no-consumer and fail-open guarantees across every gated surface, a continuity read-model with private-record masking shared by all read-side consumers, ATOF/ATIF trajectory export (`o2b brain continuity export --format atof|atif` - read-only, redaction honoured), a deterministic memory quality benchmark (`o2b brain bench memory` with checkpoint/resume and separate quality/latency/context-cost reporting), and the `docs/observability.md` contract enumerating every event kind, gate, and safety rule. The v0.40.0 surface adds the Project History Suite: git history as project memory (`o2b brain git ingest | status | find | mine` - a sanitized read-only reader lands commits, tags, and release ranges in a per-repo record store under `Brain/projects/git/<repo-key>/` with watermarked duplicate-free incremental runs, a deterministic FTS-discoverable digest note, store-only history queries that survive checkout deletion, and decision-shaped commits mined into draft ADR candidates under `Brain/decisions/candidates/` with sha-stable skip-existing identity), regeneration-safe architecture notes (`o2b brain architect <project-path>` - a stdlib-only deterministic scanner renders overview and per-module notes through paired `o2b:begin`/`o2b:end` sentinel regions, so operator prose survives every re-scan byte-for-byte and corrupted markers fail closed), and `brain_query` recall telemetry (per-call opt-in mirroring `brain_search`, kind-only payload - the supplied preference id, topic, or timestamp never lands in a continuity record). The v0.41.0 surface adds the Agent Write Contract Suite: provider-agnostic write sessions (`o2b brain session`, MCP `brain_write_session` - a file-backed JSON-envelope lifecycle where the calling agent generates, the Brain validates fail-closed with machine-readable correction errors and a retry cap, collisions never overwrite without explicit intent, operator review gates are opt-in, and every terminal transition is audited), a multi-persona decision panel riding the same kernel (`o2b brain panel` with operator-curated personas under `Brain/personas/` and committed decision notes under `Brain/decisions/panels/`), a pluggable memory backend boundary (`memory_backend` config key, Claude Code adapter byte-identical by default), and an opt-in cross-agent shared namespace (`shared_namespace` mirrors feedback signals and notes into a second vault fail-soft, with agent and origin attribution). The v0.42.0 surface adds the Time-Aware Recall & Activation Suite: access-reinforced activation (CLI/MCP searches record surfaced documents as hashed one-file-per-access events; a bounded `activation` ranking boost decays stored strength by a content-type half-life table where preferences and decisions never fade; `o2b brain activation status | sweep` inspects and compacts the store), co-access reinforcement edges (habitual companions in the same candidate pool boost each other with a bounded `co_access` reason), dream-stamped `freshness_trend` on preferences (`new | strengthening | stable | weakening | stale` from the evidence time distribution, multiplying the relevance portion of recall), event-time recall discipline (`since`/`until` filters obey declared `valid_from`/`valid_until` validity windows by overlap, with mtime only as the fallback), temporal-bridge traversal (time-scoped queries pull in linked causes and consequences from a padded event-time neighbourhood instead of leaking arbitrary old neighbours), and self-correcting two-pass recall (a zero-candidate evidence-pack query runs exactly one broadened OR retry, reported as `secondPass`). The v0.43.0 surface adds the Entity Truth & Self-Improving Dream Suite: an append-only entity claim ledger under `Brain/truth/` (device-sharded JSONL claim events folded into per-`(entity, aspect)` slots with current value, superseded history, temporal-structural `value_conflict` detection that is always `ask_user`, exact-match quantity aggregation, and `o2b brain truth` / MCP `brain_truth` surfaces), deterministic atomic-fact decomposition (`o2b brain facts decompose`, markdown-structure splitting with an abbreviation guard and optional `--ingest` into the ledger), an actor-framed `quantity` fact family, a name-aware merge guard (`entity-guard` refusal with `--force` bypass) plus an `entity_contamination` deep-synthesis dimension, push-mode cross-agent collision triggers (`agent_collision` kind with cooldown dedup), outcome-tied apply-evidence (`outcome: success|failure|unknown` staging `outcome_regressions` with a deterministic confidence penalty), a markdown-first dead-end registry (`o2b brain dead-end`, MCP `brain_dead_ends` - negative knowledge FTS-recallable beside positive rules), surprisal novelty ranking on `brain_review_candidates` over the existing sqlite-vec index, a weekly `topSource` nomination in the weekly synthesis, and the Brain's first forward-looking fold (`o2b brain foresight`, MCP `brain_foresight` - recurrence cadences project next-due routines, open commitments and questions surface with sources). The v0.44.0 surface adds the Write-Time Integrity & Governance Suite: schema-pack ontology fields (controlled-vocabulary `labels`, per-link-type `link_constraints` endpoint pairs, per-type `attributes` descriptors, and a `frontmatter_tiers` map - all additive with audited mutations), fail-closed label classification (`o2b brain label`, MCP `brain_labels` - unknown dimensions and values are rejected with the declared vocabulary, persisted as a filterable frontmatter array plus a canonical label entity), link-type endpoint constraints enforced at index materialization (violating typed edges fall back to untyped links, surfaced by `schema lint` and restored automatically when the constraint is removed), per-type attribute fields whose validation errors teach the declared vocabulary (`o2b brain attr`), a four-level frontmatter tier guard (identity/system/business/user with built-in framework defaults, a tier-respecting merge in framework writers, index-time identity-drift detection that never absorbs a hand-edit, and the staged `o2b brain tiers check | restore | accept` repair surface, MCP `brain_tiers`), capability-gated secret custody (`o2b brain secret set | list | rm | run`, MCP `brain_secrets` - per-value AES-256-GCM ciphertext under the vault-local state dir, stdin-only ingestion, allowlist-gated subprocess env injection with redacted output, and a no-values audit trail in `Brain/log/secret-custody/`), and a quiet-window lease-guarded maintenance lane (`o2b brain maintenance run | status`, MCP `brain_maintenance` - a tz-aware hour window, a recall-telemetry busy gate, an expiring SQLite lease no second worker can grab, stale-first task ordering, and a bounded journal of every attempt including gate refusals).
+The v0.26.0 surface adds audited schema mutation/admin tools, real-time lifecycle capture hooks for prompt markers and `brain_feedback` tool calls, CJK-aware FTS recall, and `brain_watchdog` / `o2b brain watchdog` recovery probes. The v0.27.0 surface adds recall-control and trust tools: structured search query documents, session focus, MCP `brain_recall_gate`, polarity-aware context lanes, and opt-in evidence packs for CLI/MCP search. The v0.28.0 surface adds a deterministic prompt-injection guard for automatically surfaced Brain context, agent-blind `$secret:NAME` references, and preview foundations for source-scoped forget, privacy-scanned knowledge packs, and oversized payload externalization. The v0.29.0 surface adds opt-in context receipts and recall telemetry, read-only context budget presets, pre-compaction extraction, and a continuity-backed session recall DAG. The v0.33.0 surface adds the Recall Trust Suite: relation-aware recall polarity for typed memory edges, an explicit retrieval feedback loop with bounded learned weights (`o2b search feedback` / `weights`, MCP `brain_recall_feedback`), time-aware recall (`--since` / `--until` with natural-language ranges), verified multi-record recall (per-token union records, IDF-weighted coverage, rare-term abstention), and a search-completeness verdict with a false-absence guard. The v0.34.0 surface adds the Token Diet: a budgeted SessionStart injection of `Brain/active.md` (default 8,000 chars, `active.inject_budget_chars`) with the post-compaction path moved to the supported SessionStart `compact` matcher, a once-per-session post-write reminder cadence, frontmatter escape-amplification fixed at the parser with a one-shot `o2b brain upgrade --apply` repair for already-corrupted preference files, three consolidated read tools (`brain_brief`, `brain_analytics`, `schema_inspect`) with 18 hidden deprecated aliases, registry description caps with a contract guard, preview budgets by default, and a `scripts/measure-token-surface.ts` report. The v0.35.0 surface adds the Memory Integrity Suite: a canonical entity registry under `Brain/entities/` (one Markdown entity per `(category, name)` with alias resolution, archive/restore, typed relations, `o2b brain entity` CLI verbs, a read-only `brain_entity` MCP tool, doctor duplicate/relation lints, and alias-aware search boost with `entity_canonical` explanations), per-device Brain log shards (`Brain/log/<date>.<deviceId>.jsonl` + `.md` keyed by a device-local id, merged reads through `readLogDay`/`listLogDates`, no more Syncthing write conflicts, legacy days untouched), capture boundaries (a `sessions:` block with ignored/stateless session globs and message suppression regexes, applied before any extraction at both live-hook and import seams, counted but never stored raw; keep suppression regexes simple - they run on every message, and a catastrophic-backtracking pattern slows capture), and deterministic regex fact extraction (seven precision-first families over user turns, `source_type: extracted` signals with family-scoped dedup and canonical entity anchors). The v0.36.0 surface adds the Embedding Provider Suite: an offline `local` embedding provider (deterministic feature hashing, no cloud, no key, no model download - set `embedding_provider: local` for a privacy-first recall path), a CLI provider registry (`o2b search provider add | list | show | remove`, persisted to `Brain/search/embedding-providers.json` storing only environment-variable names, resolved after the built-ins so a configured key is never shadowed), an embedding cost gate (`embedding_cost_gate_usd`, default 0 = off; refuses an over-budget run unless `o2b search index --force-cost`) with the active `<provider>:<model>:<dimension>` signature and a refresh-cost estimate in `o2b search status`, and an opt-in Reciprocal Rank Fusion mode (`search_fusion_mode: rrf`, `search_rrf_k` default 60) that fuses the keyword and semantic lanes by rank position instead of weighted magnitude while the default `linear` mode stays bit-identical and storage remains SQLite + sqlite-vec + FTS5. The v0.37.0 surface adds the Agent Surface Suite: skills as callable MCP tools (`list_skills` / `get_skill` over the shipped `skills/` plus vault-local `Brain/skills/`), two-pass tool catalog hydration (a compact `catalog` scope where `tool_hydrate` returns the sorted catalog and per-name full schemas while every tool stays callable), five named tool-surface profiles with fail-open fallback (`mcp_tool_profile` / `o2b mcp --tool-profile`), deterministic BM25-style skill auto-attach (`skills_attach`, gated by `skill_auto_attach`), config-level capture role filtering (`session_capture_roles`), session-scoped search focus with SessionEnd auto-clear and gated context-pack promotion (`--session`, `focus_session`, `search_focus_context_pack`), operator-readable handoff notes (`o2b brain handoff`, gated SessionEnd generation via `session_handoff`), and scoped current-intention chains with a move-to-history lifecycle (`o2b brain intention`, MCP `brain_intention`). The v0.38.0 surface adds the Workspace Insight Suite: project vault pointers (`o2b brain project link | list | remove | status` writes a `.o2b-vault.json` into any project directory and `resolveVault` honours it from anywhere under that tree), read-only recall sources (`o2b brain source add | list | remove` with self/duplicate/circular validation and BROKEN flagging), cross-vault union search (`o2b search <query> --global`, `brain_search { global: true }` - origin-labelled results, external vaults never written to), a configurable wikilink path format (`wiki_link_format`: preserve/full/short plus `o2b brain links normalize`), a shell-native surface (`o2b brain profile` materializes `Brain/profile.md` + a `.o2bfs` root marker; `o2b brain sgrep` is grep-shaped semantic search), a grounded trigger queue with an anti-nag lifecycle (`o2b brain trigger scan | list | ack | dismiss | act | history`, MCP `brain_trigger`, cooldown-key dedup, morning-brief delivery once per `trigger_cooldown_days`), deep vault synthesis (`o2b brain deep-synthesis <topic>`, MCP `brain_deep_synthesis` - a deterministic dossier of agreements, contradictions, stale claims, and knowledge gaps), idea discovery (`o2b brain ideas`, MCP `brain_idea_discovery`), and opt-in recall-gate telemetry (`recall_gate_telemetry`, hashed prompts only, gate_list / gate_summary operations). The v0.39.0 surface adds the Memory Observability Suite: a contract-wide continuity schema version (`o2b.continuity.v1`, legacy records read as v1, dedup ids unchanged), a lazy gated telemetry emit kernel with structural no-consumer and fail-open guarantees across every gated surface, a continuity read-model with private-record masking shared by all read-side consumers, ATOF/ATIF trajectory export (`o2b brain continuity export --format atof|atif` - read-only, redaction honoured), a deterministic memory quality benchmark (`o2b brain bench memory` with checkpoint/resume and separate quality/latency/context-cost reporting), and the `docs/observability.md` contract enumerating every event kind, gate, and safety rule. The v0.40.0 surface adds the Project History Suite: git history as project memory (`o2b brain git ingest | status | find | mine` - a sanitized read-only reader lands commits, tags, and release ranges in a per-repo record store under `Brain/projects/git/<repo-key>/` with watermarked duplicate-free incremental runs, a deterministic FTS-discoverable digest note, store-only history queries that survive checkout deletion, and decision-shaped commits mined into draft ADR candidates under `Brain/decisions/candidates/` with sha-stable skip-existing identity), regeneration-safe architecture notes (`o2b brain architect <project-path>` - a stdlib-only deterministic scanner renders overview and per-module notes through paired `o2b:begin`/`o2b:end` sentinel regions, so operator prose survives every re-scan byte-for-byte and corrupted markers fail closed), and `brain_query` recall telemetry (per-call opt-in mirroring `brain_search`, kind-only payload - the supplied preference id, topic, or timestamp never lands in a continuity record). The v0.41.0 surface adds the Agent Write Contract Suite: provider-agnostic write sessions (`o2b brain session`, MCP `brain_write_session` - a file-backed JSON-envelope lifecycle where the calling agent generates, the Brain validates fail-closed with machine-readable correction errors and a retry cap, collisions never overwrite without explicit intent, operator review gates are opt-in, and every terminal transition is audited), a multi-persona decision panel riding the same kernel (`o2b brain panel` with operator-curated personas under `Brain/personas/` and committed decision notes under `Brain/decisions/panels/`), a pluggable memory backend boundary (`memory_backend` config key, Claude Code adapter byte-identical by default), and an opt-in cross-agent shared namespace (`shared_namespace` mirrors feedback signals and notes into a second vault fail-soft, with agent and origin attribution). The v0.42.0 surface adds the Time-Aware Recall & Activation Suite: access-reinforced activation (CLI/MCP searches record surfaced documents as hashed one-file-per-access events; a bounded `activation` ranking boost decays stored strength by a content-type half-life table where preferences and decisions never fade; `o2b brain activation status | sweep` inspects and compacts the store), co-access reinforcement edges (habitual companions in the same candidate pool boost each other with a bounded `co_access` reason), dream-stamped `freshness_trend` on preferences (`new | strengthening | stable | weakening | stale` from the evidence time distribution, multiplying the relevance portion of recall), event-time recall discipline (`since`/`until` filters obey declared `valid_from`/`valid_until` validity windows by overlap, with mtime only as the fallback), temporal-bridge traversal (time-scoped queries pull in linked causes and consequences from a padded event-time neighbourhood instead of leaking arbitrary old neighbours), and self-correcting two-pass recall (a zero-candidate evidence-pack query runs exactly one broadened OR retry, reported as `secondPass`). The v0.43.0 surface adds the Entity Truth & Self-Improving Dream Suite: an append-only entity claim ledger under `Brain/truth/` (device-sharded JSONL claim events folded into per-`(entity, aspect)` slots with current value, superseded history, temporal-structural `value_conflict` detection that is always `ask_user`, exact-match quantity aggregation, and `o2b brain truth` / MCP `brain_truth` surfaces), deterministic atomic-fact decomposition (`o2b brain facts decompose`, markdown-structure splitting with an abbreviation guard and optional `--ingest` into the ledger), an actor-framed `quantity` fact family, a name-aware merge guard (`entity-guard` refusal with `--force` bypass) plus an `entity_contamination` deep-synthesis dimension, push-mode cross-agent collision triggers (`agent_collision` kind with cooldown dedup), outcome-tied apply-evidence (`outcome: success|failure|unknown` staging `outcome_regressions` with a deterministic confidence penalty), a markdown-first dead-end registry (`o2b brain dead-end`, MCP `brain_dead_ends` - negative knowledge FTS-recallable beside positive rules), surprisal novelty ranking on `brain_review_candidates` over the existing sqlite-vec index, a weekly `topSource` nomination in the weekly synthesis, and the Brain's first forward-looking fold (`o2b brain foresight`, MCP `brain_foresight` - recurrence cadences project next-due routines, open commitments and questions surface with sources). The v0.44.0 surface adds the Write-Time Integrity & Governance Suite: schema-pack ontology fields (controlled-vocabulary `labels`, per-link-type `link_constraints` endpoint pairs, per-type `attributes` descriptors, and a `frontmatter_tiers` map - all additive with audited mutations), fail-closed label classification (`o2b brain label`, MCP `brain_labels` - unknown dimensions and values are rejected with the declared vocabulary, persisted as a filterable frontmatter array plus a canonical label entity), link-type endpoint constraints enforced at index materialization (violating typed edges fall back to untyped links, surfaced by `schema lint` and restored automatically when the constraint is removed), per-type attribute fields whose validation errors teach the declared vocabulary (`o2b brain attr`), a four-level frontmatter tier guard (identity/system/business/user with built-in framework defaults, a tier-respecting merge in framework writers, index-time identity-drift detection that never absorbs a hand-edit, and the staged `o2b brain tiers check | restore | accept` repair surface, MCP `brain_tiers`), capability-gated secret custody (`o2b brain secret set | list | rm | run`, MCP `brain_secrets` - per-value AES-256-GCM ciphertext under the vault-local state dir, stdin-only ingestion, allowlist-gated subprocess env injection with redacted output, and a no-values audit trail in `Brain/log/secret-custody/`), and a quiet-window lease-guarded maintenance lane (`o2b brain maintenance run | status`, MCP `brain_maintenance` - a tz-aware hour window, a recall-telemetry busy gate, an expiring SQLite lease no second worker can grab, stale-first task ordering, and a bounded journal of every attempt including gate refusals). The v0.45.0 surface adds the Link & Recall Intelligence Suite: vault-wide frontmatter alias resolution materialized at index time (schema v7 `doc_aliases`, shadowing-safe, exact paths always win), orphan-first bridge discovery over the vec index (`o2b brain bridges discover | list | accept | dismiss`, MCP `brain_bridges` - embedding-near unlinked pairs land in a reviewable `Brain/proposals/bridges.md`, accept writes one `related:` wikilink honoring schema-pack link constraints, dismissals persist), deterministic graph-wide community detection with derived cluster digests (`o2b brain clusters run | list`, MCP `brain_clusters` - label propagation with a stable tie-break, `Brain/clusters/` notes regenerate per run, hand-written files untouched), a reproducible recall benchmark with a committed fixture dataset and CI thresholds (`o2b brain benchmark run`, MCP `brain_benchmark` - hit@k and MRR against the live hybrid pipeline), deterministic query expansion into the structured lex/vec/hyde lanes (`o2b search --expand` - stopword-stripped lex terms, entity-context vec line, template hyde passage, no model and no paid call), opt-in self-tuning recall judged by the benchmark (`o2b brain tune run | status | reset`, MCP `brain_tune` - a bounded replayable grid persisted to `Brain/search/tuning.json`, applied only under `search_self_tuning_enabled`), and a dashboard-ready run-level metrics layer (`Brain/metrics/<surface>.jsonl`, schema `o2b.metrics.v1`, contract in `docs/metrics.md`).
## CLI
diff --git a/docs/brainstorm/link-recall-intelligence/cli-output/claude.md b/docs/brainstorm/link-recall-intelligence/cli-output/claude.md
new file mode 100644
index 00000000..e25ce88b
--- /dev/null
+++ b/docs/brainstorm/link-recall-intelligence/cli-output/claude.md
@@ -0,0 +1,35 @@
+### Variant 1: Index-native (everything in the search SQLite)
+- **Approach**: Push all six features into the search index via an additive schema v7 migration. Bridges and communities become pending-proposal rows, alias resolution extends `resolveLinkTargets`, query-expansion output and self-tuning parameters are stored tables, and the uniform metrics layer is a single `metrics(surface, run_at, payload)` table in the same SQLite. Graph algorithms (community detection, orphan ranking) run as recursive CTEs / post-passes in `indexer.ts` directly over the `links` table.
+- **Trade-offs**:
+ - Pro: one transactional store, no cross-store sync; graph queries are fast and natural over the existing links table; alias fix lands exactly where the gap is.
+ - Pro: self-tuning objective function (benchmark scores) is queryable with SQL — trivial closed-loop reads.
+ - Con: dashboard plugin must open OSB's SQLite and bind to its schema, violating "readable without importing internals / stable on-disk contract" unless an exporter is also built.
+ - Con: proposals-as-rows are less reviewable than markdown; weakens the "reviewable artifact before mutating notes" constraint.
+ - Con: couples bridge/community generation to index lifecycle rather than the maintenance lane.
+- **Complexity**: large
+- **Risk**: high
+
+### Variant 2: Vault-native (Brain/ artifacts + single JSONL metrics layer)
+- **Approach**: Express bridge proposals and synthesized cluster notes as reviewable markdown artifacts under `Brain/` (mirroring dream dry-run / staged tier-drift repair), persist self-tuning state alongside `feedback.ts` as bounded replayable JSON, and make the uniform metrics layer a single append-only `Brain/metrics/*.jsonl` log that every feature writes to. Only the alias fix and benchmark touch SQLite/tests; community detection and orphan ranking read the links table into memory and emit markdown.
+- **Trade-offs**:
+ - Pro: dashboard reads plain JSONL with no OSB internals — cleanest satisfaction of the cross-cutting contract; idiomatic with existing per-event JSON feedback and Brain/log sidecars.
+ - Pro: proposals/derived notes are inherently reviewable and participate in recall as real notes; matches deterministic/replayable philosophy.
+ - Con: graph algorithms still must pull the graph out of SQLite each run — duplicated read path, weaker for large graphs.
+ - Con: self-tuning's objective function (benchmark scores) requires scanning/parsing JSONL rather than querying — replayable but less ergonomic.
+ - Con: scattering compute across Brain/ modules risks inconsistent metric emission unless a shared sink is enforced.
+- **Complexity**: medium
+- **Risk**: low
+
+### Variant 3: Hybrid layered (lane-orchestrated compute, Brain/ artifacts, dual-write metrics)
+- **Approach**: Heavy graph passes (bridge discovery, Louvain community detection, orphan/backlink ranking) run as maintenance-lane passes over the SQLite `links` table; their outputs are reviewable `Brain/` proposal and derived-cluster artifacts. The alias fix lands in `resolveLinkTargets`; expansion is a deterministic producer feeding the existing parser; self-tuning mirrors the learned-weights fold. The metrics layer is dual-write: a queryable `metrics` table (source of truth, v7 migration) plus a deterministic `Brain/metrics/*.jsonl` projection that is the dashboard's stable contract. A shared `MetricsSink` interface and a common `Proposal` artifact contract bind all six features.
+- **Trade-offs**:
+ - Pro: each task uses its right substrate — SQL for graph math, markdown for review, JSONL for the dashboard — while a single sink keeps emission uniform.
+ - Pro: fits conventions exactly (maintenance-lane window+lease for periodic work, reviewable proposals, deterministic projection, additive v7).
+ - Pro: self-tuning queries the metrics table efficiently yet the dashboard never imports internals.
+ - Con: dual-write adds a projection surface that must stay deterministic and consistent (table → JSONL replay).
+ - Con: most moving parts; largest of the three within the ~50-70 file PR; shared abstractions add up-front design cost.
+- **Complexity**: large
+- **Risk**: medium
+
+### Recommended: Variant 3
+**Rationale**: It is the only variant that simultaneously honors the two hardest constraints — graph algorithms want SQLite's transactional link table, while the dashboard needs a stable on-disk contract with no internal coupling — by computing in SQL and projecting deterministically to `Brain/metrics/` JSONL. It also slots cleanly into established conventions (maintenance lane for heavy periodic passes, reviewable proposal artifacts, bounded replayable folds, single additive v7 migration), where Variant 1 breaks the dashboard-decoupling and reviewability constraints and Variant 2 weakens graph performance and the self-tuning objective-function read path. The added dual-write surface is a deterministic, replayable projection rather than true sync, keeping it within the project's deterministic-first discipline.
diff --git a/docs/brainstorm/link-recall-intelligence/cli-output/prompt.md b/docs/brainstorm/link-recall-intelligence/cli-output/prompt.md
new file mode 100644
index 00000000..c5d380c2
--- /dev/null
+++ b/docs/brainstorm/link-recall-intelligence/cli-output/prompt.md
@@ -0,0 +1,104 @@
+You are brainstorming architectural variants for the following task. Do not write code. Do not write a final design. Only produce variants and a recommendation.
+
+# Task
+
+Release epic "Link & Recall Intelligence Suite" - six kanban tasks shipping as one PR. The graph self-organizes, recall quality becomes measurable, and every feature publishes metrics for an upcoming dashboard plugin.
+
+## Task 1 (t_ab540afe, p3) - Bridge discovery: propose links between embedding-near unconnected notes
+
+Upstream (mazemaker REM phase): sample isolated/under-connected memories, run batched semantic recall to find related memories not already linked, write bridge edges weighted by similarity. Connects clusters that share no wikilink or textual mention - pure embedding adjacency.
+
+OSB today: traversal only follows EXISTING links (applyTraversal walks outbound edges); findUnlinkedMentions only flags TEXTUAL occurrences of a known title. Nothing proposes a connection between two notes that are embedding-near but never name each other. A second discovery signal from an article: rank notes by inbound-link count and prioritize orphans (low backlink count).
+
+## Task 2 (t_d6660a83, p3) - Frontmatter alias resolution for wikilinks
+
+Upstream (llm-wiki-compiler): when a page declares `aliases: [...]` in frontmatter, wikilinks pointing to any alias resolve to that page.
+
+OSB today: `src/core/brain/link-graph/alias-index.ts` exists but only scans `Brain/preferences/` + `Brain/retired/` (used by backlinks/unlinked-mentions for Brain artifacts). The SEARCH INDEX materialization (`src/core/search/store.ts` resolveLinkTargets + basename SUBSTR fallback joins) knows nothing about aliases: a wikilink `[[PA]]` to a note titled "Project Alpha" with `aliases: [PA]` stays unresolved in the links table, so traversal/backlinks/link-constraints miss it.
+
+## Task 3 (t_e2215d49, p3, re-scoped) - Reproducible recall benchmark with fixed dataset and regression tests
+
+Upstream (yantrikdb-hermes-plugin): benchmark runner + fixed query/expected-result dataset + tests asserting recall quality thresholds in CI.
+
+OSB re-scope (the miner referenced a nonexistent src/core/brain/yantrikdb/ dir): benchmark OSB's OWN hybrid search (FTS5 + sqlite-vec + fusion + ranker, src/core/search/). Fixed vault fixture + fixed query set with expected results, metrics (hit@k, MRR), thresholds asserted in bun tests so ranking regressions fail CI deterministically (deterministic local embedding provider exists for tests).
+
+## Task 4 (t_4ba927ec, p2) - Community detection materializing synthesized cluster summary notes
+
+Upstream (mazemaker Insight phase): Louvain community detection over the consolidated link graph; for each community of size >= 4, materialize a synthetic derived-cluster summary note capturing the cluster; derived notes participate in later recall.
+
+OSB today: buildConceptCluster only assembles depth-1 backlinks for ONE explicitly-named target; concept-gap detects uncovered entities. No graph-wide community discovery, no synthesized per-cluster note. The links table in the search index is the natural input graph.
+
+## Task 5 (t_2fa95db1, p2) - Local query expansion into structured lex/vec/hyde lanes
+
+Upstream (flowstate-qmd): a local model turns a raw query like "auth config" into structured expansions: lex: keyword lines for BM25, vec: natural-language lines for vector search, hyde: hypothetical-document passage.
+
+OSB today: `src/core/search/structured-query.ts` PARSES a structured lex/vec/hyde query document (consumer exists), but lanes must be authored upstream by the caller. No producer. Constraint: deterministic expansion contract preferred (no GGUF/local-model dependency, no paid calls) - synonym table, entity registry, heuristics are available building blocks (`src/core/search/synonyms.ts`, entity registry, CJK tokenizer).
+
+## Task 6 (t_ae973491, p2) - Opt-in self-tuning recall with persisted feedback
+
+Upstream (yantrikdb-hermes-plugin): env-flag-gated adaptive recall parameter tuning (k, score thresholds), feedback persisted across sessions, closed-loop improvement from recall outcomes.
+
+OSB today: `src/core/search/feedback.ts` ALREADY implements explicit up/down recall feedback events (one JSON file per event under Brain/search/feedback/) folded deterministically into bounded per-layer weight multipliers (learned-weights.json, [0.8, 1.2]). The gap: nothing tunes retrieval PARAMETERS (top-k, score thresholds, traversal depth); the fold only adjusts layer weights. Self-tuning must stay opt-in, deterministic, bounded, and replayable - same philosophy as the existing fold. The recall benchmark (Task 3) is the natural objective function / guardrail.
+
+## Cross-cutting constraint - Dashboard-ready metrics layer
+
+A dashboard plugin showing project metrics ships in a near-future cycle. EVERY feature above must publish its run metrics (bridge proposals generated/accepted, alias resolutions, benchmark scores over time, community count/sizes, expansion usage, tuning state) into ONE uniform, machine-readable, append-friendly metrics layer the dashboard can read without scraping logs. Today metrics are scattered: recall-telemetry.ts, gate-telemetry.ts, IndexStats, Brain/log JSONL sidecars. Decide: where the uniform layer lives (Brain/metrics/ JSONL? a metrics table in the search SQLite? both?), its schema (surface, run_at, payload), and how existing telemetry relates to it.
+
+# Project context
+
+Open Second Brain - TypeScript/Bun CLI + MCP server managing an Obsidian-compatible markdown vault with a hybrid search index (SQLite: FTS5 + sqlite-vec + link graph), a deterministic learning loop (dream), entity registry, schema packs (write-time ontology governance since v0.44.0), and 73 MCP tools.
+
+Recent commits:
+789e3e3 feat: Write-Time Integrity & Governance Suite - schema ontology, tier guard, secret custody, maintenance lane (#76)
+c03d569 fix(hermes): root cli.py shim completes the upstream CLI discovery contract (#75)
+a0054dd feat: Entity Truth & Self-Improving Dream Suite - claim ledger, outcome-aware dream, foresight (#74)
+b16c37d feat: Time-Aware Recall & Activation Suite - usage-aware ranking, event-time recall, two-pass recovery (#73)
+c3a2fcc feat: Agent Write Contract Suite - write sessions, decision panel, backend boundary, shared namespace (#72)
+
+Related files:
+- src/core/search/store.ts (links table, resolveLinkTargets, typed-relation readers, schema v6)
+- src/core/search/indexer.ts (incremental pass, post-passes: relation constraints, tier guard)
+- src/core/search/schema.ts (migrations v1-v6, LATEST_SCHEMA_VERSION=6)
+- src/core/search/search.ts (hybrid pipeline: fts, vec, fusion, ranker, traversal, property filters)
+- src/core/search/feedback.ts (explicit feedback events -> bounded learned weights fold)
+- src/core/search/structured-query.ts (lex/vec/hyde document parser - consumer side)
+- src/core/search/embeddings/{provider,registry,local-provider,null-provider,openai-compat}.ts
+- src/core/search/synonyms.ts, src/core/search/entities.ts, src/core/search/traversal.ts
+- src/core/brain/link-graph/{alias-index,unlinked-mentions,concept-cluster,moc-audit}.ts
+- src/core/brain/recall-telemetry.ts, src/core/brain/gate-telemetry.ts
+- src/core/brain/maintenance/lane.ts (leased maintenance lane, v0.44.0 - natural host for periodic passes)
+- src/cli/brain/verbs/, src/mcp/brain-tools.ts (verb + MCP tool registration patterns)
+
+Conventions:
+- TDD, atomic conventional commits, oxlint + oxfmt before every commit, bun test (4091 tests / 526 files)
+- Schema migrations are versioned (v6 latest); new tables ship as one migration with LATEST_SCHEMA_VERSION bump
+- Deterministic-first: pure folds, replayable derivations, no wall-clock/randomness in core logic (clock injected via opts)
+- Fail-soft on missing index/providers; fail-closed on vocabulary/write validation
+- New CLI verbs register in 5 places (brain.ts, verbs/index.ts, help-text.ts x2, command-manifest.ts); MCP tool descriptions capped at 300 chars; tool count pinned in tests
+- Heavy periodic work belongs in the maintenance lane (window + busy gate + lease)
+- Proposals/derived artifacts must be reviewable before they mutate canonical notes (cf. dream dry-run, staged tier-drift repair)
+
+Constraints:
+- No new external runtime dependencies (no GGUF models, no paid API calls in core paths; embedding provider abstraction already exists and tests use the deterministic local provider)
+- Bridge/community output must NOT silently mutate user notes: proposals must be reviewable artifacts (the operator or an agent accepts them)
+- Self-tuning must be opt-in, bounded, deterministic, replayable - mirroring the existing learned-weights fold contract
+- Do not break existing public APIs (search(), Store, MCP tool contracts); additive schema migration v7 is acceptable
+- The metrics layer must be readable by a future dashboard plugin without importing OSB internals (stable on-disk contract)
+- All six tasks ship in ONE PR (~50-70 files), each as its own atomic commit sequence
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. For each variant:
+
+### Variant N: <short name>
+- **Approach**: 2-3 sentences describing the variant.
+- **Trade-offs**: bullet list of pros and cons.
+- **Complexity**: small | medium | large
+- **Risk**: low | medium | high
+
+After the three variants, add exactly one recommendation:
+
+### Recommended: Variant N
+**Rationale**: 2-3 sentences explaining why this variant over the others, considering the project context and constraints above.
+
+Output nothing outside of these sections.
diff --git a/docs/brainstorm/link-recall-intelligence/design.md b/docs/brainstorm/link-recall-intelligence/design.md
new file mode 100644
index 00000000..a846faca
--- /dev/null
+++ b/docs/brainstorm/link-recall-intelligence/design.md
@@ -0,0 +1,182 @@
+# Link & Recall Intelligence Suite - the graph self-organizes and recall quality becomes measurable
+
+**Status:** approved
+**Author:** claude-dev-agent (via feature-release-playbook)
+**Audience:** implementation
+**Epic:** t_06a7cc0e; children t_ab540afe, t_d6660a83, t_e2215d49, t_4ba927ec, t_2fa95db1, t_ae973491
+
+## Problem statement
+
+The link graph only knows edges the operator (or an agent) wrote by hand:
+wikilinks to an alias stay unresolved in the search index, embedding-near
+notes that never name each other stay unconnected, and no surface discovers
+graph-wide structure. Meanwhile recall quality is unmeasured - there is no
+fixed-dataset benchmark, so ranking changes land blind - and retrieval
+parameters are static even though an explicit-feedback fold already exists.
+Every feature also produces numbers a near-future dashboard plugin needs, but
+today metrics are scattered across recall-telemetry, gate-telemetry,
+IndexStats, and Brain/log sidecars.
+
+## Scope
+
+- **Metrics sink** (cross-cutting): one append-only, schema-versioned JSONL
+ layer under `Brain/metrics/` that every feature in this suite writes
+ run-level records to; the stable on-disk contract the dashboard plugin
+ will read without importing OSB internals.
+- **Alias resolution** (t_d6660a83): vault-wide frontmatter `aliases`
+ resolution at search-index materialization - new `doc_aliases` table
+ (schema v7), indexer extraction, alias pass in `resolveLinkTargets`.
+- **Recall benchmark** (t_e2215d49, re-scoped): fixed fixture vault + fixed
+ query dataset, hit@k + MRR metrics, thresholds asserted in bun tests so
+ ranking regressions fail CI; on-demand CLI/MCP run against any vault.
+- **Bridge discovery** (t_ab540afe): orphan-first pass over the vec index
+ proposing links between embedding-near, unconnected notes; reviewable
+ proposal artifact with accept/dismiss lifecycle.
+- **Community detection** (t_4ba927ec): deterministic label propagation over
+ the links graph; communities of size >= 4 materialize derived cluster
+ notes under `Brain/clusters/`.
+- **Query expansion** (t_2fa95db1): deterministic producer of the existing
+ structured lex/vec/hyde query document from a bare query (synonyms +
+ entity registry + template hyde passage); opt-in `--expand`.
+- **Self-tuning recall** (t_ae973491): opt-in, bounded, replayable parameter
+ selection (candidate-pool multiplier, traversal depth, learned-weights
+ toggle, expansion toggle) by grid evaluation against the recall benchmark;
+ persisted to `Brain/search/tuning.json`.
+- CLI verbs (`links`, `clusters`, `benchmark`, `tune`, `search --expand`),
+ MCP tools, maintenance-lane task registration, docs incl. the dashboard
+ metrics contract.
+
+## Out of scope
+
+- LLM-generated prose in cluster notes or bridge reasons (core stays
+ deterministic; prose synthesis belongs to calling agents - same rule as
+ deep-synthesis).
+- Auto-applying bridge proposals to user notes (accept is operator/agent
+ initiated, per-pair).
+- A metrics SQLite table or any dashboard UI (the dashboard plugin is a
+ future cycle; this cycle ships only its data contract).
+- Local-model (GGUF) query expansion; embedding-provider changes.
+- Tuning the fusion weight constants themselves (the learned-weights fold
+ already owns per-layer multipliers; tuning composes with it, never
+ rewrites it).
+
+## Chosen approach
+
+Consultant Variant 3 (hybrid layered) with Variant 2's metrics substrate -
+override rationale recorded in `variants.md`. Heavy graph passes (bridge
+discovery, community detection) compute over the search SQLite `links` +
+`chunk_vec` tables and emit reviewable vault artifacts; the alias fix lands
+inside link materialization where the gap is; expansion and self-tuning are
+deterministic producers/folds beside the existing structured-query parser and
+learned-weights fold; all run-level numbers flow through one shared metrics
+sink writing `Brain/metrics/<surface>.jsonl`.
+
+## Design decisions
+
+- **Metrics envelope mirrors continuity records.** One JSON object per line:
+ `{schema: "o2b.metrics.v1", surface, run_at, payload}`. Additive-optional
+ fields do not bump the version; renames/removals do. One file per surface
+ (`Brain/metrics/recall_benchmark.jsonl`, `bridge_discovery.jsonl`,
+ `communities.jsonl`, `index.jsonl`, `self_tuning.jsonl`) so the dashboard
+ reads only what it renders. O_APPEND single-line writes (the maintenance
+ journal pattern); fail-soft reader `listMetrics`.
+- **Run-level only.** Per-search events stay in recall telemetry (existing
+ surface); `Brain/metrics/` records one line per index run / discovery pass
+ / benchmark / tuning run. Query-expansion usage rides the benchmark record
+ and recall-telemetry metadata instead of its own high-volume file.
+- **Aliases live in the index, not a second scan.** `doc_aliases(document_id,
+ alias)` populated by the indexer from frontmatter `aliases:` arrays
+ (NFC-normalised, lower-cased - the exact `alias-index.ts` normalisation).
+ `resolveLinkTargets` gains a second UPDATE pass: unresolved links whose
+ `target_path` contains no `/` join `doc_aliases`; collisions resolve
+ first-wins by sorted document path (same rule as `alias-index.ts`).
+ `IndexStats.aliasResolved` counts links the alias pass resolved.
+ The Brain-artifact `alias-index.ts` stays as-is (different consumer).
+- **Bridge discovery is orphan-first and read-only.** Candidates ranked by
+ inbound-link count ascending (the article's orphan signal); per candidate,
+ chunk embeddings KNN against `chunk_vec` (existing `vecSearch`), L2-on-unit
+ distance converted to cosine similarity, doc-level max aggregation, pairs
+ already linked in either direction excluded, deduped, thresholded, capped.
+ Output: regenerated `Brain/proposals/bridges.md` (kind `brain-bridge-
+ proposals`) listing pairs with similarity + inbound counts. Accept writes
+ `related: "[[target]]"` into the source note's frontmatter (one pair at a
+ time, validated); dismiss persists pair keys in
+ `Brain/proposals/bridges-dismissed.json` so re-runs stay quiet.
+- **Community detection is deterministic label propagation.** Undirected
+ doc-level graph from resolved links; labels initialised to sorted doc ids;
+ synchronous sweeps in sorted order with lowest-label tie-break; iteration
+ cap. No Louvain dependency, no randomness. Communities of size >= minSize
+ (default 4) materialize `Brain/clusters/<slug>.md` where slug derives from
+ the most-central member (highest internal degree, path tie-break). Cluster
+ notes are derived artifacts: regenerated each run, auto-generated header,
+ deterministic digest body (members by internal degree, shared entities from
+ `chunk_entities`, link density) - no LLM prose. Stale cluster notes (community
+ gone) are removed on the next run. `DEFAULT_TIER_MAP` gains a
+ `brain-cluster` entry so the tier guard treats regeneration as
+ framework-owned.
+- **Expansion is a producer for an existing parser.** `expandQuery` builds a
+ `StructuredRecallQueryDocument`: lex include = query tokens + bounded
+ synonym expansions (`deriveExpansionTerms`); vec = raw query + one
+ entity-context line when registry entities match; hyde = one deterministic
+ template passage naming the query and matched entities. Opt-in per call
+ (`expand: true` / `--expand`); never silently active, so cached queries and
+ benchmarks stay comparable.
+- **Self-tuning selects from a bounded grid, judged by the benchmark.**
+ Parameters: candidate-pool multiplier {3, 4, 5}, traversal depth {1, 2},
+ learned-weights {on, off}, expansion {on, off}. `tuneRecall` evaluates the
+ grid against a dataset deterministically, picks best MRR (stable
+ tie-break: fewer/smaller params first), persists
+ `Brain/search/tuning.json` with scores, dataset hash, and `evaluated_at`.
+ `search()` consults the tuned parameters only when self-tuning is enabled
+ (config `search.self_tuning` / `OSB_SELF_TUNING=1`); values are re-validated
+ against the grid bounds on read and fail soft to defaults. Replayable:
+ delete tuning.json and re-run, nothing else changes.
+- **Benchmark is both CI gate and objective function.** Core
+ `runRecallBenchmark(config, dataset, opts)` returns per-query hit/rank and
+ aggregate hit@k + MRR. The repo ships a fixture vault + dataset with
+ thresholds pinned in a bun test (deterministic local embedding provider).
+ The same runner serves `brain benchmark` for operator vaults and
+ `tuneRecall` as the scoring callback.
+- **Maintenance lane hosts the periodic passes.** `brain maintenance run`
+ gains `bridges` and `clusters` tasks after `reindex` (stale-first ordering
+ already handles fairness); both also run on demand via their verbs.
+
+## File changes
+
+New core: `src/core/brain/metrics.ts`, `src/core/brain/link-graph/
+bridge-discovery.ts`, `src/core/brain/link-graph/communities.ts`,
+`src/core/search/query-expansion.ts`, `src/core/search/benchmark.ts`,
+`src/core/search/tuning.ts`.
+Modified core: `src/core/search/schema.ts` (v7), `store.ts` (doc_aliases
+writers/readers, alias resolve pass, inbound-count + pair readers),
+`indexer.ts` (alias extraction + metric emission), `search.ts` (expand +
+tuned-parameter read path), `types.ts` (IndexStats.aliasResolved, config),
+`src/core/config.ts` / search config resolution (self_tuning flag),
+`src/core/brain/frontmatter-tiers.ts` (brain-cluster tier entry).
+New CLI verbs: `links.ts`, `clusters.ts`, `benchmark.ts`, `tune.ts` (each
+registered in the 5 standard places); `search.ts` verb gains `--expand`.
+MCP: 4 new tools (brain_links, brain_clusters, brain_benchmark, brain_tune)
+in `src/mcp/brain-tools.ts`; tool-count pins 73 -> 77.
+Tests: new suites per module + e2e `tests/e2e/link-recall-intelligence.
+integration.test.ts`; fixture vault under `tests/fixtures/recall-benchmark/`.
+Docs: CHANGELOG 0.45.0, README, docs/cli-reference.md, docs/how-it-works.md,
+new `docs/metrics.md` (dashboard data contract).
+
+## Risks and open questions
+
+- **Vec coverage**: vaults indexed with the null provider have no embeddings;
+ bridge discovery must report "no vec layer" cleanly (fail-soft, metric
+ records zero candidates) rather than proposing nothing silently.
+- **Label propagation stability**: synchronous sweeps can oscillate on
+ bipartite-ish subgraphs; the iteration cap plus lowest-label tie-break
+ guarantees termination and determinism - tests pin a known oscillation
+ case.
+- **Benchmark threshold brittleness**: thresholds pinned slightly below
+ measured values (one failing-direction margin) so legitimate ranking
+ improvements do not flap the gate.
+- **Cluster-note deletion**: removing stale derived notes must never touch
+ non-derived files - deletion is restricted to `Brain/clusters/` files
+ whose frontmatter carries the generated marker.
+- **Accept write-path**: writing `related:` into user frontmatter must
+ respect the tier guard (user-tier field, additive only) and link-type
+ constraints from the schema pack when one declares `related`.
diff --git a/docs/brainstorm/link-recall-intelligence/plan.md b/docs/brainstorm/link-recall-intelligence/plan.md
new file mode 100644
index 00000000..117113aa
--- /dev/null
+++ b/docs/brainstorm/link-recall-intelligence/plan.md
@@ -0,0 +1,214 @@
+# Link & Recall Intelligence Suite - implementation plan
+
+TDD discipline: every task starts with failing tests, ends with a green
+suite, formatter + linter run before each commit, one conventional commit
+per task.
+
+## Tasks
+
+### Task 1: Metrics sink
+- **Files**: `src/core/brain/metrics.ts` (new), `tests/core/brain/metrics.test.ts` (new)
+- **Scope**: `appendMetric(vault, {surface, runAt, payload})` writing one
+ `{schema: "o2b.metrics.v1", surface, run_at, payload}` line to
+ `Brain/metrics/<surface>.jsonl` via O_APPEND; surface name validated
+ (`[a-z][a-z0-9_]*`); `listMetrics(vault, {surface?, since?, limit?})`
+ fail-soft reader (missing dir/file -> empty, malformed lines skipped);
+ newest-first listing.
+- **Acceptance**: append + list round-trip; envelope shape pinned; malformed
+ line tolerated; surface validation rejects bad names.
+- **Depends on**: none
+
+### Task 2: doc_aliases schema v7 + store surface
+- **Files**: `src/core/search/schema.ts`, `src/core/search/store.ts`,
+ `src/core/search/types.ts`, `tests/core/search/schema.test.ts`,
+ `tests/core/search/store-aliases.test.ts` (new)
+- **Scope**: migration v7 (`doc_aliases(document_id REFERENCES documents ON
+ DELETE CASCADE, alias TEXT, UNIQUE(document_id, alias))` + alias index;
+ LATEST_SCHEMA_VERSION = 7); `replaceDocAliases(docId, aliases)`,
+ `aliasesForDocument(docId)`; alias pass inside `resolveLinkTargets`
+ (unresolved, slash-free targets join `doc_aliases` on the normalised
+ alias; first-wins by sorted document path) returning the resolved count.
+- **Acceptance**: v6 -> v7 migration test; alias-resolved link gets
+ `target_document_id`; collision resolves deterministically; exact-path
+ match still wins over alias match.
+- **Depends on**: none
+
+### Task 3: Indexer alias extraction + index metric
+- **Files**: `src/core/search/indexer.ts`, `src/core/search/types.ts`,
+ `tests/core/search/indexer-aliases.test.ts` (new)
+- **Scope**: extract frontmatter `aliases` (string array, NFC + lower-case,
+ non-string entries skipped) into `replaceDocAliases` during upsert;
+ `IndexStats.aliasResolved` populated from the resolve pass; one
+ `index` metric record per non-empty index run (files, aliasResolved,
+ relationViolations, tierDrift counts) - emission fail-soft.
+- **Acceptance**: `[[PA]]` wikilink resolves to note declaring
+ `aliases: [PA]` after indexing (links table has target_document_id);
+ stats and metric line carry the count; removing the alias un-resolves on
+ reindex.
+- **Depends on**: Task 1, Task 2
+
+### Task 4: Deterministic query expansion producer
+- **Files**: `src/core/search/query-expansion.ts` (new),
+ `src/core/search/search.ts`, `src/core/search/types.ts`,
+ `tests/core/search/query-expansion.test.ts` (new)
+- **Scope**: `expandQuery(query, {store, maxLexTerms?}) ->
+ StructuredRecallQueryDocument` - lex include = tokens + bounded synonym
+ expansion (`deriveExpansionTerms`); vec = raw query (+ one entity-context
+ line when `chunk_entities`/registry names match a token); hyde = one
+ deterministic template passage; `search(config, {expand: true})` produces
+ the document and routes through the existing structured path; no-op when
+ a structured document was already supplied.
+- **Acceptance**: same query -> identical expansion (determinism pin);
+ expansion improves a fixture recall case lex alone misses; `expand`
+ composes with the query cache key (different cache entry).
+- **Depends on**: none
+
+### Task 5: Recall benchmark core + CI regression gate
+- **Files**: `src/core/search/benchmark.ts` (new),
+ `tests/fixtures/recall-benchmark/` (new fixture vault + `dataset.json`),
+ `tests/core/search/recall-benchmark.test.ts` (new)
+- **Scope**: dataset schema `{queries: [{id, query, expected: [paths],
+ k?}]}` with validation; `runRecallBenchmark(config, dataset, {k?,
+ expand?, learnedWeights?})` -> per-query `{id, hit, rank,
+ reciprocalRank}` + aggregate `{hitAtK, mrr, total}`; fixture vault
+ (~15 notes incl. alias + bridge bait) indexed with the deterministic
+ local provider; thresholds asserted (hit@5, MRR pinned just below
+ measured).
+- **Acceptance**: benchmark deterministic across runs; thresholds hold;
+ artificially crippling ranking (weight override) fails the gate.
+- **Depends on**: Task 4 (expand option)
+
+### Task 6: Bridge discovery core
+- **Files**: `src/core/brain/link-graph/bridge-discovery.ts` (new),
+ `src/core/search/store.ts` (inbound-count reader, linked-pair check),
+ `tests/core/brain/bridge-discovery.test.ts` (new)
+- **Scope**: `discoverBridges(store, {maxProposals?, minSimilarity?,
+ maxCandidates?})` - inbound-count ascending candidate order; chunk
+ embeddings -> `vecSearch` KNN; L2-on-unit -> cosine; doc-level max;
+ exclude self/already-linked (either direction)/dismissed; dedupe
+ unordered pairs; threshold + cap. `writeBridgeProposals(vault,
+ proposals, {now})` regenerates `Brain/proposals/bridges.md` (generated
+ marker, similarity + inbound counts per pair);
+ `readDismissedBridges`/`dismissBridge` persist pair keys in
+ `Brain/proposals/bridges-dismissed.json`; `acceptBridge(vault, source,
+ target, {pack?})` appends `related: "[[target]]"` to source frontmatter
+ (idempotent, tier-guard-safe, link-constraint-checked when a pack
+ declares `related`); no-vec-layer -> empty result with reason.
+- **Acceptance**: embedding-near unlinked fixture pair proposed; linked
+ pair never proposed; dismiss suppresses across re-runs; accept writes
+ frontmatter once; no-vec vault fails soft.
+- **Depends on**: none (store readers local to task)
+
+### Task 7: links CLI verb + bridge metrics
+- **Files**: `src/cli/brain/verbs/links.ts` (new) + 5-place registration,
+ `tests/cli/brain-links.test.ts` (new)
+- **Scope**: `brain links discover [--max N] [--min-similarity X] [--json]`
+ (runs discovery, writes proposals doc, emits `bridge_discovery` metric),
+ `list`, `accept <source> <target>`, `dismiss <source> <target>`;
+ unindexed/no-vec vault exits cleanly with message.
+- **Acceptance**: CLI round-trip discover -> list -> accept/dismiss on a
+ fixture vault; metric line written; JSON shapes pinned.
+- **Depends on**: Task 1, Task 6
+
+### Task 8: Community detection core + cluster notes
+- **Files**: `src/core/brain/link-graph/communities.ts` (new),
+ `src/core/brain/frontmatter-tiers.ts` (brain-cluster entry),
+ `tests/core/brain/communities.test.ts` (new)
+- **Scope**: `detectCommunities(store, {minSize?, maxIterations?})` -
+ deterministic synchronous label propagation (sorted doc ids, lowest-label
+ tie-break, iteration cap) over undirected resolved links; members ranked
+ by internal degree; `materializeClusterNotes(vault, communities, {store,
+ now})` writes `Brain/clusters/<slug>.md` (slug from most-central member;
+ kind `brain-cluster`, generated marker, members + shared entities +
+ density digest), removes stale generated cluster notes only.
+- **Acceptance**: two known fixture communities detected deterministically;
+ oscillation case terminates; size < minSize ignored; re-run updates and
+ removes correctly; non-generated file in Brain/clusters/ never touched.
+- **Depends on**: none
+
+### Task 9: clusters CLI verb + maintenance lane tasks
+- **Files**: `src/cli/brain/verbs/clusters.ts` (new) + 5-place
+ registration, `src/cli/brain/verbs/maintenance.ts`,
+ `tests/cli/brain-clusters.test.ts` (new)
+- **Scope**: `brain clusters run [--min-size N] [--json]` (detect +
+ materialize + `communities` metric), `brain clusters list [--json]`;
+ maintenance verb gains `bridges` and `clusters` tasks after `reindex`.
+- **Acceptance**: CLI run materializes fixture clusters + metric; list
+ reads back; maintenance run executes new tasks under lease.
+- **Depends on**: Task 1, Task 8 (Task 7 for shared discovery helper)
+
+### Task 10: Self-tuning core
+- **Files**: `src/core/search/tuning.ts` (new), `src/core/search/search.ts`
+ + `types.ts` + config resolution (self_tuning flag, tuned-parameter read
+ path), `tests/core/search/tuning.test.ts` (new)
+- **Scope**: bounded grid (pool multiplier {3,4,5}, traversal depth {1,2},
+ learned-weights {on,off}, expansion {on,off}); `tuneRecall(config,
+ dataset, {grid?})` evaluates via `runRecallBenchmark`, best MRR with
+ stable tie-break, persists `Brain/search/tuning.json` (schema, chosen,
+ evaluated grid scores, dataset hash, evaluated_at);
+ `loadTunedParameters(vault)` re-validates against bounds, fail-soft to
+ defaults; `search()` consults tuned params only when
+ `search.self_tuning` config / `OSB_SELF_TUNING=1`; reset = delete file.
+- **Acceptance**: tuning deterministic (same dataset -> same choice);
+ out-of-bounds tuning.json ignored; opt-out leaves search byte-identical;
+ tuned pool multiplier observably changes candidate pool width.
+- **Depends on**: Task 5
+
+### Task 11: benchmark + tune CLI verbs
+- **Files**: `src/cli/brain/verbs/benchmark.ts`, `src/cli/brain/verbs/tune.ts`
+ (new) + 5-place registrations, `src/cli/brain/verbs/search.ts`
+ (`--expand` flag), `tests/cli/brain-benchmark.test.ts`,
+ `tests/cli/brain-tune.test.ts` (new)
+- **Scope**: `brain benchmark run --dataset <path> [--k N] [--expand]
+ [--json]` (emits `recall_benchmark` metric); `brain tune run --dataset
+ <path>`, `status`, `reset` (emits `self_tuning` metric on run);
+ `brain search --expand`.
+- **Acceptance**: CLI benchmark on fixture dataset prints/JSONs scores +
+ metric line; tune run -> status -> reset lifecycle; search --expand
+ returns results.
+- **Depends on**: Task 1, Task 5, Task 10
+
+### Task 12: MCP tools
+- **Files**: `src/mcp/brain-tools.ts`, `tests/mcp/mcp.test.ts`,
+ `tests/mcp/link-recall-tools.test.ts` (new)
+- **Scope**: `brain_links` (discover/list/accept/dismiss), `brain_clusters`
+ (run/list), `brain_benchmark` (run), `brain_tune` (run/status/reset);
+ previewBudget on each; descriptions <= 300 chars; param validation before
+ environment checks; tool count pins 73 -> 77.
+- **Acceptance**: tool registry pins updated; happy path + INVALID_PARAMS
+ per tool; vault containment via shared resolveNotePath where paths
+ appear.
+- **Depends on**: Tasks 6, 8, 10
+
+### Task 13: End-to-end integration test
+- **Files**: `tests/e2e/link-recall-intelligence.integration.test.ts` (new)
+- **Scope**: one vault through the suite: alias note + wikilink resolves at
+ materialization; bridge proposed between embedding-near unlinked notes,
+ accepted pair lands `related:` and disappears from next discovery;
+ communities materialize cluster notes; benchmark scores the vault;
+ tuning persists and search honors it under the flag; every surface left
+ one metric line in `Brain/metrics/`.
+- **Acceptance**: the composed flow passes with the deterministic local
+ embedding provider.
+- **Depends on**: Tasks 1-12
+
+### Task 14: Docs
+- **Files**: `CHANGELOG.md` ([0.45.0]), `README.md`,
+ `docs/cli-reference.md`, `docs/how-it-works.md`, `docs/metrics.md` (new -
+ dashboard data contract: envelope, surfaces, payload fields, evolution
+ rule)
+- **Acceptance**: docs match shipped behavior; metrics contract documents
+ every surface this release writes.
+- **Depends on**: Tasks 1-13
+
+## Implementation deviations
+
+- **Task 7 verb is `bridges`, not `links`**: `o2b brain links normalize`
+ already exists (Workspace Insight Suite, t_5f31b5f1) - clobbering or
+ overloading its contract for an unrelated feature would be a breaking
+ surprise. Bridge discovery ships as `o2b brain bridges
+ discover|list|accept|dismiss`; the MCP tool follows as `brain_bridges`.
+- **Task 5 acceptance reworded**: "expansion improves a case lex alone
+ misses" is pinned via the deterministic stopword case (implicit-AND FTS
+ drops a note when a stopword is absent from it) rather than a weight
+ override, which the public API does not expose.
diff --git a/docs/brainstorm/link-recall-intelligence/variants.md b/docs/brainstorm/link-recall-intelligence/variants.md
new file mode 100644
index 00000000..53280a3b
--- /dev/null
+++ b/docs/brainstorm/link-recall-intelligence/variants.md
@@ -0,0 +1,104 @@
+# Link & Recall Intelligence Suite - consultant variants (audit trail)
+
+Consultant: Claude CLI (`claude -p`), prompt in `cli-output/prompt.md`, raw
+output in `cli-output/claude.md`. Fallback (Codex) not needed - primary
+returned 3 parseable variants.
+
+## Variant 1: Index-native (everything in the search SQLite)
+
+- **Approach**: Push all six features into the search index via an additive
+ schema v7 migration. Bridges and communities become pending-proposal rows,
+ alias resolution extends `resolveLinkTargets`, query-expansion output and
+ self-tuning parameters are stored tables, and the uniform metrics layer is a
+ single `metrics(surface, run_at, payload)` table in the same SQLite. Graph
+ algorithms run as recursive CTEs / post-passes in `indexer.ts` directly over
+ the `links` table.
+- **Trade-offs**:
+ - Pro: one transactional store, no cross-store sync; graph queries fast and
+ natural; alias fix lands exactly where the gap is.
+ - Pro: self-tuning objective function queryable with SQL.
+ - Con: dashboard plugin must open OSB's SQLite and bind to its schema,
+ violating "readable without importing internals".
+ - Con: proposals-as-rows are less reviewable than markdown; weakens the
+ "reviewable artifact before mutating notes" constraint.
+ - Con: couples bridge/community generation to index lifecycle rather than
+ the maintenance lane.
+- **Complexity**: large
+- **Risk**: high
+
+## Variant 2: Vault-native (Brain/ artifacts + single JSONL metrics layer)
+
+- **Approach**: Express bridge proposals and synthesized cluster notes as
+ reviewable markdown artifacts under `Brain/`, persist self-tuning state
+ alongside `feedback.ts` as bounded replayable JSON, and make the uniform
+ metrics layer a single append-only `Brain/metrics/*.jsonl` log. Only the
+ alias fix and benchmark touch SQLite/tests; community detection and orphan
+ ranking read the links table into memory and emit markdown.
+- **Trade-offs**:
+ - Pro: dashboard reads plain JSONL with no OSB internals - cleanest
+ satisfaction of the cross-cutting contract; idiomatic with existing
+ per-event JSON feedback and Brain/log sidecars.
+ - Pro: proposals/derived notes inherently reviewable and participate in
+ recall as real notes; matches deterministic/replayable philosophy.
+ - Con: graph algorithms still must pull the graph out of SQLite each run.
+ - Con: self-tuning objective reads require scanning/parsing JSONL.
+ - Con: scattering compute risks inconsistent metric emission unless a
+ shared sink is enforced.
+- **Complexity**: medium
+- **Risk**: low
+
+## Variant 3: Hybrid layered (lane-orchestrated compute, Brain/ artifacts, dual-write metrics)
+
+- **Approach**: Heavy graph passes (bridge discovery, community detection,
+ orphan/backlink ranking) run as maintenance-lane passes over the SQLite
+ `links` table; their outputs are reviewable `Brain/` proposal and
+ derived-cluster artifacts. The alias fix lands in `resolveLinkTargets`;
+ expansion is a deterministic producer feeding the existing parser;
+ self-tuning mirrors the learned-weights fold. The metrics layer is
+ dual-write: a queryable `metrics` table (source of truth, v7 migration)
+ plus a deterministic `Brain/metrics/*.jsonl` projection as the dashboard's
+ stable contract. A shared `MetricsSink` interface and a common proposal
+ artifact contract bind all six features.
+- **Trade-offs**:
+ - Pro: each task uses its right substrate - SQL for graph math, markdown
+ for review, JSONL for the dashboard - single sink keeps emission uniform.
+ - Pro: fits conventions exactly (maintenance lane, reviewable proposals,
+ deterministic projection, additive v7).
+ - Pro: self-tuning queries the metrics table efficiently yet the dashboard
+ never imports internals.
+ - Con: dual-write adds a projection surface that must stay deterministic
+ and consistent (table -> JSONL replay).
+ - Con: most moving parts; largest of the three; shared abstractions add
+ up-front design cost.
+- **Complexity**: large
+- **Risk**: medium
+
+## Consultant recommendation: Variant 3
+
+> It is the only variant that simultaneously honors the two hardest
+> constraints - graph algorithms want SQLite's transactional link table,
+> while the dashboard needs a stable on-disk contract with no internal
+> coupling - by computing in SQL and projecting deterministically to
+> `Brain/metrics/` JSONL. It also slots cleanly into established conventions
+> (maintenance lane for heavy periodic passes, reviewable proposal artifacts,
+> bounded replayable folds, single additive v7 migration), where Variant 1
+> breaks the dashboard-decoupling and reviewability constraints and Variant 2
+> weakens graph performance and the self-tuning objective-function read path.
+
+## Orchestrator decision: Variant 3 with Variant 2's metrics substrate
+
+Accepted Variant 3's compute and artifact architecture (graph passes over the
+SQLite `links` table, reviewable `Brain/` proposal and cluster artifacts,
+alias fix in `resolveLinkTargets`, deterministic expansion producer,
+self-tuning as a bounded replayable fold) but overrode the dual-write metrics
+layer in favor of Variant 2's single-write `Brain/metrics/*.jsonl` through one
+shared sink module.
+
+Rationale: the metrics in this suite are run-level (one record per index run,
+bridge pass, benchmark run, tuning run), not per-query - tens of records per
+day, not thousands - so the SQL queryability the table buys is negligible
+while the projection surface it costs (table + replay + consistency tests)
+is real. OSB precedent already settles this pattern: continuity records
+(`o2b.continuity.v1`) are schema-versioned append-only JSONL with fail-soft
+readers, and the self-tuning objective function reads benchmark output
+directly from the in-process benchmark run, not from persisted metrics.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 0d8acfb0..df531d69 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -209,6 +209,18 @@ o2b brain maintenance run [--force] [--window H-H] [--tz ZONE] [--busy-m
The schema pack gains four additive ontology fields (`labels`, `link_constraints`, `attributes`, `frontmatter_tiers`) with audited mutations through `o2b brain schema apply`. Link constraints enforce at index materialization: a typed edge whose endpoint page types violate the declared pairs falls back to an untyped link, `o2b brain schema lint` lists each violation, and removing the constraint restores the edges on the next index run. Tier drift detection rides the same index pass - the snapshot keeps the expected value, so reindexes never absorb a hand-edit, and `brain_doctor` warns with the open count. Filter labelled recall with `o2b search <q> --property labels=<dim>/<value>`. Secrets protect against context leakage and vault sync exposure, not against root; every custody operation lands a no-values record in `Brain/log/secret-custody/`. A maintenance gate skip exits 0 so cron never alarms on a quiet hour.
+### Link and recall intelligence (since v0.45.0)
+
+```text
+o2b brain bridges discover [--max N] [--min-similarity X] | list | accept <source> <target> | dismiss <source> <target> - embedding-near link proposals over the vec index, reviewable artifact, accept writes one related: wikilink
+o2b brain clusters run [--min-size N] | list - graph-wide community detection; derived digests under Brain/clusters/, regenerated per run
+o2b brain benchmark run --dataset <path> [--k N] [--expand] - hit@k + MRR against the live hybrid recall; records the recall_benchmark metric
+o2b brain tune run --dataset <path> [--k N] | status | reset - bounded self-tuning grid judged by the benchmark; persisted to Brain/search/tuning.json
+o2b search <query> --expand deterministic lex/vec/hyde expansion of a bare query (stopword-stripped lex, entity-context vec line, template hyde passage)
+```
+
+Wikilinks to frontmatter `aliases:` resolve at index materialization (schema v7): exact paths always win, a real basename is never shadowed, collisions resolve first-wins by sorted path, and `o2b search status` counts the pass via `IndexStats.aliasResolved`. Bridge discovery and clusters also run as maintenance-lane tasks after `reindex`. Self-tuning only changes behavior under `search_self_tuning_enabled` (or `OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING=1`); an explicit `--expand`/`expand` always wins over the tuned default. Every surface appends one run-level record to `Brain/metrics/<surface>.jsonl` - the dashboard data contract documented in `docs/metrics.md`.
+
## Vault scope
Single exclusion policy for every vault walker.
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 9dd7c1e6..e399343e 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -979,6 +979,22 @@ Until now almost nothing about a write into the Brain was declared: any frontmat
**Heavy work waits its turn.** The maintenance lane runs dream and reindex behind three gates: a tz-aware local-time window, a busy gate over recent recall telemetry, and an expiring SQLite lease in its own database so holding it never contends with the search index writer lock. Force bypasses the soft gates but never the lease, tasks run stale-first, and every attempt - including each gate refusal - lands in a bounded journal, because a lane you cannot audit is a lane you cannot trust.
+## Link and recall intelligence (since v0.45.0)
+
+A second brain's value compounds through connections, but until now the graph only knew edges someone wrote by hand, and recall quality was an unmeasured feeling. The Link & Recall Intelligence Suite makes the graph self-organizing and the recall measurable - deterministically, with every output reviewable before it touches a note.
+
+**Aliases resolve where edges materialize.** Obsidian vaults lean on frontmatter `aliases:` for shorthand, but the search index resolved wikilink targets by exact path only - `[[PA]]` to a note titled "Project Alpha" stayed an unresolved string. The indexer now extracts every note's aliases into the index (schema v7) and a shadowing-safe post-pass materializes the target id: exact paths always win, a real document basename is never shadowed by someone else's alias, and collisions resolve deterministically. Traversal, backlinks, and link constraints all see the edge from then on.
+
+**Bridges surface the connections nobody wrote.** Traversal follows existing edges; unlinked-mentions catches textual name-drops. The third kind of latent structure - two notes that are embedding-near but never name each other - is found by an orphan-first pass over the vec index: weakly connected notes get scanned before well-wired hubs, chunk KNN similarity aggregates to document level, and pairs that already share an edge stay out. The output is a PROPOSAL artifact (`Brain/proposals/bridges.md`), regenerated per run; nothing touches a user note until someone runs `accept`, which writes exactly one `related:` wikilink, idempotently, under the schema pack's link constraints. Dismissals persist so re-runs stay quiet.
+
+**Communities become visible structure.** Deterministic label propagation (sorted sweeps, lowest-label tie-break, a hard iteration cap so bipartite stars cannot oscillate forever) discovers graph-wide communities; each one of four or more notes materializes a derived digest under `Brain/clusters/` - members by internal degree, shared entities, link density. No LLM prose: synthesis belongs to the reading agent, the digest is a projection. Stale generated notes are removed on the next run; a hand-written file in the same directory is never touched.
+
+**Recall quality gets a number.** A fixed query/expected-result dataset scores the live hybrid pipeline - hit@k and MRR per query and aggregate. The repository pins thresholds over a committed fixture vault with the deterministic local embedding provider, so a ranking regression fails CI instead of shipping silently; the same runner scores any operator vault on demand. And that number becomes an objective function: the self-tuner grid-evaluates a BOUNDED parameter space (keyword pool multiplier, traversal depth, learned weights, expansion) against it and persists the winner with every evaluated score and the dataset hash. Search applies the tuned point only under an explicit opt-in flag, re-validates it against the grid bounds on every read, and deleting the file restores defaults - the same replayable-fold philosophy as learned weights.
+
+**Expansion without a model.** A bare query can become a structured lex/vec/hyde document locally: stopword-stripped lex terms (the FTS lane is implicit AND, so one stopword absent from the target note kills the match), an entity-context line anchored to the vault's own registry, one template hyde passage for embedding retrieval. Opt-in per call, never silently active, so cached queries and benchmark runs stay comparable.
+
+**Every pass reports to one place.** Each feature appends one run-level record to `Brain/metrics/<surface>.jsonl` (`o2b.metrics.v1` envelope) - the stable contract a dashboard reads without importing internals, documented in `docs/metrics.md`.
+
## Safety properties
These are invariants of the system, not configuration to enable.
diff --git a/docs/metrics.md b/docs/metrics.md
new file mode 100644
index 00000000..07a1c79b
--- /dev/null
+++ b/docs/metrics.md
@@ -0,0 +1,80 @@
+# Metrics layer - the dashboard data contract
+
+Since v0.45.0 every run-level pass in Open Second Brain reports its
+numbers into one uniform, machine-readable layer under
+`Brain/metrics/`. This document is the stable on-disk contract for
+consumers - in particular the upcoming dashboard plugin - so they can
+read metrics without importing Open Second Brain internals.
+
+## Layout
+
+One append-only JSONL file per surface:
+
+```
+Brain/metrics/
+├── index.jsonl
+├── bridge_discovery.jsonl
+├── communities.jsonl
+├── recall_benchmark.jsonl
+└── self_tuning.jsonl
+```
+
+Surface names are lowercase snake_case (`[a-z][a-z0-9_]*`, max 64
+chars). A consumer reads only the files it renders; unknown files in
+the directory must be ignored.
+
+## Record envelope
+
+Every line is one JSON object:
+
+```json
+{
+ "schema": "o2b.metrics.v1",
+ "surface": "recall_benchmark",
+ "run_at": "2026-06-05T12:00:00Z",
+ "payload": { "hit_at_k": 1, "mrr": 0.958 }
+}
+```
+
+- `schema` - envelope version. Evolution rule mirrors continuity
+ records: additive optional payload fields do NOT bump the version;
+ renames, removals, or semantic changes bump to `o2b.metrics.v2`.
+- `surface` - matches the file name.
+- `run_at` - ISO-8601 UTC timestamp of the run the record describes.
+- `payload` - surface-specific object (fields below).
+
+Records are RUN-LEVEL: one line per index run, discovery pass,
+benchmark, or tuning run. Per-query retrieval events stay in recall
+telemetry (`docs/observability.md`). Writes are O_APPEND single
+lines, so concurrent writers interleave instead of racing; readers
+must skip torn or non-object lines (the bundled `listMetrics` reader
+does). Keep payloads small (well under the platform pipe-buffer
+size, ~4 KiB) - O_APPEND atomicity is only guaranteed for short
+writes, and a metric record is a summary, not a report.
+
+## Surfaces and payload fields (v0.45.0)
+
+| Surface | Writer | Payload fields |
+| --- | --- | --- |
+| `index` | every non-empty index run | `added`, `updated`, `deleted`, `alias_resolved`, `relation_violations`, `tier_drift` |
+| `bridge_discovery` | `o2b brain bridges discover`, MCP `brain_bridges`, maintenance lane | `proposals`, `scanned_candidates`, `vec_available`, `dismissed_total`, `min_similarity`, `max_proposals`, `lane` (lane runs) |
+| `communities` | `o2b brain clusters run`, MCP `brain_clusters`, maintenance lane | `communities`, `sizes`, `written`, `removed`, `min_size`, `lane` (lane runs) |
+| `recall_benchmark` | `o2b brain benchmark run`, MCP `brain_benchmark` | `total`, `k`, `expand`, `hit_at_k`, `mrr`, `misses` |
+| `self_tuning` | `o2b brain tune run`, MCP `brain_tune` | `chosen`, `evaluated`, `best_mrr`, `dataset_hash` |
+
+Payload fields marked "(lane runs)" appear only on maintenance-lane
+emissions. All fields are additive-optional from a consumer's point
+of view: render what is present, ignore what is unknown.
+
+## Reading
+
+- Newest records sit at the end of each file; the bundled reader
+ (`listMetrics(vault, {surface?, since?, limit?})` in
+ `src/core/brain/metrics.ts`) returns newest-first and merges
+ surfaces when none is specified.
+- External consumers (dashboards, scripts in other languages) should
+ read the files directly: split on newlines, `JSON.parse` each line,
+ skip lines that fail to parse or lack a string `surface`/`run_at`.
+- Metric emission is fail-soft everywhere: a metrics-layer problem
+ never fails the pass that produced the numbers, so gaps in a file
+ mean the run failed or predates the layer - not data corruption.
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index f8cba9a9..27b3c190 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": "0.44.0",
+ "version": "0.45.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index 8b950784..05cd5ae8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.44.0",
+ "version": "0.45.0",
"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 3ab85f7b..9db70b93 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.44.0"
+version: "0.45.0"
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 93e0d513..0b2cf0a8 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.44.0",
+ "version": "0.45.0",
"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/plugin.yaml b/plugins/hermes/plugin.yaml
index 3ab85f7b..9db70b93 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.44.0"
+version: "0.45.0"
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/pyproject.toml b/pyproject.toml
index f16a272b..c905d895 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 = "0.44.0"
+version = "0.45.0"
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/src/cli/brain.ts b/src/cli/brain.ts
index d6351eb4..fe8f3e43 100644
--- a/src/cli/brain.ts
+++ b/src/cli/brain.ts
@@ -38,6 +38,10 @@ import {
cmdBrainDeadEnd,
cmdBrainForesight,
cmdBrainLabel,
+ cmdBrainBridges,
+ cmdBrainClusters,
+ cmdBrainBenchmark,
+ cmdBrainTune,
cmdBrainAttr,
cmdBrainTiers,
cmdBrainSecret,
@@ -186,6 +190,14 @@ export async function handleBrainSubcommand(argv: ReadonlyArray<string>): Promis
return await cmdBrainForesight(rest);
case "label":
return await cmdBrainLabel(rest);
+ case "bridges":
+ return await cmdBrainBridges(rest);
+ case "clusters":
+ return await cmdBrainClusters(rest);
+ case "benchmark":
+ return await cmdBrainBenchmark(rest);
+ case "tune":
+ return await cmdBrainTune(rest);
case "attr":
return await cmdBrainAttr(rest);
case "tiers":
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index 0d5413fe..ae709be6 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -45,10 +45,14 @@ Brain verbs (observing memory):
dead-end Negative-knowledge registry: record and list failed approaches
foresight Forward projection: routines coming due, open commitments and questions
label Controlled-vocabulary classification: assign, remove, show note labels
+ bridges Embedding-near link proposals: discover, list, accept, dismiss
+ clusters Link-graph communities: detect and materialize cluster notes
+ benchmark Recall quality benchmark: hit@k and MRR over a fixed dataset
+ tune Self-tuning recall: grid-evaluate, persist, inspect, reset
attr Typed-page attribute fields: assign, remove, show (schema-pack declared)
tiers Frontmatter tier guard: check identity-field drift, restore or accept
secret Capability-gated secret custody: set, list, rm, run (use w/o exposure)
- maintenance Quiet-window, lease-guarded lane for heavy passes (dream, reindex)
+ maintenance Quiet-window, lease-guarded lane (dream, reindex, bridges, clusters)
audit Render a preference's full mutation audit trail
morning-brief Session-start summary: top prefs, open questions, recent notes
codec Compress/expand session prose with the deterministic codec (stdin/--in)
@@ -256,6 +260,35 @@ export const VERB_HELP: Record<string, string> = {
"rejected with the declared vocabulary - single-choice per dimension, and\n" +
"persist as a sorted labels frontmatter array plus a canonical label\n" +
"entity. Filter recall with: o2b search <q> --property labels=<dim>/<value>.\n",
+ bridges:
+ "usage: o2b brain bridges discover [--max N] [--min-similarity X] | list | accept <source> <target> | dismiss <source> <target> [--vault <path>] [--json]\n" +
+ "Bridge discovery over the vec index: propose links between embedding-near\n" +
+ "notes that share no existing edge, orphan-first. discover regenerates the\n" +
+ "reviewable Brain/proposals/bridges.md artifact and records one\n" +
+ "bridge_discovery metric; accept writes a single related: wikilink into the\n" +
+ "source note (schema-pack link constraints honored); dismiss silences a\n" +
+ "pair across future runs. Fail-soft without an index or embeddings.\n",
+ clusters:
+ "usage: o2b brain clusters run [--min-size N] | list [--vault <path>] [--json]\n" +
+ "Graph-wide community detection: deterministic label propagation over the\n" +
+ "index's resolved link graph. run materializes one derived note per\n" +
+ "community of size >= min-size (default 4) under Brain/clusters/ - members\n" +
+ "by internal degree, shared entities, density, no LLM prose - removes\n" +
+ "stale generated notes, and records one communities metric. list reads\n" +
+ "the generated notes back. Fail-soft without an index.\n",
+ benchmark:
+ "usage: o2b brain benchmark run --dataset <path> [--k N] [--expand] [--vault <path>] [--json]\n" +
+ "Score the vault's live hybrid recall against a fixed query/expected-result\n" +
+ "dataset (hit@k + MRR, per query and aggregate) and record one\n" +
+ "recall_benchmark metric in Brain/metrics/ so recall quality is chartable\n" +
+ "over time. Dataset shape: {queries: [{id, query, expected: [paths]}]}.\n",
+ tune:
+ "usage: o2b brain tune run --dataset <path> [--k N] | status | reset [--vault <path>] [--json]\n" +
+ "Opt-in self-tuning recall: run grid-evaluates bounded parameters (pool\n" +
+ "multiplier, traversal depth, learned weights, expansion) with the recall\n" +
+ "benchmark as the objective and persists the winner to\n" +
+ "Brain/search/tuning.json. Search honors it only when\n" +
+ "search_self_tuning_enabled is on; reset deletes the state.\n",
attr:
"usage: o2b brain attr <path> <field>=<value> | --remove <field> | --show [--vault <path>] [--json]\n" +
"Per-type attribute fields declared in the schema pack's attributes map.\n" +
@@ -286,7 +319,8 @@ export const VERB_HELP: Record<string, string> = {
"Quiet-window, lease-guarded lane for heavy passes. run gates on the\n" +
"local-time window (unset = always open), recent interactive query-rate\n" +
"from recall telemetry, and an expiring SQLite lease no second worker\n" +
- "can grab, then executes dream + reindex stale-first. --force bypasses\n" +
+ "can grab, then executes dream, reindex, bridges, and clusters\n" +
+ "stale-first. --force bypasses\n" +
"the soft gates but never the lease. Every attempt - including gate\n" +
"refusals - lands in a bounded journal; status renders lease + journal.\n",
audit:
diff --git a/src/cli/brain/verbs/benchmark.ts b/src/cli/brain/verbs/benchmark.ts
new file mode 100644
index 00000000..166ba908
--- /dev/null
+++ b/src/cli/brain/verbs/benchmark.ts
@@ -0,0 +1,112 @@
+/**
+ * `o2b brain benchmark run --dataset <path>` (t_e2215d49): score the
+ * vault's live hybrid recall against a fixed query/expected-result
+ * dataset - hit@k and MRR per query and aggregate - and record one
+ * `recall_benchmark` metric so the dashboard can chart recall quality
+ * over time.
+ *
+ * Exit codes: 0 on success, 1 on an operational failure, 2 on usage
+ * errors.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { parseRecallBenchmarkDataset, runRecallBenchmark } from "../../../core/search/benchmark.ts";
+import { appendMetric } from "../../../core/brain/metrics.ts";
+import { isoSecond } from "../../../core/brain/time.ts";
+import { resolveSearchConfig } from "../../../core/search/index.ts";
+import { SearchError } from "../../../core/search/types.ts";
+import { defaultConfigPath } from "../../../core/config.ts";
+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+
+const USAGE =
+ "usage: o2b brain benchmark run --dataset <path> [--k N] [--expand] [--vault <path>] [--json]";
+
+export async function cmdBrainBenchmark(argv: string[]): Promise<number> {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ dataset: { type: "string" },
+ k: { type: "string" },
+ expand: { type: "boolean" },
+ json: { type: "boolean" },
+ });
+ const asJson = flags["json"] === true;
+ const datasetPath = flags["dataset"] as string | undefined;
+ if (positional[0] !== "run" || positional.length !== 1 || datasetPath === undefined) {
+ process.stderr.write(`${USAGE}\n`);
+ return 2;
+ }
+ const k = flags["k"] !== undefined ? Number(flags["k"]) : undefined;
+ if (k !== undefined && (!Number.isInteger(k) || k < 1)) {
+ process.stderr.write("brain benchmark run: --k must be a positive integer\n");
+ return 2;
+ }
+
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ try {
+ let raw: unknown;
+ try {
+ raw = JSON.parse(readFileSync(datasetPath, "utf8"));
+ } catch (exc) {
+ process.stderr.write(
+ `brain benchmark run: cannot read dataset ${datasetPath}: ${(exc as Error).message}\n`,
+ );
+ return 2;
+ }
+ const dataset = parseRecallBenchmarkDataset(raw);
+ const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
+ const now = new Date();
+ const report = await runRecallBenchmark(searchConfig, dataset, {
+ ...(k !== undefined ? { k } : {}),
+ expand: flags["expand"] === true,
+ });
+ try {
+ appendMetric(vault, {
+ surface: "recall_benchmark",
+ runAt: isoSecond(now),
+ payload: {
+ total: report.total,
+ k: report.k,
+ expand: report.expand,
+ hit_at_k: report.hitAtK,
+ mrr: report.mrr,
+ misses: report.perQuery.filter((q) => !q.hit).map((q) => q.id),
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ if (asJson) {
+ okJson({
+ total: report.total,
+ k: report.k,
+ expand: report.expand,
+ hit_at_k: report.hitAtK,
+ mrr: report.mrr,
+ per_query: report.perQuery,
+ });
+ } else {
+ ok(
+ `benchmark: ${report.total} queries, hit@${report.k} ${report.hitAtK.toFixed(3)}, ` +
+ `MRR ${report.mrr.toFixed(3)}${report.expand ? " (expanded)" : ""}`,
+ );
+ for (const q of report.perQuery) {
+ ok(` ${q.hit ? "hit " : "MISS"} ${q.id} rank=${q.rank ?? "-"}`);
+ }
+ }
+ return 0;
+ } catch (exc) {
+ if (exc instanceof SearchError && exc.code === "INVALID_INPUT") {
+ process.stderr.write(`brain benchmark run: ${exc.message}\n`);
+ return 2;
+ }
+ const message = `benchmark failed: ${(exc as Error).message ?? exc}`;
+ if (asJson) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
diff --git a/src/cli/brain/verbs/bridges.ts b/src/cli/brain/verbs/bridges.ts
new file mode 100644
index 00000000..21c0bf84
--- /dev/null
+++ b/src/cli/brain/verbs/bridges.ts
@@ -0,0 +1,193 @@
+/**
+ * `o2b brain bridges discover|list|accept|dismiss` (t_ab540afe):
+ * bridge discovery over the vec index. `discover` regenerates the
+ * reviewable `Brain/proposals/bridges.md` artifact and records one
+ * `bridge_discovery` metric; `accept` writes a single `related:`
+ * wikilink into the source note; `dismiss` silences a pair across
+ * future runs. Fail-soft on a missing index or vec layer - the verb
+ * reports why and exits 0 so cron wrappers stay quiet.
+ *
+ * Exit codes: 0 on success/fail-soft skip, 1 on an operational
+ * failure, 2 on usage errors.
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+ acceptBridge,
+ bridgePairKey,
+ discoverBridges,
+ dismissBridge,
+ readDismissedBridges,
+ writeBridgeProposals,
+ BRIDGE_DEFAULT_MAX_PROPOSALS,
+ BRIDGE_DEFAULT_MIN_SIMILARITY,
+} from "../../../core/brain/link-graph/bridge-discovery.ts";
+import { appendMetric } from "../../../core/brain/metrics.ts";
+import { loadSchemaPack } from "../../../core/brain/schema-pack.ts";
+import { isoSecond } from "../../../core/brain/time.ts";
+import { resolveSearchConfig } from "../../../core/search/index.ts";
+import { Store } from "../../../core/search/store.ts";
+import { SearchError } from "../../../core/search/types.ts";
+import { defaultConfigPath } from "../../../core/config.ts";
+import { parseFrontmatter } from "../../../core/vault.ts";
+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+
+const USAGE =
+ "usage: o2b brain bridges discover [--max N] [--min-similarity X] | list | " +
+ "accept <source> <target> | dismiss <source> <target> [--vault <path>] [--json]";
+
+export async function cmdBrainBridges(argv: string[]): Promise<number> {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ max: { type: "string" },
+ "min-similarity": { type: "string" },
+ json: { type: "boolean" },
+ });
+ const asJson = flags["json"] === true;
+ const action = positional[0];
+ if (
+ action === undefined ||
+ !["discover", "list", "accept", "dismiss"].includes(action) ||
+ ((action === "accept" || action === "dismiss") && positional.length !== 3) ||
+ ((action === "discover" || action === "list") && positional.length !== 1)
+ ) {
+ process.stderr.write(`${USAGE}\n`);
+ return 2;
+ }
+
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ try {
+ if (action === "accept") {
+ const pack = loadSchemaPack(vault);
+ const result = acceptBridge(vault, positional[1]!, positional[2]!, { pack });
+ if (asJson) okJson({ ...result, source: positional[1], target: positional[2] });
+ else if (result.changed) ok(`bridge accepted: related now ${result.related.join(", ")}`);
+ else ok("bridge already accepted (related target present)");
+ return 0;
+ }
+
+ if (action === "dismiss") {
+ const added = dismissBridge(vault, positional[1]!, positional[2]!);
+ if (asJson) {
+ okJson({ dismissed: bridgePairKey(positional[1]!, positional[2]!), added });
+ } else ok(added ? "bridge dismissed" : "bridge was already dismissed");
+ return 0;
+ }
+
+ if (action === "list") {
+ const path = join(vault, "Brain", "proposals", "bridges.md");
+ if (!existsSync(path)) {
+ if (asJson) okJson({ exists: false, proposals: 0 });
+ else ok("no proposals artifact yet - run: o2b brain bridges discover");
+ return 0;
+ }
+ const [meta, body] = parseFrontmatter(path);
+ if (asJson) {
+ okJson({
+ exists: true,
+ path: "Brain/proposals/bridges.md",
+ generated_at: meta["generated_at"] ?? null,
+ proposals: Number(meta["proposals"] ?? 0),
+ });
+ } else ok(body);
+ return 0;
+ }
+
+ // discover
+ const max = parsePositiveInt(flags["max"] as string | undefined);
+ const minSimilarity = parseFraction(flags["min-similarity"] as string | undefined);
+ if (max === false || minSimilarity === false) {
+ process.stderr.write(
+ "brain bridges discover: --max must be a positive integer, --min-similarity in (0, 1]\n",
+ );
+ return 2;
+ }
+
+ const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
+ let store: Store;
+ try {
+ store = await Store.open(searchConfig, { mode: "read" });
+ } catch (exc) {
+ if (
+ exc instanceof SearchError &&
+ (exc.code === "INDEX_MISSING" || exc.code === "SCHEMA_MISMATCH")
+ ) {
+ if (asJson) okJson({ vec_available: false, proposals: [], reason: "index not built" });
+ else ok("bridges discover: search index not initialised - run: o2b search index");
+ return 0;
+ }
+ throw exc;
+ }
+
+ const now = new Date();
+ try {
+ const dismissed = readDismissedBridges(vault);
+ const report = discoverBridges(store, {
+ ...(max !== undefined ? { maxProposals: max } : {}),
+ ...(minSimilarity !== undefined ? { minSimilarity } : {}),
+ dismissed,
+ });
+ const path = writeBridgeProposals(vault, report, { now });
+ try {
+ appendMetric(vault, {
+ surface: "bridge_discovery",
+ runAt: isoSecond(now),
+ payload: {
+ proposals: report.proposals.length,
+ scanned_candidates: report.scannedCandidates,
+ vec_available: report.vecAvailable,
+ dismissed_total: dismissed.size,
+ min_similarity: minSimilarity ?? BRIDGE_DEFAULT_MIN_SIMILARITY,
+ max_proposals: max ?? BRIDGE_DEFAULT_MAX_PROPOSALS,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ if (asJson) {
+ okJson({
+ vec_available: report.vecAvailable,
+ ...(report.reason !== undefined ? { reason: report.reason } : {}),
+ scanned_candidates: report.scannedCandidates,
+ proposals: report.proposals,
+ artifact: "Brain/proposals/bridges.md",
+ });
+ } else if (!report.vecAvailable) {
+ ok(`bridges discover: ${report.reason ?? "vec layer unavailable"}`);
+ } else if (report.proposals.length === 0) {
+ ok("bridges discover: no new bridge proposals");
+ } else {
+ ok(`bridges discover: ${report.proposals.length} proposal(s) -> ${path}`);
+ for (const p of report.proposals) {
+ ok(` ${p.source} <-> ${p.target} sim=${p.similarity.toFixed(3)}`);
+ }
+ }
+ return 0;
+ } finally {
+ await store.close();
+ }
+ } catch (exc) {
+ const message = `bridges ${action} failed: ${(exc as Error).message ?? exc}`;
+ if (asJson) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
+
+function parsePositiveInt(raw: string | undefined): number | undefined | false {
+ if (raw === undefined) return undefined;
+ const n = Number(raw);
+ return Number.isInteger(n) && n > 0 ? n : false;
+}
+
+function parseFraction(raw: string | undefined): number | undefined | false {
+ if (raw === undefined) return undefined;
+ const n = Number(raw);
+ return Number.isFinite(n) && n > 0 && n <= 1 ? n : false;
+}
diff --git a/src/cli/brain/verbs/clusters.ts b/src/cli/brain/verbs/clusters.ts
new file mode 100644
index 00000000..14a67a29
--- /dev/null
+++ b/src/cli/brain/verbs/clusters.ts
@@ -0,0 +1,162 @@
+/**
+ * `o2b brain clusters run|list` (t_4ba927ec): graph-wide community
+ * detection over the search index's link graph. `run` detects
+ * communities (deterministic label propagation), materializes one
+ * derived note per community under `Brain/clusters/`, removes stale
+ * generated notes, and records one `communities` metric. `list`
+ * reads the generated notes back. Fail-soft on a missing index.
+ *
+ * Exit codes: 0 on success/fail-soft skip, 1 on an operational
+ * failure, 2 on usage errors.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+ detectCommunities,
+ materializeClusterNotes,
+ COMMUNITY_DEFAULT_MIN_SIZE,
+} from "../../../core/brain/link-graph/communities.ts";
+import { appendMetric } from "../../../core/brain/metrics.ts";
+import { isoSecond } from "../../../core/brain/time.ts";
+import { resolveSearchConfig } from "../../../core/search/index.ts";
+import { Store } from "../../../core/search/store.ts";
+import { SearchError } from "../../../core/search/types.ts";
+import { defaultConfigPath } from "../../../core/config.ts";
+import { parseFrontmatter } from "../../../core/vault.ts";
+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+
+const USAGE = "usage: o2b brain clusters run [--min-size N] | list [--vault <path>] [--json]";
+
+export async function cmdBrainClusters(argv: string[]): Promise<number> {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ "min-size": { type: "string" },
+ json: { type: "boolean" },
+ });
+ const asJson = flags["json"] === true;
+ const action = positional[0];
+ if ((action !== "run" && action !== "list") || positional.length !== 1) {
+ process.stderr.write(`${USAGE}\n`);
+ return 2;
+ }
+
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ try {
+ if (action === "list") {
+ const dir = join(vault, "Brain", "clusters");
+ if (!existsSync(dir)) {
+ if (asJson) okJson({ clusters: [] });
+ else ok("no cluster notes yet - run: o2b brain clusters run");
+ return 0;
+ }
+ const clusters = readdirSync(dir)
+ .filter((f) => f.endsWith(".md"))
+ .toSorted()
+ .map((f) => {
+ const [meta] = parseFrontmatter(join(dir, f));
+ return meta["kind"] === "brain-cluster"
+ ? {
+ path: `Brain/clusters/${f}`,
+ cluster: String(meta["cluster"] ?? ""),
+ size: Number(meta["size"] ?? 0),
+ density: Number(meta["density"] ?? 0),
+ generated_at: String(meta["generated_at"] ?? ""),
+ }
+ : null;
+ })
+ .filter((c) => c !== null);
+ if (asJson) okJson({ clusters });
+ else if (clusters.length === 0) ok("no generated cluster notes");
+ else {
+ for (const c of clusters) {
+ ok(`${c.cluster}: ${c.size} notes, density ${c.density} (${c.path})`);
+ }
+ }
+ return 0;
+ }
+
+ // run
+ const minSize = parsePositiveInt(flags["min-size"] as string | undefined);
+ if (minSize === false) {
+ process.stderr.write("brain clusters run: --min-size must be a positive integer\n");
+ return 2;
+ }
+
+ const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
+ let store: Store;
+ try {
+ store = await Store.open(searchConfig, { mode: "read" });
+ } catch (exc) {
+ if (
+ exc instanceof SearchError &&
+ (exc.code === "INDEX_MISSING" || exc.code === "SCHEMA_MISMATCH")
+ ) {
+ if (asJson) okJson({ communities: 0, reason: "index not built" });
+ else ok("clusters run: search index not initialised - run: o2b search index");
+ return 0;
+ }
+ throw exc;
+ }
+
+ const now = new Date();
+ try {
+ const communities = detectCommunities(store, minSize !== undefined ? { minSize } : {});
+ const result = materializeClusterNotes(vault, communities, { store, now });
+ try {
+ appendMetric(vault, {
+ surface: "communities",
+ runAt: isoSecond(now),
+ payload: {
+ communities: communities.length,
+ sizes: communities.map((c) => c.size),
+ written: result.written.length,
+ removed: result.removed.length,
+ min_size: minSize ?? COMMUNITY_DEFAULT_MIN_SIZE,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ if (asJson) {
+ okJson({
+ communities: communities.map((c) => ({
+ id: c.id,
+ size: c.size,
+ density: c.density,
+ members: c.members.map((m) => m.path),
+ })),
+ written: result.written,
+ removed: result.removed,
+ });
+ } else if (communities.length === 0) {
+ ok("clusters run: no communities at the current threshold");
+ } else {
+ ok(`clusters run: ${communities.length} communit${communities.length === 1 ? "y" : "ies"}`);
+ for (const c of communities) {
+ ok(` ${c.id}: ${c.size} notes, density ${c.density.toFixed(2)}`);
+ }
+ if (result.removed.length > 0) ok(` removed stale: ${result.removed.join(", ")}`);
+ }
+ return 0;
+ } finally {
+ await store.close();
+ }
+ } catch (exc) {
+ const message = `clusters ${action} failed: ${(exc as Error).message ?? exc}`;
+ if (asJson) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
+
+function parsePositiveInt(raw: string | undefined): number | undefined | false {
+ if (raw === undefined) return undefined;
+ const n = Number(raw);
+ return Number.isInteger(n) && n > 0 ? n : false;
+}
diff --git a/src/cli/brain/verbs/index.ts b/src/cli/brain/verbs/index.ts
index eada1f97..ba43f619 100644
--- a/src/cli/brain/verbs/index.ts
+++ b/src/cli/brain/verbs/index.ts
@@ -25,6 +25,10 @@ export { cmdBrainFacts } from "./facts.ts";
export { cmdBrainDeadEnd } from "./dead-end.ts";
export { cmdBrainForesight } from "./foresight.ts";
export { cmdBrainLabel } from "./label.ts";
+export { cmdBrainBridges } from "./bridges.ts";
+export { cmdBrainClusters } from "./clusters.ts";
+export { cmdBrainBenchmark } from "./benchmark.ts";
+export { cmdBrainTune } from "./tune.ts";
export { cmdBrainAttr } from "./attr.ts";
export { cmdBrainTiers } from "./tiers.ts";
export { cmdBrainSecret } from "./secret.ts";
diff --git a/src/cli/brain/verbs/maintenance.ts b/src/cli/brain/verbs/maintenance.ts
index 82f285d9..c008089a 100644
--- a/src/cli/brain/verbs/maintenance.ts
+++ b/src/cli/brain/verbs/maintenance.ts
@@ -2,8 +2,9 @@
* `o2b brain maintenance <run|status>` (t_166d1226): the quiet-window
* lane for heavy passes. `run` gates on the local-time window
* (--window H-H, unset = always open), recent interactive query-rate,
- * and the expiring SQLite lease, then executes dream + reindex
- * stale-first; --force bypasses the soft gates but never the lease.
+ * and the expiring SQLite lease, then executes dream, reindex,
+ * bridges, and clusters stale-first; --force bypasses the soft gates
+ * but never the lease.
* `status` renders the lease holder and recent journal. Designed as
* the cron entry point: a dead dashboard hour surfaces as
* skipped:window in the journal instead of a contended vault.
@@ -14,6 +15,18 @@
*/
import { dream } from "../../../core/brain/dream.ts";
+import {
+ discoverBridges,
+ readDismissedBridges,
+ writeBridgeProposals,
+} from "../../../core/brain/link-graph/bridge-discovery.ts";
+import {
+ detectCommunities,
+ materializeClusterNotes,
+} from "../../../core/brain/link-graph/communities.ts";
+import { appendMetric } from "../../../core/brain/metrics.ts";
+import { isoSecond } from "../../../core/brain/time.ts";
+import { Store } from "../../../core/search/store.ts";
import { currentLease, MAINTENANCE_LEASE_NAME } from "../../../core/brain/maintenance/lease.ts";
import {
MAINTENANCE_BUSY_MINUTES,
@@ -120,6 +133,64 @@ export async function cmdBrainMaintenance(argv: string[]): Promise<number> {
await indexVault(searchConfig);
},
},
+ // Link-recall-intelligence passes ride the same lease, after
+ // reindex so they see fresh edges. Both are fail-soft inside:
+ // a vault without embeddings simply proposes nothing.
+ {
+ name: "bridges",
+ run: async () => {
+ const store = await Store.open(searchConfig, { mode: "read" });
+ try {
+ const report = discoverBridges(store, {
+ dismissed: readDismissedBridges(vault),
+ });
+ writeBridgeProposals(vault, report, { now });
+ try {
+ appendMetric(vault, {
+ surface: "bridge_discovery",
+ runAt: isoSecond(now),
+ payload: {
+ proposals: report.proposals.length,
+ scanned_candidates: report.scannedCandidates,
+ vec_available: report.vecAvailable,
+ lane: true,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ } finally {
+ await store.close();
+ }
+ },
+ },
+ {
+ name: "clusters",
+ run: async () => {
+ const store = await Store.open(searchConfig, { mode: "read" });
+ try {
+ const communities = detectCommunities(store, {});
+ const materialized = materializeClusterNotes(vault, communities, { store, now });
+ try {
+ appendMetric(vault, {
+ surface: "communities",
+ runAt: isoSecond(now),
+ payload: {
+ communities: communities.length,
+ sizes: communities.map((c) => c.size),
+ written: materialized.written.length,
+ removed: materialized.removed.length,
+ lane: true,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ } finally {
+ await store.close();
+ }
+ },
+ },
],
});
diff --git a/src/cli/brain/verbs/tune.ts b/src/cli/brain/verbs/tune.ts
new file mode 100644
index 00000000..37535704
--- /dev/null
+++ b/src/cli/brain/verbs/tune.ts
@@ -0,0 +1,144 @@
+/**
+ * `o2b brain tune run|status|reset` (t_ae973491): opt-in self-tuning
+ * recall. `run` grid-evaluates the bounded parameter space against a
+ * benchmark dataset, persists the winner to Brain/search/tuning.json,
+ * and records one `self_tuning` metric; `status` renders the persisted
+ * choice; `reset` deletes it. Search only honors the tuned state when
+ * `search_self_tuning_enabled` is on.
+ *
+ * Exit codes: 0 on success, 1 on an operational failure, 2 on usage
+ * errors.
+ */
+
+import { readFileSync } from "node:fs";
+
+import { parseRecallBenchmarkDataset } from "../../../core/search/benchmark.ts";
+import { loadTunedParameters, resetTuning, tuneRecall } from "../../../core/search/tuning.ts";
+import { appendMetric } from "../../../core/brain/metrics.ts";
+import { isoSecond } from "../../../core/brain/time.ts";
+import { resolveSearchConfig } from "../../../core/search/index.ts";
+import { SearchError } from "../../../core/search/types.ts";
+import { defaultConfigPath } from "../../../core/config.ts";
+import { fail, ok, okJson, parse, resolveBrainVault } from "../helpers.ts";
+
+const USAGE =
+ "usage: o2b brain tune run --dataset <path> [--k N] | status | reset [--vault <path>] [--json]";
+
+export async function cmdBrainTune(argv: string[]): Promise<number> {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ dataset: { type: "string" },
+ k: { type: "string" },
+ json: { type: "boolean" },
+ });
+ const asJson = flags["json"] === true;
+ const action = positional[0];
+ if (
+ (action !== "run" && action !== "status" && action !== "reset") ||
+ positional.length !== 1 ||
+ (action === "run" && flags["dataset"] === undefined)
+ ) {
+ process.stderr.write(`${USAGE}\n`);
+ return 2;
+ }
+
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ try {
+ if (action === "status") {
+ const tuned = loadTunedParameters(vault);
+ const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
+ if (asJson) {
+ okJson({ enabled: searchConfig.recall.selfTuningEnabled, tuned });
+ } else if (tuned === null) {
+ ok("tune: no valid tuned parameters persisted - run: o2b brain tune run --dataset <path>");
+ } else {
+ ok(
+ `tune: pool x${tuned.poolMultiplier}, depth ${tuned.traversalDepth}, ` +
+ `learned-weights ${tuned.learnedWeights ? "on" : "off"}, ` +
+ `expansion ${tuned.expansion ? "on" : "off"} ` +
+ `(${searchConfig.recall.selfTuningEnabled ? "ACTIVE" : "inactive - enable search_self_tuning_enabled"})`,
+ );
+ }
+ return 0;
+ }
+
+ if (action === "reset") {
+ const removed = resetTuning(vault);
+ if (asJson) okJson({ removed });
+ else ok(removed ? "tune: persisted state removed" : "tune: nothing to remove");
+ return 0;
+ }
+
+ // run
+ const k = flags["k"] !== undefined ? Number(flags["k"]) : undefined;
+ if (k !== undefined && (!Number.isInteger(k) || k < 1)) {
+ process.stderr.write("brain tune run: --k must be a positive integer\n");
+ return 2;
+ }
+ const datasetPath = flags["dataset"] as string;
+ let raw: unknown;
+ try {
+ raw = JSON.parse(readFileSync(datasetPath, "utf8"));
+ } catch (exc) {
+ process.stderr.write(
+ `brain tune run: cannot read dataset ${datasetPath}: ${(exc as Error).message}\n`,
+ );
+ return 2;
+ }
+ const dataset = parseRecallBenchmarkDataset(raw);
+ const searchConfig = resolveSearchConfig({ vault, configPath: config ?? undefined });
+ const now = new Date();
+ const report = await tuneRecall(searchConfig, dataset, {
+ ...(k !== undefined ? { k } : {}),
+ now,
+ });
+ try {
+ appendMetric(vault, {
+ surface: "self_tuning",
+ runAt: isoSecond(now),
+ payload: {
+ chosen: report.chosen,
+ evaluated: report.evaluated.length,
+ best_mrr: Math.max(...report.evaluated.map((e) => e.mrr)),
+ dataset_hash: report.datasetHash,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ if (asJson) {
+ okJson({
+ chosen: report.chosen,
+ evaluated: report.evaluated.map((e) => ({
+ params: e.params,
+ mrr: e.mrr,
+ hit_at_k: e.hitAtK,
+ })),
+ });
+ } else {
+ ok(
+ `tune: chose pool x${report.chosen.poolMultiplier}, depth ${report.chosen.traversalDepth}, ` +
+ `learned-weights ${report.chosen.learnedWeights ? "on" : "off"}, ` +
+ `expansion ${report.chosen.expansion ? "on" : "off"} ` +
+ `over ${report.evaluated.length} grid points`,
+ );
+ ok(
+ "activate with: search_self_tuning_enabled: true (config) or OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING=1",
+ );
+ }
+ return 0;
+ } catch (exc) {
+ if (exc instanceof SearchError && exc.code === "INVALID_INPUT") {
+ process.stderr.write(`brain tune ${action}: ${exc.message}\n`);
+ return 2;
+ }
+ const message = `tune ${action} failed: ${(exc as Error).message ?? exc}`;
+ if (asJson) {
+ okJson({ ok: false, message });
+ return 1;
+ }
+ return fail(message);
+ }
+}
diff --git a/src/cli/command-manifest.ts b/src/cli/command-manifest.ts
index c2473f86..4ce08fed 100644
--- a/src/cli/command-manifest.ts
+++ b/src/cli/command-manifest.ts
@@ -165,6 +165,10 @@ export const CLI_COMMAND_MANIFEST: CliRootManifest = Object.freeze({
command("project", "Link project directories to their owning vault"),
command("source", "Manage read-only recall sources of the active vault"),
command("links", "Normalize wikilink path format across Brain notes"),
+ command("bridges", "Propose, accept, or dismiss embedding-near bridge links"),
+ command("clusters", "Detect link-graph communities and materialize cluster notes"),
+ command("benchmark", "Score recall quality against a fixed query dataset"),
+ command("tune", "Grid-evaluate and persist self-tuning recall parameters"),
command("profile", "Materialize the compact Brain/profile.md digest"),
command("sgrep", "Grep-shaped semantic Brain search (path:line: output)"),
command("continuity", "Export continuity records as ATOF/ATIF trajectories"),
diff --git a/src/cli/search.ts b/src/cli/search.ts
index 7191fef3..d2da10a8 100644
--- a/src/cli/search.ts
+++ b/src/cli/search.ts
@@ -413,6 +413,7 @@ async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {
property: { type: "string-array" },
visibility: { type: "string-array" },
"query-doc": { type: "string" },
+ expand: { type: "boolean" },
"evidence-pack": { type: "boolean" },
"include-superseded": { type: "boolean" },
since: { type: "string" },
@@ -475,6 +476,7 @@ async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {
...(properties !== undefined ? { properties } : {}),
...(visibility !== undefined && visibility.length > 0 ? { visibility } : {}),
...(structuredQuery !== undefined ? { structuredQuery } : {}),
+ ...(flags["expand"] === true ? { expand: true } : {}),
...(flags["evidence-pack"] === true ? { evidencePack: true } : {}),
...(flags["include-superseded"] === true ? { includeSuperseded: true } : {}),
...(typeof flags["since"] === "string" ? { since: flags["since"] as string } : {}),
diff --git a/src/core/brain/frontmatter-tiers.ts b/src/core/brain/frontmatter-tiers.ts
index 5f1eaf19..5f92f8a8 100644
--- a/src/core/brain/frontmatter-tiers.ts
+++ b/src/core/brain/frontmatter-tiers.ts
@@ -89,6 +89,17 @@ export const DEFAULT_TIER_MAP: Readonly<Record<string, Readonly<Record<string, F
created_at: "system",
retired_at: "system",
}),
+ // Derived cluster notes (link-recall-intelligence, t_4ba927ec):
+ // fully framework-owned and regenerated every run, so every field
+ // is system except the identity pair.
+ "brain-cluster": Object.freeze<Record<string, FrontmatterTier>>({
+ kind: "identity",
+ cluster: "identity",
+ generated_at: "system",
+ size: "system",
+ density: "system",
+ members: "system",
+ }),
"brain-signal": Object.freeze<Record<string, FrontmatterTier>>({
kind: "identity",
id: "identity",
diff --git a/src/core/brain/link-graph/bridge-discovery.ts b/src/core/brain/link-graph/bridge-discovery.ts
new file mode 100644
index 00000000..b4c15418
--- /dev/null
+++ b/src/core/brain/link-graph/bridge-discovery.ts
@@ -0,0 +1,341 @@
+/**
+ * Bridge discovery (link-recall-intelligence, t_ab540afe).
+ *
+ * Traversal only follows edges someone wrote; unlinked-mentions only
+ * catches textual name-drops. This pass finds the third kind of
+ * latent structure: two notes that are embedding-near but share no
+ * edge and never name each other. Orphan-first - candidates are
+ * scanned in ascending inbound-link order, so weakly connected notes
+ * get bridged before well-wired hubs.
+ *
+ * Strictly read-only against note bodies. Output is a REVIEWABLE
+ * artifact (`Brain/proposals/bridges.md`, regenerated per run);
+ * `acceptBridge` is the only path that mutates a user note, one pair
+ * at a time, on operator/agent initiative. Dismissals persist in
+ * `Brain/proposals/bridges-dismissed.json` so re-runs stay quiet.
+ *
+ * Similarity: chunk embeddings are unit-normalised, so the sqlite-vec
+ * L2 distance converts exactly (cos = 1 - d^2 / 2). Fail-soft: a
+ * vault without embeddings reports `vecAvailable: false` and proposes
+ * nothing.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import type { Store } from "../../search/store.ts";
+import { linkConstraintAllows } from "../../search/link-constraints.ts";
+import { normalizeRelationTarget } from "../../graph/frontmatter-relations.ts";
+import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import { isoSecond } from "../time.ts";
+import {
+ formatFrontmatter,
+ listVaultPages,
+ parseFrontmatter,
+ writeFrontmatterAtomic,
+} from "../../vault.ts";
+import { resolveNotePath } from "../note-path.ts";
+import type { SchemaPack } from "../schema-pack.ts";
+
+export const BRIDGE_DEFAULT_MIN_SIMILARITY = 0.8;
+export const BRIDGE_DEFAULT_MAX_PROPOSALS = 10;
+export const BRIDGE_DEFAULT_MAX_CANDIDATES = 25;
+/** Chunk embeddings sampled per candidate document. */
+const BRIDGE_CHUNKS_PER_DOC = 3;
+/** KNN depth per sampled chunk. */
+const BRIDGE_KNN_K = 10;
+
+export interface BridgeProposal {
+ readonly source: string;
+ readonly target: string;
+ /** Cosine similarity of the closest chunk pair, [0, 1]. */
+ readonly similarity: number;
+ readonly sourceInbound: number;
+ readonly targetInbound: number;
+}
+
+export interface BridgeDiscoveryReport {
+ readonly proposals: ReadonlyArray<BridgeProposal>;
+ readonly scannedCandidates: number;
+ readonly vecAvailable: boolean;
+ readonly reason?: string;
+}
+
+export interface DiscoverBridgesOptions {
+ readonly minSimilarity?: number;
+ readonly maxProposals?: number;
+ readonly maxCandidates?: number;
+ /** Pair keys (see {@link bridgePairKey}) to suppress. */
+ readonly dismissed?: ReadonlySet<string>;
+}
+
+/** Canonical unordered pair key. */
+export function bridgePairKey(a: string, b: string): string {
+ return [a, b].toSorted().join("::");
+}
+
+/**
+ * Propose bridges over the open store. Deterministic for a fixed
+ * index state; performs no writes.
+ */
+export function discoverBridges(
+ store: Store,
+ opts: DiscoverBridgesOptions = {},
+): BridgeDiscoveryReport {
+ const minSimilarity = opts.minSimilarity ?? BRIDGE_DEFAULT_MIN_SIMILARITY;
+ const maxProposals = Math.max(1, opts.maxProposals ?? BRIDGE_DEFAULT_MAX_PROPOSALS);
+ const maxCandidates = Math.max(1, opts.maxCandidates ?? BRIDGE_DEFAULT_MAX_CANDIDATES);
+ const dismissed = opts.dismissed ?? new Set<string>();
+
+ if (!store.vecLoaded() || store.countEmbeddings() === 0) {
+ return Object.freeze({
+ proposals: Object.freeze([]),
+ scannedCandidates: 0,
+ vecAvailable: false,
+ reason: "no embedding layer: index the vault with embeddings enabled first",
+ });
+ }
+
+ const documents = store.listDocuments();
+ const pathById = new Map<number, string>();
+ for (const [path, summary] of documents) pathById.set(summary.id, path);
+
+ // Existing doc-level edges (either direction) and inbound counts.
+ const linkedPairs = new Set<string>();
+ const inbound = new Map<number, number>();
+ for (const { source, target } of store.resolvedDocLinkPairs()) {
+ if (source === target) continue;
+ const sourcePath = pathById.get(source);
+ const targetPath = pathById.get(target);
+ if (!sourcePath || !targetPath) continue;
+ linkedPairs.add(bridgePairKey(sourcePath, targetPath));
+ inbound.set(target, (inbound.get(target) ?? 0) + 1);
+ }
+
+ // Orphans first: ascending inbound count, path tie-break.
+ const candidates = [...documents.entries()]
+ .map(([path, summary]) => ({ path, id: summary.id, inbound: inbound.get(summary.id) ?? 0 }))
+ .toSorted((a, b) =>
+ a.inbound !== b.inbound ? a.inbound - b.inbound : a.path < b.path ? -1 : 1,
+ )
+ .slice(0, maxCandidates);
+
+ // Best similarity per unordered pair.
+ const best = new Map<string, BridgeProposal>();
+ for (const candidate of candidates) {
+ const chunks = store.chunksForDocument(candidate.id).slice(0, BRIDGE_CHUNKS_PER_DOC);
+ for (const chunk of chunks) {
+ const embedding = store.embeddingForChunk(chunk.id);
+ if (embedding === null) continue;
+ for (const hit of store.semanticTopK(embedding, { limit: BRIDGE_KNN_K })) {
+ if (hit.documentId === candidate.id) continue;
+ const otherPath = pathById.get(hit.documentId);
+ if (!otherPath) continue;
+ // Unit vectors: L2^2 = 2 - 2cos.
+ const similarity = 1 - (hit.distance * hit.distance) / 2;
+ if (similarity < minSimilarity) continue;
+ const key = bridgePairKey(candidate.path, otherPath);
+ if (linkedPairs.has(key) || dismissed.has(key)) continue;
+ const existing = best.get(key);
+ if (existing && existing.similarity >= similarity) continue;
+ best.set(
+ key,
+ Object.freeze({
+ source: candidate.path,
+ target: otherPath,
+ similarity,
+ sourceInbound: candidate.inbound,
+ targetInbound: inbound.get(hit.documentId) ?? 0,
+ }),
+ );
+ }
+ }
+ }
+
+ const proposals = [...best.values()]
+ .toSorted((a, b) =>
+ a.similarity !== b.similarity
+ ? b.similarity - a.similarity
+ : bridgePairKey(a.source, a.target) < bridgePairKey(b.source, b.target)
+ ? -1
+ : 1,
+ )
+ .slice(0, maxProposals);
+
+ return Object.freeze({
+ proposals: Object.freeze(proposals),
+ scannedCandidates: candidates.length,
+ vecAvailable: true,
+ });
+}
+
+// ── proposal artifact ────────────────────────────────────────────────────────
+
+function proposalsPath(vault: string): string {
+ return join(vault, "Brain", "proposals", "bridges.md");
+}
+
+function dismissedPath(vault: string): string {
+ return join(vault, "Brain", "proposals", "bridges-dismissed.json");
+}
+
+/**
+ * Regenerate the reviewable proposals artifact. Derived file: the
+ * whole document is replaced on every run.
+ */
+export function writeBridgeProposals(
+ vault: string,
+ report: BridgeDiscoveryReport,
+ opts: { readonly now: Date },
+): string {
+ const path = proposalsPath(vault);
+ const lines: string[] = [
+ "# Bridge proposals",
+ "",
+ "Auto-generated by `o2b brain links discover`. Do not edit - regenerated",
+ "on every run. Accept a pair with `o2b brain links accept <source> <target>`,",
+ "silence one with `o2b brain links dismiss <source> <target>`.",
+ "",
+ ];
+ if (report.proposals.length === 0) {
+ lines.push(
+ report.vecAvailable
+ ? "No bridge proposals: every embedding-near pair is already linked or dismissed."
+ : `No bridge proposals: ${report.reason ?? "vec layer unavailable"}.`,
+ );
+ } else {
+ lines.push("| source | target | similarity | inbound (src/tgt) |");
+ lines.push("| --- | --- | --- | --- |");
+ for (const p of report.proposals) {
+ lines.push(
+ `| [[${noteId(p.source)}]] (${p.source}) | [[${noteId(p.target)}]] (${p.target}) | ${p.similarity.toFixed(3)} | ${p.sourceInbound}/${p.targetInbound} |`,
+ );
+ }
+ }
+ const content = formatFrontmatter(
+ {
+ kind: "brain-bridge-proposals",
+ generated_at: isoSecond(opts.now),
+ proposals: report.proposals.length,
+ scanned_candidates: report.scannedCandidates,
+ },
+ lines.join("\n"),
+ );
+ mkdirSync(dirname(path), { recursive: true });
+ atomicWriteFileSync(path, content);
+ return path;
+}
+
+/** Persisted dismissals, unordered pair keys. Fail-soft read. */
+export function readDismissedBridges(vault: string): Set<string> {
+ const path = dismissedPath(vault);
+ if (!existsSync(path)) return new Set();
+ try {
+ const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+ const pairs = (parsed as { pairs?: unknown }).pairs;
+ if (!Array.isArray(pairs)) return new Set();
+ return new Set(pairs.filter((p): p is string => typeof p === "string"));
+ } catch {
+ return new Set();
+ }
+}
+
+/** Persist one dismissal; returns true when it was new. */
+export function dismissBridge(vault: string, source: string, target: string): boolean {
+ const key = bridgePairKey(source, target);
+ const dismissed = readDismissedBridges(vault);
+ if (dismissed.has(key)) return false;
+ dismissed.add(key);
+ const path = dismissedPath(vault);
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, JSON.stringify({ pairs: [...dismissed].toSorted() }, null, 2) + "\n");
+ return true;
+}
+
+// ── accept ───────────────────────────────────────────────────────────────────
+
+export interface AcceptBridgeResult {
+ readonly changed: boolean;
+ /** Normalised related targets after the write. */
+ readonly related: ReadonlyArray<string>;
+}
+
+/** Note id used inside a wikilink: basename without `.md`. */
+function noteId(relPath: string): string {
+ return basename(relPath, ".md");
+}
+
+/**
+ * Accept one proposal: append `related: "[[target]]"` to the source
+ * note's frontmatter. Idempotent (normalised target comparison);
+ * validates both endpoints exist inside the vault; honors a schema
+ * pack's `related` link constraints when one is supplied. When the
+ * target's basename is ambiguous across the vault, the wikilink keeps
+ * the full vault-relative path so the edge cannot point at the wrong
+ * note.
+ */
+export function acceptBridge(
+ vault: string,
+ source: string,
+ target: string,
+ opts: { readonly pack?: SchemaPack } = {},
+): AcceptBridgeResult {
+ const sourceAbs = resolveNotePath(vault, source, { mustExist: true });
+ resolveNotePath(vault, target, { mustExist: true });
+
+ const [meta, body] = parseFrontmatter(sourceAbs);
+ const targetBase = noteId(target);
+ const targetFull = target.replace(/\.md$/u, "");
+ const ambiguous = countBasenameMatches(vault, targetBase) > 1;
+ const link = `[[${ambiguous ? targetFull : targetBase}]]`;
+
+ const current = meta["related"];
+ const items: string[] =
+ current === undefined || current === ""
+ ? []
+ : Array.isArray(current)
+ ? current.map(String)
+ : [String(current)];
+
+ // Idempotency is checked BEFORE constraint validation: re-accepting
+ // an already-present link returns changed:false without re-judging
+ // it, because no write occurs either way. Both the basename and the
+ // full-path form count as already-linked.
+ const existingNorm = new Set(items.map((item) => normalizeRelationTarget(item)));
+ if (existingNorm.has(targetBase) || existingNorm.has(targetFull)) {
+ return Object.freeze({ changed: false, related: Object.freeze([...items]) });
+ }
+
+ if (opts.pack && Object.keys(opts.pack.link_constraints).length > 0) {
+ const sourceType = frontmatterType(meta);
+ const targetType = frontmatterType(
+ parseFrontmatter(resolveNotePath(vault, target, { mustExist: true }))[0],
+ );
+ if (!linkConstraintAllows(opts.pack.link_constraints, "related", sourceType, targetType)) {
+ const declared = opts.pack.link_constraints["related"] ?? [];
+ throw new Error(
+ `link constraint violation: related ${sourceType ?? "?"}->${targetType ?? "?"} is not allowed ` +
+ `(declared: ${declared.join(", ")})`,
+ );
+ }
+ }
+
+ const next = [...items, link];
+ const metadata = { ...meta, related: next.length === 1 ? next[0]! : next };
+ writeFrontmatterAtomic(sourceAbs, metadata, body, { overwrite: true });
+ return Object.freeze({ changed: true, related: Object.freeze(next) });
+}
+
+/** Number of vault pages sharing one basename (without `.md`). */
+function countBasenameMatches(vault: string, base: string): number {
+ let count = 0;
+ for (const page of listVaultPages(vault)) {
+ if (basename(page.path, ".md") === base) count++;
+ }
+ return count;
+}
+
+function frontmatterType(meta: Record<string, unknown>): string | null {
+ const raw = meta["type"];
+ return typeof raw === "string" && raw.trim().length > 0 ? raw.trim().toLowerCase() : null;
+}
diff --git a/src/core/brain/link-graph/communities.ts b/src/core/brain/link-graph/communities.ts
new file mode 100644
index 00000000..88e966c9
--- /dev/null
+++ b/src/core/brain/link-graph/communities.ts
@@ -0,0 +1,273 @@
+/**
+ * Graph-wide community detection with materialized cluster notes
+ * (link-recall-intelligence, t_4ba927ec).
+ *
+ * `buildConceptCluster` assembles depth-1 backlinks for ONE named
+ * target; nothing discovered structure across the whole graph. This
+ * pass runs deterministic synchronous label propagation over the
+ * resolved doc-level link graph (undirected): labels start as sorted
+ * document ids, every sweep assigns each node the most frequent label
+ * among its neighbours (lowest label breaks ties), and a fixed
+ * iteration cap guarantees termination on oscillating topologies
+ * (bipartite stars flip forever under synchronous updates). No
+ * Louvain dependency, no randomness - identical input, identical
+ * communities.
+ *
+ * Communities of size >= minSize materialize one derived note each
+ * under `Brain/clusters/`. Cluster notes are projections, not prose:
+ * members ranked by internal degree, shared entities from the index,
+ * link density - synthesis stays with the calling agent (the
+ * deep-synthesis rule). Notes are regenerated every run; a note whose
+ * community vanished is removed, but ONLY when it carries the
+ * generated marker - hand-written files in the directory are never
+ * touched.
+ */
+
+import { mkdirSync, readdirSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import type { Store } from "../../search/store.ts";
+import { atomicWriteFileSync } from "../../fs-atomic.ts";
+import { isoSecond } from "../time.ts";
+import { formatFrontmatter, parseFrontmatter } from "../../vault.ts";
+
+export const COMMUNITY_DEFAULT_MIN_SIZE = 4;
+export const COMMUNITY_MAX_ITERATIONS = 20;
+/** Shared entities listed per cluster note. */
+const CLUSTER_TOP_ENTITIES = 5;
+
+export interface CommunityMember {
+ readonly path: string;
+ /** Edges to other members of the same community. */
+ readonly internalDegree: number;
+}
+
+export interface Community {
+ /**
+ * Stable id: the most-central member's vault-relative path with
+ * `/` flattened to `-` (basename alone collides when two folders
+ * hold same-named hub notes, and colliding ids would overwrite
+ * each other's cluster files).
+ */
+ readonly id: string;
+ /** Members ranked by internal degree desc, path asc. */
+ readonly members: ReadonlyArray<CommunityMember>;
+ readonly size: number;
+ /** internal edges / possible edges, [0, 1]. */
+ readonly density: number;
+}
+
+export interface DetectCommunitiesOptions {
+ readonly minSize?: number;
+ readonly maxIterations?: number;
+}
+
+/**
+ * Deterministic label propagation over the store's resolved link
+ * graph. Read-only.
+ */
+export function detectCommunities(store: Store, opts: DetectCommunitiesOptions = {}): Community[] {
+ const minSize = Math.max(2, opts.minSize ?? COMMUNITY_DEFAULT_MIN_SIZE);
+ const maxIterations = Math.max(1, opts.maxIterations ?? COMMUNITY_MAX_ITERATIONS);
+
+ const pathById = new Map<number, string>();
+ for (const [path, summary] of store.listDocuments()) pathById.set(summary.id, path);
+
+ // Undirected adjacency over resolved pairs, self-loops dropped.
+ const adjacency = new Map<number, Set<number>>();
+ for (const { source, target } of store.resolvedDocLinkPairs()) {
+ if (source === target || !pathById.has(source) || !pathById.has(target)) continue;
+ let a = adjacency.get(source);
+ if (!a) adjacency.set(source, (a = new Set()));
+ a.add(target);
+ let b = adjacency.get(target);
+ if (!b) adjacency.set(target, (b = new Set()));
+ b.add(source);
+ }
+
+ // Synchronous sweeps in sorted-id order; lowest label wins ties.
+ const nodes = [...adjacency.keys()].toSorted((a, b) => a - b);
+ const labels = new Map<number, number>(nodes.map((n) => [n, n]));
+ for (let iteration = 0; iteration < maxIterations; iteration++) {
+ let changed = false;
+ const next = new Map<number, number>();
+ for (const node of nodes) {
+ const counts = new Map<number, number>();
+ for (const neighbour of adjacency.get(node)!) {
+ const label = labels.get(neighbour)!;
+ counts.set(label, (counts.get(label) ?? 0) + 1);
+ }
+ let bestLabel = labels.get(node)!;
+ let bestCount = 0;
+ for (const [label, count] of counts) {
+ if (count > bestCount || (count === bestCount && label < bestLabel)) {
+ bestLabel = label;
+ bestCount = count;
+ }
+ }
+ next.set(node, bestLabel);
+ if (bestLabel !== labels.get(node)) changed = true;
+ }
+ for (const [node, label] of next) labels.set(node, label);
+ if (!changed) break;
+ }
+
+ // Group, rank members, compute density. Groups are final-label
+ // equivalence classes: when the iteration cap interrupts an
+ // oscillating topology, a group is not guaranteed to be a connected
+ // component - acceptable for a digest surface, never for routing.
+ const groups = new Map<number, number[]>();
+ for (const node of nodes) {
+ const label = labels.get(node)!;
+ const group = groups.get(label);
+ if (group) group.push(node);
+ else groups.set(label, [node]);
+ }
+
+ const communities: Community[] = [];
+ for (const ids of groups.values()) {
+ if (ids.length < minSize) continue;
+ const memberSet = new Set(ids);
+ let internalEdges = 0;
+ const members = ids
+ .map((id) => {
+ let degree = 0;
+ for (const neighbour of adjacency.get(id)!) {
+ if (memberSet.has(neighbour)) degree++;
+ }
+ internalEdges += degree;
+ return { path: pathById.get(id)!, internalDegree: degree };
+ })
+ .toSorted((a, b) =>
+ a.internalDegree !== b.internalDegree
+ ? b.internalDegree - a.internalDegree
+ : a.path < b.path
+ ? -1
+ : 1,
+ );
+ internalEdges /= 2; // each undirected edge counted from both ends
+ const possible = (ids.length * (ids.length - 1)) / 2;
+ communities.push(
+ Object.freeze({
+ id: communityId(members[0]!.path),
+ members: Object.freeze(members),
+ size: ids.length,
+ density: possible === 0 ? 0 : internalEdges / possible,
+ }),
+ );
+ }
+
+ return communities.toSorted((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/** Collision-free id: vault-relative path, `/` -> `-`, no `.md`. */
+function communityId(relPath: string): string {
+ return relPath.replace(/\.md$/u, "").split("/").join("-");
+}
+
+// ── materialization ──────────────────────────────────────────────────────────
+
+const GENERATED_KIND = "brain-cluster";
+
+export interface MaterializeClusterNotesResult {
+ readonly written: ReadonlyArray<string>;
+ readonly removed: ReadonlyArray<string>;
+}
+
+function clustersDir(vault: string): string {
+ return join(vault, "Brain", "clusters");
+}
+
+/**
+ * Regenerate one derived note per community and remove generated
+ * notes whose community vanished. Hand-written files (no
+ * `kind: brain-cluster`) are never touched.
+ */
+export function materializeClusterNotes(
+ vault: string,
+ communities: ReadonlyArray<Community>,
+ opts: { readonly store: Store; readonly now: Date },
+): MaterializeClusterNotesResult {
+ const dir = clustersDir(vault);
+ mkdirSync(dir, { recursive: true });
+
+ const written: string[] = [];
+ const expected = new Set<string>();
+ for (const community of communities) {
+ const fileName = `cluster-${community.id}.md`;
+ expected.add(fileName);
+ const path = join(dir, fileName);
+ atomicWriteFileSync(path, renderClusterNote(community, opts));
+ written.push(`Brain/clusters/${fileName}`);
+ }
+
+ // Stale sweep: only generated notes are eligible for removal.
+ const removed: string[] = [];
+ for (const file of readdirSync(dir).toSorted()) {
+ if (!file.endsWith(".md") || expected.has(file)) continue;
+ const full = join(dir, file);
+ const [meta] = parseFrontmatter(full);
+ if (meta["kind"] !== GENERATED_KIND) continue;
+ rmSync(full);
+ removed.push(`Brain/clusters/${file}`);
+ }
+
+ return Object.freeze({ written: Object.freeze(written), removed: Object.freeze(removed) });
+}
+
+function renderClusterNote(
+ community: Community,
+ opts: { readonly store: Store; readonly now: Date },
+): string {
+ const entities = sharedEntities(opts.store, community);
+ const lines: string[] = [
+ `# Cluster: ${community.id}`,
+ "",
+ "Auto-generated by `o2b brain clusters run`. Do not edit - regenerated on",
+ "every run; synthesis belongs to the reading agent, not this file.",
+ "",
+ `${community.size} notes, link density ${community.density.toFixed(2)}.`,
+ "",
+ "## Members (by internal degree)",
+ "",
+ ];
+ for (const member of community.members) {
+ lines.push(
+ `- [[${basename(member.path, ".md")}]] (${member.path}) - ${member.internalDegree} internal link(s)`,
+ );
+ }
+ if (entities.length > 0) {
+ lines.push("", "## Shared entities", "");
+ for (const [entity, count] of entities) {
+ lines.push(`- ${entity} (${count} member note(s))`);
+ }
+ }
+ return formatFrontmatter(
+ {
+ kind: GENERATED_KIND,
+ cluster: community.id,
+ generated_at: isoSecond(opts.now),
+ size: community.size,
+ density: community.density.toFixed(2),
+ members: community.members.map((m) => m.path),
+ },
+ lines.join("\n"),
+ );
+}
+
+/** Entities appearing in >= 2 member notes, by member count desc. */
+function sharedEntities(store: Store, community: Community): Array<[string, number]> {
+ const counts = new Map<string, number>();
+ const summaries = store.listDocuments();
+ for (const member of community.members) {
+ const summary = summaries.get(member.path);
+ if (!summary) continue;
+ for (const entity of store.entitiesForDocument(summary.id)) {
+ counts.set(entity, (counts.get(entity) ?? 0) + 1);
+ }
+ }
+ return [...counts.entries()]
+ .filter(([, count]) => count >= 2)
+ .toSorted((a, b) => (a[1] !== b[1] ? b[1] - a[1] : a[0] < b[0] ? -1 : 1))
+ .slice(0, CLUSTER_TOP_ENTITIES);
+}
diff --git a/src/core/brain/metrics.ts b/src/core/brain/metrics.ts
new file mode 100644
index 00000000..11bfe222
--- /dev/null
+++ b/src/core/brain/metrics.ts
@@ -0,0 +1,167 @@
+/**
+ * Dashboard-ready metrics sink (link-recall-intelligence, Task 1).
+ *
+ * One append-only JSONL file per surface under `Brain/metrics/` -
+ * the stable on-disk contract the upcoming dashboard plugin reads
+ * without importing OSB internals. Every record is one line:
+ *
+ * {"schema":"o2b.metrics.v1","surface":"...","run_at":"...","payload":{...}}
+ *
+ * Records are RUN-LEVEL (one per index run, discovery pass, benchmark
+ * or tuning run) - per-query events stay in recall telemetry. Writes
+ * use O_APPEND single lines (the maintenance-journal pattern) so
+ * concurrent writers interleave instead of racing a rewrite; reads
+ * are fail-soft (missing dir/file -> empty, torn lines skipped).
+ *
+ * Evolution rule mirrors continuity records: additive optional fields
+ * do NOT bump the version; renames, removals, or semantic changes
+ * bump to `o2b.metrics.v2`. The contract is documented for dashboard
+ * consumers in `docs/metrics.md`.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** On-disk schema version stamped on every metric record. */
+export const METRICS_SCHEMA_VERSION = "o2b.metrics.v1";
+
+/** Surface names: lowercase snake_case, max 64 chars. */
+const SURFACE_RE = /^[a-z][a-z0-9_]{0,63}$/;
+
+/** ISO-8601 UTC timestamp shape (second or millisecond precision). */
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+
+export class MetricSurfaceError extends Error {
+ constructor(message: string) {
+ super(message);
+ this.name = "MetricSurfaceError";
+ }
+}
+
+/** One persisted metric record, as read back from disk. */
+export interface MetricRecord {
+ readonly schema: string;
+ readonly surface: string;
+ readonly run_at: string;
+ readonly payload: Readonly<Record<string, unknown>>;
+}
+
+export interface AppendMetricInput {
+ readonly surface: string;
+ /** ISO-8601 UTC timestamp of the run this record describes. */
+ readonly runAt: string;
+ readonly payload: Readonly<Record<string, unknown>>;
+}
+
+export interface ListMetricsFilter {
+ readonly surface?: string;
+ /** Inclusive lower bound on `run_at`. */
+ readonly since?: string;
+ readonly limit?: number;
+}
+
+function metricsDir(vault: string): string {
+ return join(vault, "Brain", "metrics");
+}
+
+function surfacePath(vault: string, surface: string): string {
+ return join(metricsDir(vault), `${surface}.jsonl`);
+}
+
+function assertSurface(surface: string): void {
+ if (!SURFACE_RE.test(surface)) {
+ throw new MetricSurfaceError(
+ `invalid metric surface '${surface}': expected lowercase snake_case ([a-z][a-z0-9_]*, max 64 chars)`,
+ );
+ }
+}
+
+/**
+ * Append one run-level metric record to the surface's JSONL file.
+ * Creates `Brain/metrics/` on first write.
+ */
+export function appendMetric(vault: string, input: AppendMetricInput): void {
+ assertSurface(input.surface);
+ if (!ISO_RE.test(input.runAt)) {
+ throw new MetricSurfaceError(
+ `invalid run_at '${input.runAt}': expected ISO-8601 UTC (YYYY-MM-DDTHH:MM:SSZ)`,
+ );
+ }
+ const record: MetricRecord = {
+ schema: METRICS_SCHEMA_VERSION,
+ surface: input.surface,
+ run_at: input.runAt,
+ payload: input.payload,
+ };
+ const path = surfacePath(vault, input.surface);
+ mkdirSync(dirname(path), { recursive: true });
+ appendFileSync(path, JSON.stringify(record) + "\n");
+}
+
+/**
+ * Metric records, newest-first by `run_at` (file order tie-break).
+ * Without a `surface` filter every surface file is merged. Missing
+ * dir/file reads as empty; torn or non-object lines are skipped.
+ */
+export function listMetrics(vault: string, filter: ListMetricsFilter = {}): MetricRecord[] {
+ let surfaces: string[];
+ if (filter.surface !== undefined) {
+ assertSurface(filter.surface);
+ surfaces = [filter.surface];
+ } else {
+ const dir = metricsDir(vault);
+ if (!existsSync(dir)) return [];
+ surfaces = readdirSync(dir)
+ .filter((f) => f.endsWith(".jsonl"))
+ .map((f) => f.slice(0, -".jsonl".length))
+ .filter((s) => SURFACE_RE.test(s))
+ .toSorted();
+ }
+
+ const out: Array<{ record: MetricRecord; seq: number }> = [];
+ let seq = 0;
+ for (const surface of surfaces) {
+ for (const record of readSurface(vault, surface)) {
+ if (filter.since !== undefined && record.run_at < filter.since) continue;
+ out.push({ record, seq: seq++ });
+ }
+ }
+ // Newest first; stable on equal timestamps via file/line order.
+ out.sort((a, b) =>
+ a.record.run_at === b.record.run_at
+ ? a.seq - b.seq
+ : a.record.run_at < b.record.run_at
+ ? 1
+ : -1,
+ );
+ const records = out.map((e) => e.record);
+ return filter.limit !== undefined ? records.slice(0, Math.max(0, filter.limit)) : records;
+}
+
+function readSurface(vault: string, surface: string): MetricRecord[] {
+ const path = surfacePath(vault, surface);
+ if (!existsSync(path)) return [];
+ const out: MetricRecord[] = [];
+ for (const line of readFileSync(path, "utf8").split("\n")) {
+ if (line.trim().length === 0) continue;
+ try {
+ const parsed: unknown = JSON.parse(line);
+ if (
+ parsed !== null &&
+ typeof parsed === "object" &&
+ !Array.isArray(parsed) &&
+ typeof (parsed as { schema?: unknown }).schema === "string" &&
+ typeof (parsed as { surface?: unknown }).surface === "string" &&
+ typeof (parsed as { run_at?: unknown }).run_at === "string" &&
+ (parsed as { payload?: unknown }).payload !== null &&
+ typeof (parsed as { payload?: unknown }).payload === "object" &&
+ !Array.isArray((parsed as { payload?: unknown }).payload)
+ ) {
+ out.push(parsed as MetricRecord);
+ }
+ } catch {
+ // Fail-soft: a torn line never breaks the metrics read.
+ }
+ }
+ return out;
+}
diff --git a/src/core/search/benchmark.ts b/src/core/search/benchmark.ts
new file mode 100644
index 00000000..45fd161f
--- /dev/null
+++ b/src/core/search/benchmark.ts
@@ -0,0 +1,174 @@
+/**
+ * Reproducible recall benchmark (link-recall-intelligence,
+ * t_e2215d49).
+ *
+ * A fixed query/expected-result dataset scored against the live
+ * hybrid pipeline (`search()`): hit@k and MRR per query and in
+ * aggregate. Three consumers share this runner:
+ *
+ * - the CI regression gate (`tests/core/search/recall-benchmark
+ * .test.ts`) pins thresholds over the committed fixture vault, so
+ * a ranking regression fails the suite deterministically;
+ * - `o2b brain benchmark run` scores an operator vault on demand and
+ * records the run in `Brain/metrics/recall_benchmark.jsonl`;
+ * - `tuneRecall` (t_ae973491) uses the report as the objective
+ * function when grid-evaluating retrieval parameters.
+ *
+ * The runner itself is read-only and emits nothing - metric emission
+ * belongs to the CLI/MCP callers, so library use stays side-effect
+ * free.
+ */
+
+import { search } from "./search.ts";
+import { SearchError } from "./types.ts";
+import type { ResolvedSearchConfig } from "./types.ts";
+
+/** Default rank depth for hit@k / reciprocal rank. */
+export const BENCHMARK_DEFAULT_K = 5;
+
+export interface RecallBenchmarkQuery {
+ readonly id: string;
+ readonly query: string;
+ /** Vault-relative paths counted as a hit, any-of. */
+ readonly expected: ReadonlyArray<string>;
+ /** Per-query rank depth override. */
+ readonly k?: number;
+}
+
+export interface RecallBenchmarkDataset {
+ readonly queries: ReadonlyArray<RecallBenchmarkQuery>;
+}
+
+export interface RecallBenchmarkOptions {
+ /** Rank depth, default {@link BENCHMARK_DEFAULT_K}. */
+ readonly k?: number;
+ /** Route every query through deterministic expansion (t_2fa95db1). */
+ readonly expand?: boolean;
+}
+
+export interface RecallBenchmarkQueryResult {
+ readonly id: string;
+ readonly query: string;
+ readonly hit: boolean;
+ /** 1-based rank of the first expected path, null on a miss. */
+ readonly rank: number | null;
+ readonly reciprocalRank: number;
+}
+
+export interface RecallBenchmarkReport {
+ readonly total: number;
+ readonly k: number;
+ readonly expand: boolean;
+ /** Fraction of queries with an expected path in the top k. */
+ readonly hitAtK: number;
+ /** Mean reciprocal rank over all queries (misses contribute 0). */
+ readonly mrr: number;
+ readonly perQuery: ReadonlyArray<RecallBenchmarkQueryResult>;
+}
+
+/**
+ * Validate a parsed dataset JSON value. Throws `SearchError`
+ * (INVALID_INPUT) naming the first offending entry.
+ */
+export function parseRecallBenchmarkDataset(raw: unknown): RecallBenchmarkDataset {
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+ throw new SearchError("INVALID_INPUT", "benchmark dataset must be a JSON object");
+ }
+ const queries = (raw as { queries?: unknown }).queries;
+ if (!Array.isArray(queries) || queries.length === 0) {
+ throw new SearchError("INVALID_INPUT", "benchmark dataset needs a non-empty `queries` array");
+ }
+ const seen = new Set<string>();
+ const parsed = queries.map((entry, i) => {
+ if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+ throw new SearchError("INVALID_INPUT", `benchmark query #${i} must be an object`);
+ }
+ const q = entry as { id?: unknown; query?: unknown; expected?: unknown; k?: unknown };
+ if (typeof q.id !== "string" || q.id.trim().length === 0) {
+ throw new SearchError("INVALID_INPUT", `benchmark query #${i} needs a non-empty string id`);
+ }
+ if (seen.has(q.id)) {
+ throw new SearchError("INVALID_INPUT", `benchmark query id '${q.id}' is duplicated`);
+ }
+ seen.add(q.id);
+ if (typeof q.query !== "string" || q.query.trim().length === 0) {
+ throw new SearchError("INVALID_INPUT", `benchmark query '${q.id}' needs a query string`);
+ }
+ if (
+ !Array.isArray(q.expected) ||
+ q.expected.length === 0 ||
+ q.expected.some((p) => typeof p !== "string" || p.length === 0)
+ ) {
+ throw new SearchError(
+ "INVALID_INPUT",
+ `benchmark query '${q.id}' needs a non-empty expected path array`,
+ );
+ }
+ if (q.k !== undefined && (!Number.isInteger(q.k) || (q.k as number) < 1)) {
+ throw new SearchError("INVALID_INPUT", `benchmark query '${q.id}' k must be a positive int`);
+ }
+ return Object.freeze({
+ id: q.id,
+ query: q.query,
+ expected: Object.freeze([...(q.expected as string[])]) as ReadonlyArray<string>,
+ ...(q.k !== undefined ? { k: q.k as number } : {}),
+ });
+ });
+ return Object.freeze({ queries: Object.freeze(parsed) });
+}
+
+/**
+ * Score the dataset against the vault behind `config`. Queries run
+ * concurrently (read-only); the report order follows the dataset.
+ */
+export async function runRecallBenchmark(
+ config: ResolvedSearchConfig,
+ dataset: RecallBenchmarkDataset,
+ opts: RecallBenchmarkOptions = {},
+): Promise<RecallBenchmarkReport> {
+ if (dataset.queries.length === 0) {
+ throw new SearchError("INVALID_INPUT", "benchmark dataset needs a non-empty `queries` array");
+ }
+ if (opts.k !== undefined && (!Number.isInteger(opts.k) || opts.k < 1)) {
+ throw new SearchError("INVALID_INPUT", "benchmark k must be a positive integer");
+ }
+ const k = opts.k ?? BENCHMARK_DEFAULT_K;
+ const expand = opts.expand === true;
+
+ const perQuery = await Promise.all(
+ dataset.queries.map(async (q): Promise<RecallBenchmarkQueryResult> => {
+ const depth = q.k ?? k;
+ const outcome = await search(config, {
+ query: q.query,
+ limit: depth,
+ ...(expand ? { expand: true } : {}),
+ });
+ const expected = new Set(q.expected);
+ let rank: number | null = null;
+ for (let i = 0; i < outcome.results.length && i < depth; i++) {
+ if (expected.has(outcome.results[i]!.path)) {
+ rank = i + 1;
+ break;
+ }
+ }
+ return Object.freeze({
+ id: q.id,
+ query: q.query,
+ hit: rank !== null,
+ rank,
+ reciprocalRank: rank === null ? 0 : 1 / rank,
+ });
+ }),
+ );
+
+ const hits = perQuery.filter((r) => r.hit).length;
+ const mrr = perQuery.reduce((sum, r) => sum + r.reciprocalRank, 0) / perQuery.length;
+ return Object.freeze({
+ total: perQuery.length,
+ k,
+ expand,
+ hitAtK: hits / perQuery.length,
+ mrr,
+ perQuery: Object.freeze(perQuery),
+ });
+}
diff --git a/src/core/search/index.ts b/src/core/search/index.ts
index d336582a..33393298 100644
--- a/src/core/search/index.ts
+++ b/src/core/search/index.ts
@@ -497,6 +497,17 @@ export function resolveSearchConfig(opts: {
true,
"search_two_pass_enabled",
);
+ const poolMultiplier = parseInteger(
+ envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_POOL_MULTIPLIER", "search_pool_multiplier"),
+ 3,
+ "search_pool_multiplier",
+ { min: 1, max: 10 },
+ );
+ const selfTuningEnabled = parseBool(
+ envOrConfig(env, config, "OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING", "search_self_tuning_enabled"),
+ false,
+ "search_self_tuning_enabled",
+ );
const recall: ResolvedRecallConfig = Object.freeze({
mmrLambda,
maxHops,
@@ -514,6 +525,8 @@ export function resolveSearchConfig(opts: {
learnedWeightsEnabled,
activationEnabled,
twoPassEnabled,
+ poolMultiplier,
+ selfTuningEnabled,
});
const base: ResolvedSearchConfig = Object.freeze({
diff --git a/src/core/search/indexer.ts b/src/core/search/indexer.ts
index 1405b67c..7b908bbd 100644
--- a/src/core/search/indexer.ts
+++ b/src/core/search/indexer.ts
@@ -42,6 +42,7 @@ import { loadSchemaPack, type SchemaPack } from "../brain/schema-pack.ts";
import { tieredFieldsForKind } from "../brain/frontmatter-tiers.ts";
import { normalizeSchemaToken } from "../brain/schema-vocab.ts";
import { parseFrontmatterText } from "../vault.ts";
+import { appendMetric } from "../brain/metrics.ts";
import { extractEntities } from "./entities.ts";
import { Store } from "./store.ts";
import { SearchError } from "./types.ts";
@@ -83,6 +84,7 @@ interface MutableStats {
errors: Array<{ readonly path: string; readonly message: string }>;
relationViolations: IndexStats["relationViolations"];
tierDrift: IndexStats["tierDrift"];
+ aliasResolved: number;
}
function newStats(): MutableStats {
@@ -97,6 +99,7 @@ function newStats(): MutableStats {
errors: [],
relationViolations: [],
tierDrift: [],
+ aliasResolved: 0,
};
}
@@ -112,6 +115,7 @@ function freezeStats(s: MutableStats, durationMs: number): IndexStats {
errors: Object.freeze([...s.errors]),
relationViolations: Object.freeze([...s.relationViolations]),
tierDrift: Object.freeze([...s.tierDrift]),
+ aliasResolved: s.aliasResolved,
durationMs,
});
}
@@ -141,6 +145,17 @@ function pageTypeFromFrontmatter(frontmatter: Record<string, unknown>): string |
return normalized.length > 0 ? normalized : null;
}
+/**
+ * The page's declared frontmatter `aliases` as raw strings (the store
+ * normalises). Tolerant by design: a non-array value or non-string
+ * entries never fail indexing, they are simply skipped.
+ */
+function aliasesFromFrontmatter(frontmatter: Record<string, unknown>): string[] {
+ const raw = frontmatter["aliases"];
+ if (!Array.isArray(raw)) return [];
+ return raw.filter((v): v is string => typeof v === "string");
+}
+
const UTF8_FATAL = new TextDecoder("utf-8", { fatal: true });
function readUtf8(absPath: string): string {
@@ -249,6 +264,10 @@ async function indexInto(
if (typeof frontmatter["kind"] === "string" && frontmatter["kind"].length > 0) {
tieredDocs.push({ docId, relPath: file.relPath, frontmatter });
}
+ // Vault-wide alias resolution (v7): replace this document's
+ // declared aliases so the post-pass can materialize alias
+ // wikilink targets.
+ store.replaceDocAliases(docId, aliasesFromFrontmatter(frontmatter));
const chunkInputs: ChunkInput[] = chunkResult.chunks.map((c) => ({
chunkIndex: c.chunkIndex,
@@ -319,6 +338,9 @@ async function indexInto(
}
store.resolveLinkTargets();
+ // Alias post-pass (v7): exact path matches above always win; this
+ // only fills still-unresolved slash-free targets from doc_aliases.
+ stats.aliasResolved = store.resolveAliasTargets();
// Link-constraint materialization post-pass
// (write-time-integrity-governance): recompute every typed edge's
@@ -397,6 +419,25 @@ async function indexInto(
// and schema are unchanged.
if (stats.added + stats.updated + stats.deleted > 0) {
store.bumpIndexRevision();
+ // Dashboard contract (link-recall-intelligence): one run-level
+ // record per non-empty index run. Fail-soft - a metrics-layer
+ // problem never fails the index.
+ try {
+ appendMetric(config.vault, {
+ surface: "index",
+ runAt: now,
+ payload: {
+ added: stats.added,
+ updated: stats.updated,
+ deleted: stats.deleted,
+ alias_resolved: stats.aliasResolved,
+ relation_violations: stats.relationViolations.length,
+ tier_drift: stats.tierDrift.length,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
}
return freezeStats(stats, Date.now() - t0);
diff --git a/src/core/search/query-expansion.ts b/src/core/search/query-expansion.ts
new file mode 100644
index 00000000..b8c998aa
--- /dev/null
+++ b/src/core/search/query-expansion.ts
@@ -0,0 +1,149 @@
+/**
+ * Deterministic query expansion producer (link-recall-intelligence,
+ * t_2fa95db1).
+ *
+ * The structured lex/vec/hyde recall document has had a consumer since
+ * `structured-query.ts` landed, but the lanes had to be authored
+ * upstream by the caller. `expandQuery` is the local producer: pure
+ * string work plus one read of the vault's entity registry - no local
+ * model, no paid call, identical output for identical input.
+ *
+ * - lex: query tokens minus stopwords (the FTS lane is implicit AND,
+ * so one stopword absent from the target note kills the match);
+ * falls back to the raw tokens when everything is a stopword.
+ * - vec: the raw query, plus one entity-context line when registry
+ * entities match a query token - anchors the semantic lane to the
+ * vault's own vocabulary.
+ * - hyde: one template passage shaped like the note that would
+ * answer the query, for embedding retrieval.
+ *
+ * Expansion is OPT-IN per call (`search(config, {expand: true})`,
+ * `o2b brain search --expand`) and never silently active, so cached
+ * queries and benchmark runs stay comparable.
+ */
+
+import { listEntities } from "../brain/entities/registry.ts";
+import { tokenizeForExpansion } from "./synonyms.ts";
+import type { StructuredRecallQueryDocument } from "./structured-query.ts";
+
+/** Default cap on lex include terms. */
+export const EXPANSION_MAX_LEX_TERMS = 8;
+/** Default cap on matched registry entities woven into vec/hyde. */
+export const EXPANSION_MAX_ENTITIES = 3;
+
+/**
+ * Small closed-class English stopword set. Deliberately conservative:
+ * a missed stopword only leaves one extra AND term, while an
+ * over-eager list would silently drop signal.
+ */
+const STOPWORDS: ReadonlySet<string> = new Set([
+ "a",
+ "an",
+ "and",
+ "are",
+ "as",
+ "at",
+ "be",
+ "but",
+ "by",
+ "for",
+ "from",
+ "how",
+ "in",
+ "is",
+ "it",
+ "me",
+ "my",
+ "of",
+ "on",
+ "or",
+ "our",
+ "show",
+ "that",
+ "the",
+ "their",
+ "this",
+ "to",
+ "was",
+ "we",
+ "what",
+ "when",
+ "where",
+ "which",
+ "who",
+ "why",
+ "with",
+]);
+
+export interface ExpandQueryOptions {
+ readonly maxLexTerms?: number;
+ readonly maxEntities?: number;
+}
+
+/**
+ * Build a structured recall query document from a bare query.
+ * Deterministic; reads only the entity registry under `vault`.
+ */
+export function expandQuery(
+ vault: string,
+ query: string,
+ opts: ExpandQueryOptions = {},
+): StructuredRecallQueryDocument {
+ const maxLexTerms = Math.max(1, opts.maxLexTerms ?? EXPANSION_MAX_LEX_TERMS);
+ const maxEntities = Math.max(0, opts.maxEntities ?? EXPANSION_MAX_ENTITIES);
+ const trimmed = query.trim();
+
+ const tokens = [...new Set(tokenizeForExpansion(trimmed))];
+ const meaningful = tokens.filter((t) => !STOPWORDS.has(t));
+ // Fall back to the raw tokens when the whole query is stopwords -
+ // an empty lex lane would turn the FTS lane off entirely.
+ const baseTokens = meaningful.length > 0 ? meaningful : tokens;
+ const lexTerms = baseTokens.slice(0, maxLexTerms);
+
+ const entityNames = matchEntities(vault, baseTokens).slice(0, maxEntities);
+
+ const vec: string[] = [trimmed];
+ if (entityNames.length > 0) {
+ vec.push(`${trimmed} - related to ${entityNames.join(", ")}`);
+ }
+
+ const subject = lexTerms.join(" ");
+ const hydeParts = [`A note about ${subject}.`];
+ if (entityNames.length > 0) {
+ hydeParts.push(`It covers ${entityNames.join(", ")}.`);
+ }
+ hydeParts.push(`Key decisions, references, and context for ${subject}.`);
+
+ return Object.freeze({
+ intent: null,
+ lex: Object.freeze({
+ include: Object.freeze(lexTerms) as ReadonlyArray<string>,
+ exclude: Object.freeze([]) as ReadonlyArray<string>,
+ }),
+ vec: Object.freeze(vec) as ReadonlyArray<string>,
+ hyde: Object.freeze([hydeParts.join(" ")]) as ReadonlyArray<string>,
+ });
+}
+
+/**
+ * Registry entities whose name (or alias) shares a token with the
+ * query, sorted by name for determinism. Fail-soft: a vault without a
+ * registry simply matches nothing.
+ */
+function matchEntities(vault: string, queryTokens: ReadonlyArray<string>): string[] {
+ if (queryTokens.length === 0) return [];
+ const wanted = new Set(queryTokens);
+ let names: string[];
+ try {
+ names = listEntities(vault, { status: "active" })
+ .filter((entity) =>
+ [entity.name, ...entity.aliases].some((label) =>
+ tokenizeForExpansion(label).some((token) => wanted.has(token)),
+ ),
+ )
+ .map((entity) => entity.name);
+ } catch {
+ return [];
+ }
+ return [...new Set(names)].toSorted();
+}
diff --git a/src/core/search/schema.ts b/src/core/search/schema.ts
index 8de8eea1..ca3a95df 100644
--- a/src/core/search/schema.ts
+++ b/src/core/search/schema.ts
@@ -16,7 +16,7 @@ import { SearchError } from "./types.ts";
* this raises `SCHEMA_MISMATCH` on open — the operator must reindex
* with a newer binary.
*/
-export const LATEST_SCHEMA_VERSION = 6;
+export const LATEST_SCHEMA_VERSION = 7;
const DDL_V1 = `
CREATE TABLE IF NOT EXISTS documents (
@@ -304,6 +304,27 @@ export const MIGRATIONS: ReadonlyArray<Migration> = Object.freeze([
`);
},
},
+ {
+ // v7 (link-recall-intelligence) - vault-wide frontmatter alias
+ // resolution at materialization time. The indexer extracts a
+ // note's `aliases:` array (NFC-normalised, lower-cased) into
+ // `doc_aliases`; `resolveAliasTargets` then materializes
+ // `target_document_id` for unresolved slash-free wikilink
+ // targets that match an alias. Additive and reindex-safe:
+ // existing rows simply have no aliases until a reindex
+ // repopulates them.
+ version: 7,
+ up(db) {
+ db.exec(`
+ CREATE TABLE IF NOT EXISTS doc_aliases (
+ document_id INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+ alias TEXT NOT NULL,
+ UNIQUE(document_id, alias)
+ );
+ CREATE INDEX IF NOT EXISTS idx_doc_aliases_alias ON doc_aliases(alias);
+ `);
+ },
+ },
]);
/** Read the current schema version from `index_state`. Returns 0 if not yet recorded. */
diff --git a/src/core/search/search.ts b/src/core/search/search.ts
index 3a368270..ab1d7087 100644
--- a/src/core/search/search.ts
+++ b/src/core/search/search.ts
@@ -59,6 +59,8 @@ import type {
SearchOutcome,
} from "./types.ts";
import type { StructuredRecallQueryDocument } from "./structured-query.ts";
+import { expandQuery } from "./query-expansion.ts";
+import { applyTunedParameters, loadTunedParameters } from "./tuning.ts";
interface SemanticPolicy {
/** caller asked for semantic on or off (true), or accepted the default (false). */
@@ -202,11 +204,21 @@ export async function search(
if (!query) {
throw new SearchError("INVALID_INPUT", "missing required argument: query");
}
+ // Opt-in self-tuning (t_ae973491): apply the persisted, re-validated
+ // grid point. applyTunedParameters disarms selfTuningEnabled, so the
+ // applied config can never recurse. An explicit opts.expand always
+ // wins over the tuned expansion default.
+ const tuned = config.recall.selfTuningEnabled ? loadTunedParameters(config.vault) : null;
+ if (tuned !== null) config = applyTunedParameters(config, tuned);
+ const expandActive = opts.expand ?? (tuned !== null && tuned.expansion);
const limit = Math.max(1, Math.min(100, opts.limit ?? 10));
const pathPrefix = assertSafePathPrefix(opts.pathPrefix);
const policy = resolveSemanticPolicy(config, opts);
const warnings: string[] = [];
- const structured = opts.structuredQuery;
+ // Opt-in local expansion (t_2fa95db1): an explicit structured
+ // document always wins; expansion only fills the gap.
+ const structured =
+ opts.structuredQuery ?? (expandActive === true ? expandQuery(config.vault, query) : undefined);
const sessionFocus =
opts.sessionFocus === undefined
? readActiveSessionFocus(config, opts.focusSession, Date.now())
@@ -272,10 +284,11 @@ export async function search(
const actFp = config.recall.activationEnabled
? activationStateFingerprint(config.vault)
: "off";
+ const tuneFp = tuned !== null ? JSON.stringify(tuned) : "off";
cacheKey = buildCacheKey(
keyOpts,
basePlan.planHash,
- `${configFingerprint(config)}|lw:${lwFp}|act:${actFp}`,
+ `${configFingerprint(config)}|lw:${lwFp}|act:${actFp}|tune:${tuneFp}`,
);
const hit = getCachedOutcome(store, cacheKey, generation, ttlMs, Date.now());
if (hit) return hit;
@@ -297,7 +310,7 @@ export async function search(
// Keyword candidates.
let kwOutcome = runFtsQueryDetailed(store, keywordQuery, {
- limit: limit * 3,
+ limit: limit * config.recall.poolMultiplier,
pathPrefix,
});
let kwHits = kwOutcome.hits;
@@ -320,7 +333,7 @@ export async function search(
if (expandedTerms.length > 0) {
plan = buildQueryPlan(keywordQuery, expandedTerms, structured?.intent);
kwOutcome = runFtsQueryDetailed(store, keywordQuery, {
- limit: limit * 3,
+ limit: limit * config.recall.poolMultiplier,
pathPrefix,
expandedTerms,
});
diff --git a/src/core/search/store.ts b/src/core/search/store.ts
index 5b13b8fb..dc8ef26d 100644
--- a/src/core/search/store.ts
+++ b/src/core/search/store.ts
@@ -222,6 +222,16 @@ function acquireWriterLockSync(path: string): () => void {
throw new SearchError("INDEX_LOCKED", `another writer holds the search index lock: ${msg}`);
}
+/**
+ * Canonical alias/lookup-key normalisation for `doc_aliases` (v7):
+ * trim, NFC-normalise, lower-case - the exact rule
+ * `link-graph/alias-index.ts` applies on the Brain-artifact side, so
+ * the two alias surfaces never disagree on a key.
+ */
+export function normalizeAlias(value: string): string {
+ return value.trim().normalize("NFC").toLowerCase();
+}
+
function vecToBuffer(values: ReadonlyArray<number> | Float32Array): Buffer {
const arr = values instanceof Float32Array ? values : Float32Array.from(values);
return Buffer.from(arr.buffer, arr.byteOffset, arr.byteLength);
@@ -915,6 +925,135 @@ export class Store {
);
}
+ // ── doc aliases (v7, link-recall-intelligence) ─────────────────────────────
+
+ /**
+ * Replace one document's frontmatter aliases. Values are normalised
+ * via {@link normalizeAlias}; empties and duplicates are dropped.
+ */
+ replaceDocAliases(documentId: number, aliases: ReadonlyArray<string>): void {
+ const normalised = [...new Set(aliases.map(normalizeAlias).filter((a) => a.length > 0))];
+ this.db.exec("BEGIN");
+ try {
+ this.db.run("DELETE FROM doc_aliases WHERE document_id = ?", [documentId]);
+ if (normalised.length > 0) {
+ const insert = this.db.prepare<undefined, [number, string]>(
+ "INSERT OR IGNORE INTO doc_aliases(document_id, alias) VALUES (?, ?)",
+ );
+ for (const alias of normalised) insert.run(documentId, alias);
+ }
+ this.db.exec("COMMIT");
+ } catch (e) {
+ this.db.exec("ROLLBACK");
+ throw e;
+ }
+ }
+
+ /** Normalised aliases of one document, sorted. */
+ aliasesForDocument(documentId: number): ReadonlyArray<string> {
+ return this.db
+ .query<{ alias: string }, [number]>(
+ "SELECT alias FROM doc_aliases WHERE document_id = ? ORDER BY alias ASC",
+ )
+ .all(documentId)
+ .map((r) => r.alias);
+ }
+
+ /**
+ * Materialize `target_document_id` for unresolved, slash-free link
+ * targets that match a declared alias. Runs AFTER
+ * {@link resolveLinkTargets} so exact path matches always win.
+ *
+ * Shadowing rule (mirrors `alias-index.ts`): a target that equals a
+ * real document basename is never alias-resolved - the read-time
+ * basename fallback owns it. Collisions (two documents claim one
+ * alias) resolve first-wins by sorted document path. Normalisation
+ * happens in JS because SQLite `lower()` is ASCII-only.
+ *
+ * Returns the number of link rows resolved.
+ */
+ resolveAliasTargets(): number {
+ const unresolved = this.db
+ .query<{ target_path: string }, []>(
+ "SELECT DISTINCT target_path FROM links " +
+ "WHERE target_document_id IS NULL AND target_path IS NOT NULL " +
+ "AND link_type = 'wikilink' AND instr(target_path, '/') = 0",
+ )
+ .all();
+ if (unresolved.length === 0) return 0;
+
+ const aliasOwner = this.db.prepare<{ document_id: number }, [string]>(
+ "SELECT a.document_id AS document_id FROM doc_aliases a " +
+ "JOIN documents d ON d.id = a.document_id " +
+ "WHERE a.alias = ? ORDER BY d.path ASC LIMIT 1",
+ );
+ const basenameExists = this.db.prepare<{ id: number }, [string, string, string]>(
+ "SELECT id FROM documents WHERE path = ? " +
+ "OR SUBSTR(path, -(LENGTH(?) + 4)) = '/' || ? || '.md' LIMIT 1",
+ );
+ const update = this.db.prepare<undefined, [number, string]>(
+ "UPDATE links SET target_document_id = ? " +
+ "WHERE target_document_id IS NULL AND target_path = ? AND link_type = 'wikilink'",
+ );
+
+ let resolved = 0;
+ this.db.exec("BEGIN");
+ try {
+ for (const row of unresolved) {
+ const key = normalizeAlias(row.target_path);
+ if (key.length === 0) continue;
+ // Skip targets a real document basename owns.
+ if (basenameExists.get(`${row.target_path}.md`, row.target_path, row.target_path)) {
+ continue;
+ }
+ const owner = aliasOwner.get(key);
+ if (!owner) continue;
+ update.run(owner.document_id, row.target_path);
+ resolved += this.db.query<{ n: number }, []>("SELECT changes() AS n").get()?.n ?? 0;
+ }
+ this.db.exec("COMMIT");
+ } catch (e) {
+ this.db.exec("ROLLBACK");
+ throw e;
+ }
+ return resolved;
+ }
+
+ /**
+ * Every link edge resolved to a (source, target) document-id pair,
+ * deduplicated, using the same conservative resolution ladder as
+ * {@link typedRelationEdgesForDocuments}: materialized id first,
+ * then `<target>.md` exact, then an UNAMBIGUOUS basename suffix.
+ * Unresolvable edges are absent. Read-only; feeds bridge discovery
+ * and community detection (link-recall-intelligence).
+ */
+ resolvedDocLinkPairs(): Array<{ readonly source: number; readonly target: number }> {
+ const rows = this.db
+ .query<{ source: number; target: number | null }, []>(
+ "SELECT DISTINCT l.source_document_id AS source, " +
+ " COALESCE(" +
+ " l.target_document_id, " +
+ " (SELECT d.id FROM documents d WHERE d.path = l.target_path || '.md'), " +
+ " (SELECT d.id FROM documents d " +
+ " WHERE SUBSTR(d.path, -(LENGTH(l.target_path) + 4)) = '/' || l.target_path || '.md' " +
+ " AND 1 = (SELECT COUNT(*) FROM documents d2 " +
+ " WHERE SUBSTR(d2.path, -(LENGTH(l.target_path) + 4)) = '/' || l.target_path || '.md'))" +
+ " ) AS target " +
+ "FROM links l WHERE l.target_path IS NOT NULL",
+ )
+ .all();
+ const out: Array<{ source: number; target: number }> = [];
+ for (const r of rows) {
+ if (r.target !== null) out.push({ source: r.source, target: r.target });
+ }
+ return out;
+ }
+
+ /** Number of chunks with a stored embedding row. */
+ countEmbeddings(): number {
+ return this.db.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM embeddings").get()?.n ?? 0;
+ }
+
/**
* For each document id, the typed relation edges it declares
* (v3 / typed graph semantics): rows whose `relation` is set, in
@@ -1569,6 +1708,20 @@ export class Store {
}
}
+ /**
+ * Distinct entities across one document's chunks, sorted
+ * (link-recall-intelligence: shared-entity digest in cluster notes).
+ */
+ entitiesForDocument(documentId: number): ReadonlyArray<string> {
+ return this.db
+ .query<{ entity: string }, [number]>(
+ "SELECT DISTINCT e.entity AS entity FROM chunk_entities e " +
+ "JOIN chunks c ON c.id = e.chunk_id WHERE c.document_id = ? ORDER BY e.entity ASC",
+ )
+ .all(documentId)
+ .map((r) => r.entity);
+ }
+
/**
* For each candidate chunk, the count of distinct query entities it
* also carries. Empty `queryEntities` yields an empty map (no work).
diff --git a/src/core/search/tuning.ts b/src/core/search/tuning.ts
new file mode 100644
index 00000000..94805943
--- /dev/null
+++ b/src/core/search/tuning.ts
@@ -0,0 +1,209 @@
+/**
+ * Opt-in self-tuning recall (link-recall-intelligence, t_ae973491).
+ *
+ * The learned-weights fold already adapts per-layer multipliers from
+ * explicit feedback; nothing tuned retrieval PARAMETERS. This module
+ * closes that loop with the same philosophy - bounded, deterministic,
+ * replayable:
+ *
+ * - the parameter space is a FIXED grid (candidate-pool multiplier
+ * {3,4,5}, traversal depth {1,2}, learned weights on/off,
+ * expansion on/off) - nothing learned can leave it;
+ * - the objective function is the recall benchmark (t_e2215d49)
+ * over an operator-chosen dataset, best MRR wins (hit@k, then
+ * grid order break ties), so the choice is auditable;
+ * - the winner persists to `Brain/search/tuning.json` with every
+ * evaluated score and the dataset hash - delete the file (reset)
+ * and nothing else changes;
+ * - `search()` consults the tuned parameters ONLY when self-tuning
+ * is enabled (`search_self_tuning_enabled` /
+ * `OPEN_SECOND_BRAIN_SEARCH_SELF_TUNING`), values re-validated
+ * against the grid bounds on every read, fail-soft to defaults.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+
+import { runRecallBenchmark } from "./benchmark.ts";
+import type { RecallBenchmarkDataset } from "./benchmark.ts";
+import type { ResolvedSearchConfig } from "./types.ts";
+
+export const TUNING_SCHEMA_VERSION = "o2b.tuning.v1";
+
+/** Bounded grid axes - loadTunedParameters enforces these on read. */
+export const TUNING_POOL_MULTIPLIERS: ReadonlyArray<number> = Object.freeze([3, 4, 5]);
+export const TUNING_TRAVERSAL_DEPTHS: ReadonlyArray<number> = Object.freeze([1, 2]);
+
+export interface TunedParameters {
+ readonly poolMultiplier: number;
+ readonly traversalDepth: number;
+ readonly learnedWeights: boolean;
+ readonly expansion: boolean;
+}
+
+export interface TuningEvaluation {
+ readonly params: TunedParameters;
+ readonly mrr: number;
+ readonly hitAtK: number;
+}
+
+export interface TuneRecallReport {
+ readonly chosen: TunedParameters;
+ readonly evaluated: ReadonlyArray<TuningEvaluation>;
+ readonly datasetHash: string;
+}
+
+export interface TuneRecallOptions {
+ /** Grid override (tests, narrowed sweeps). Defaults to the full grid. */
+ readonly grid?: ReadonlyArray<TunedParameters>;
+ /** Rank depth forwarded to the benchmark. */
+ readonly k?: number;
+ /** Injected clock for the persisted `evaluated_at` stamp. */
+ readonly now: Date;
+}
+
+/** The full bounded grid in stable order (defaults first). */
+export function defaultTuningGrid(): TunedParameters[] {
+ const grid: TunedParameters[] = [];
+ for (const expansion of [false, true]) {
+ for (const learnedWeights of [false, true]) {
+ for (const traversalDepth of TUNING_TRAVERSAL_DEPTHS) {
+ for (const poolMultiplier of TUNING_POOL_MULTIPLIERS) {
+ grid.push({ poolMultiplier, traversalDepth, learnedWeights, expansion });
+ }
+ }
+ }
+ }
+ // Stable order with the all-defaults combo first: the sort above
+ // already yields (3,1,false,false) first; keep insertion order.
+ return grid;
+}
+
+/**
+ * A config with one grid point applied. Always disarms
+ * `selfTuningEnabled` so an applied config can never re-apply itself.
+ */
+export function applyTunedParameters(
+ config: ResolvedSearchConfig,
+ params: TunedParameters,
+): ResolvedSearchConfig {
+ return Object.freeze({
+ ...config,
+ recall: Object.freeze({
+ ...config.recall,
+ poolMultiplier: params.poolMultiplier,
+ maxHops: params.traversalDepth,
+ learnedWeightsEnabled: params.learnedWeights,
+ selfTuningEnabled: false,
+ }),
+ });
+}
+
+function tuningPath(vault: string): string {
+ return join(vault, "Brain", "search", "tuning.json");
+}
+
+/**
+ * Grid-evaluate against the benchmark and persist the winner.
+ * Deterministic for a fixed index state and dataset.
+ */
+export async function tuneRecall(
+ config: ResolvedSearchConfig,
+ dataset: RecallBenchmarkDataset,
+ opts: TuneRecallOptions,
+): Promise<TuneRecallReport> {
+ const grid = opts.grid ?? defaultTuningGrid();
+ if (grid.length === 0) throw new Error("tuneRecall: the parameter grid is empty");
+
+ const evaluated = await Promise.all(
+ grid.map(async (params): Promise<TuningEvaluation> => {
+ const report = await runRecallBenchmark(applyTunedParameters(config, params), dataset, {
+ ...(opts.k !== undefined ? { k: opts.k } : {}),
+ expand: params.expansion,
+ });
+ return Object.freeze({ params, mrr: report.mrr, hitAtK: report.hitAtK });
+ }),
+ );
+
+ // Best MRR; hit@k, then grid order break ties.
+ let chosen = evaluated[0]!;
+ for (const candidate of evaluated.slice(1)) {
+ if (
+ candidate.mrr > chosen.mrr ||
+ (candidate.mrr === chosen.mrr && candidate.hitAtK > chosen.hitAtK)
+ ) {
+ chosen = candidate;
+ }
+ }
+
+ const datasetHash = createHash("sha256").update(JSON.stringify(dataset)).digest("hex");
+ const path = tuningPath(config.vault);
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(
+ path,
+ JSON.stringify(
+ {
+ schema: TUNING_SCHEMA_VERSION,
+ chosen: chosen.params,
+ evaluated: evaluated.map((e) => ({
+ params: e.params,
+ mrr: e.mrr,
+ hit_at_k: e.hitAtK,
+ })),
+ dataset_hash: datasetHash,
+ evaluated_at: opts.now.toISOString(),
+ },
+ null,
+ 2,
+ ) + "\n",
+ );
+
+ return Object.freeze({
+ chosen: chosen.params,
+ evaluated: Object.freeze(evaluated),
+ datasetHash,
+ });
+}
+
+/**
+ * The persisted tuned parameters, re-validated against the grid
+ * bounds. Fail-soft: missing file, torn JSON, or any out-of-bounds
+ * value reads as null (search falls back to configured defaults).
+ */
+export function loadTunedParameters(vault: string): TunedParameters | null {
+ const path = tuningPath(vault);
+ if (!existsSync(path)) return null;
+ try {
+ const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+ const chosen = (parsed as { chosen?: unknown }).chosen;
+ if (chosen === null || typeof chosen !== "object") return null;
+ const c = chosen as Record<string, unknown>;
+ if (
+ typeof c["poolMultiplier"] !== "number" ||
+ !TUNING_POOL_MULTIPLIERS.includes(c["poolMultiplier"]) ||
+ typeof c["traversalDepth"] !== "number" ||
+ !TUNING_TRAVERSAL_DEPTHS.includes(c["traversalDepth"]) ||
+ typeof c["learnedWeights"] !== "boolean" ||
+ typeof c["expansion"] !== "boolean"
+ ) {
+ return null;
+ }
+ return Object.freeze({
+ poolMultiplier: c["poolMultiplier"],
+ traversalDepth: c["traversalDepth"],
+ learnedWeights: c["learnedWeights"],
+ expansion: c["expansion"],
+ });
+ } catch {
+ return null;
+ }
+}
+
+/** Delete the persisted tuning state. Returns true when it existed. */
+export function resetTuning(vault: string): boolean {
+ const path = tuningPath(vault);
+ if (!existsSync(path)) return false;
+ rmSync(path);
+ return true;
+}
diff --git a/src/core/search/types.ts b/src/core/search/types.ts
index d4ea7c60..35b6ca09 100644
--- a/src/core/search/types.ts
+++ b/src/core/search/types.ts
@@ -149,6 +149,12 @@ export interface IndexStats {
readonly expected: unknown;
readonly actual: unknown;
}>;
+ /**
+ * Links whose `target_document_id` the alias post-pass materialized
+ * through a frontmatter `aliases:` declaration this run
+ * (link-recall-intelligence, v7).
+ */
+ readonly aliasResolved: number;
readonly durationMs: number;
}
@@ -247,6 +253,13 @@ export interface SearchOptions {
readonly visibility?: ReadonlyArray<string>;
/** Optional parsed structured recall query document. Plain-string search ignores this. */
readonly structuredQuery?: StructuredRecallQueryDocument;
+ /**
+ * Opt-in deterministic query expansion (link-recall-intelligence,
+ * t_2fa95db1): when true and no `structuredQuery` was supplied, the
+ * bare query is expanded into lex/vec/hyde lanes locally before
+ * retrieval. Never silently active.
+ */
+ readonly expand?: boolean;
/** Optional per-query or persisted session focus steering. Undefined means load persisted focus. */
readonly sessionFocus?: SearchSessionFocus | null;
/**
@@ -413,6 +426,21 @@ export interface ResolvedRecallConfig {
* Plain (non-evidence-pack) searches never broaden either way.
*/
readonly twoPassEnabled: boolean;
+ /**
+ * Keyword candidate-pool width as a multiple of the requested limit
+ * (link-recall-intelligence, t_ae973491). Default 3 preserves the
+ * historical `limit * 3` FTS pools; the self-tuner may select 4 or
+ * 5. The semantic pool keeps its own `max(limit * 5, 50)` floor.
+ */
+ readonly poolMultiplier: number;
+ /**
+ * Opt-in self-tuning recall (t_ae973491). When true, `search()`
+ * applies the bounded parameters persisted in
+ * `Brain/search/tuning.json` (validated on read, fail-soft to the
+ * configured defaults). Off by default - tuning never activates
+ * silently.
+ */
+ readonly selfTuningEnabled: boolean;
}
export interface ResolvedSearchConfig {
diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.ts
index 176088ff..aec7b764 100644
--- a/src/mcp/brain-tools.ts
+++ b/src/mcp/brain-tools.ts
@@ -38,7 +38,7 @@
import { isAbsolute, join, relative, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
import {
resolveAgentName,
@@ -57,6 +57,21 @@ import {
import { loadSchemaPack } from "../core/brain/schema-pack.ts";
import { listSecrets } from "../core/brain/secrets/store.ts";
import { runWithSecret, SecretExecDeniedError } from "../core/brain/secrets/exec.ts";
+import {
+ acceptBridge,
+ bridgePairKey,
+ discoverBridges,
+ dismissBridge,
+ readDismissedBridges,
+ writeBridgeProposals,
+} from "../core/brain/link-graph/bridge-discovery.ts";
+import {
+ detectCommunities,
+ materializeClusterNotes,
+} from "../core/brain/link-graph/communities.ts";
+import { appendMetric } from "../core/brain/metrics.ts";
+import { parseRecallBenchmarkDataset, runRecallBenchmark } from "../core/search/benchmark.ts";
+import { loadTunedParameters, resetTuning, tuneRecall } from "../core/search/tuning.ts";
import { currentLease } from "../core/brain/maintenance/lease.ts";
import { listJournal } from "../core/brain/maintenance/journal.ts";
import { runMaintenance, type DailyWindow } from "../core/brain/maintenance/lane.ts";
@@ -2070,11 +2085,382 @@ async function toolBrainMaintenance(
await indexVault(searchConfig);
},
},
+ // Same lane contract as the CLI verb (link-recall-intelligence):
+ // bridges and clusters run after reindex so they see fresh
+ // edges; both are fail-soft without embeddings, and a metrics
+ // write failure never fails the task.
+ {
+ name: "bridges",
+ run: async () => {
+ const store = await Store.open(searchConfig, { mode: "read" });
+ try {
+ const report = discoverBridges(store, {
+ dismissed: readDismissedBridges(ctx.vault),
+ });
+ writeBridgeProposals(ctx.vault, report, { now });
+ try {
+ appendMetric(ctx.vault, {
+ surface: "bridge_discovery",
+ runAt: isoSecond(now),
+ payload: {
+ proposals: report.proposals.length,
+ scanned_candidates: report.scannedCandidates,
+ vec_available: report.vecAvailable,
+ lane: true,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ } finally {
+ await store.close();
+ }
+ },
+ },
+ {
+ name: "clusters",
+ run: async () => {
+ const store = await Store.open(searchConfig, { mode: "read" });
+ try {
+ const communities = detectCommunities(store, {});
+ const materialized = materializeClusterNotes(ctx.vault, communities, { store, now });
+ try {
+ appendMetric(ctx.vault, {
+ surface: "communities",
+ runAt: isoSecond(now),
+ payload: {
+ communities: communities.length,
+ sizes: communities.map((c) => c.size),
+ written: materialized.written.length,
+ removed: materialized.removed.length,
+ lane: true,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ } finally {
+ await store.close();
+ }
+ },
+ },
],
});
return { verdict: result.verdict, tasks: result.tasks };
}
+// ----- brain_bridges (t_ab540afe) --------------------------------------------
+
+/**
+ * Bridge discovery over the vec index: discover regenerates the
+ * reviewable proposals artifact, accept writes one related wikilink,
+ * dismiss persists a pair suppression, list reads the artifact back.
+ */
+async function toolBrainBridges(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const op = args["operation"];
+ if (op !== "discover" && op !== "list" && op !== "accept" && op !== "dismiss") {
+ throw new MCPError(
+ INVALID_PARAMS,
+ "brain_bridges: operation must be discover|list|accept|dismiss",
+ );
+ }
+ if (op === "accept" || op === "dismiss") {
+ const source = args["source"];
+ const target = args["target"];
+ if (typeof source !== "string" || source.trim() === "") {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `brain_bridges ${op}: source must be a vault-relative path`,
+ );
+ }
+ if (typeof target !== "string" || target.trim() === "") {
+ throw new MCPError(
+ INVALID_PARAMS,
+ `brain_bridges ${op}: target must be a vault-relative path`,
+ );
+ }
+ if (op === "dismiss") {
+ return {
+ dismissed: bridgePairKey(source, target),
+ added: dismissBridge(ctx.vault, source, target),
+ };
+ }
+ try {
+ const pack = loadSchemaPack(ctx.vault);
+ return { ...acceptBridge(ctx.vault, source, target, { pack }), source, target };
+ } catch (exc) {
+ const message = (exc as Error).message ?? String(exc);
+ if (/outside the vault|does not exist|link constraint/.test(message)) {
+ throw new MCPError(INVALID_PARAMS, `brain_bridges accept: ${message}`);
+ }
+ throw exc;
+ }
+ }
+ if (op === "list") {
+ const path = join(ctx.vault, "Brain", "proposals", "bridges.md");
+ if (!existsSync(path)) return { exists: false, proposals: 0 };
+ const [meta] = parseFrontmatter(path);
+ return {
+ exists: true,
+ path: "Brain/proposals/bridges.md",
+ generated_at: meta["generated_at"] ?? null,
+ proposals: Number(meta["proposals"] ?? 0),
+ };
+ }
+ // discover
+ const max = args["max"];
+ if (max !== undefined && (!Number.isInteger(max) || (max as number) < 1)) {
+ throw new MCPError(INVALID_PARAMS, "brain_bridges discover: max must be a positive integer");
+ }
+ const minSimilarity = args["min_similarity"];
+ if (
+ minSimilarity !== undefined &&
+ (typeof minSimilarity !== "number" || minSimilarity <= 0 || minSimilarity > 1)
+ ) {
+ throw new MCPError(INVALID_PARAMS, "brain_bridges discover: min_similarity must be in (0, 1]");
+ }
+ const searchConfig = resolveSearchConfig({
+ vault: ctx.vault,
+ configPath: ctx.configPath ?? undefined,
+ });
+ if (!existsSync(searchConfig.dbPath)) {
+ return { vec_available: false, proposals: [], reason: "index not built" };
+ }
+ const store = await Store.open(searchConfig, { mode: "read" });
+ const now = new Date();
+ try {
+ const dismissed = readDismissedBridges(ctx.vault);
+ const report = discoverBridges(store, {
+ ...(max !== undefined ? { maxProposals: max as number } : {}),
+ ...(minSimilarity !== undefined ? { minSimilarity } : {}),
+ dismissed,
+ });
+ writeBridgeProposals(ctx.vault, report, { now });
+ try {
+ appendMetric(ctx.vault, {
+ surface: "bridge_discovery",
+ runAt: isoSecond(now),
+ payload: {
+ proposals: report.proposals.length,
+ scanned_candidates: report.scannedCandidates,
+ vec_available: report.vecAvailable,
+ dismissed_total: dismissed.size,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ return {
+ vec_available: report.vecAvailable,
+ ...(report.reason !== undefined ? { reason: report.reason } : {}),
+ scanned_candidates: report.scannedCandidates,
+ proposals: report.proposals,
+ artifact: "Brain/proposals/bridges.md",
+ };
+ } finally {
+ await store.close();
+ }
+}
+
+// ----- brain_clusters (t_4ba927ec) --------------------------------------------
+
+/** Graph-wide community detection with materialized cluster notes. */
+async function toolBrainClusters(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const op = args["operation"];
+ if (op !== "run" && op !== "list") {
+ throw new MCPError(INVALID_PARAMS, "brain_clusters: operation must be run|list");
+ }
+ if (op === "list") {
+ const dir = join(ctx.vault, "Brain", "clusters");
+ if (!existsSync(dir)) return { clusters: [] };
+ const clusters = readdirSync(dir)
+ .filter((f) => f.endsWith(".md"))
+ .toSorted()
+ .map((f) => {
+ const [meta] = parseFrontmatter(join(dir, f));
+ return meta["kind"] === "brain-cluster"
+ ? {
+ path: `Brain/clusters/${f}`,
+ cluster: String(meta["cluster"] ?? ""),
+ size: Number(meta["size"] ?? 0),
+ density: Number(meta["density"] ?? 0),
+ generated_at: String(meta["generated_at"] ?? ""),
+ }
+ : null;
+ })
+ .filter((c) => c !== null);
+ return { clusters };
+ }
+ const minSize = args["min_size"];
+ if (minSize !== undefined && (!Number.isInteger(minSize) || (minSize as number) < 2)) {
+ throw new MCPError(INVALID_PARAMS, "brain_clusters run: min_size must be an integer >= 2");
+ }
+ const searchConfig = resolveSearchConfig({
+ vault: ctx.vault,
+ configPath: ctx.configPath ?? undefined,
+ });
+ if (!existsSync(searchConfig.dbPath)) {
+ return { communities: [], reason: "index not built" };
+ }
+ const store = await Store.open(searchConfig, { mode: "read" });
+ const now = new Date();
+ try {
+ const communities = detectCommunities(
+ store,
+ minSize !== undefined ? { minSize: minSize as number } : {},
+ );
+ const materialized = materializeClusterNotes(ctx.vault, communities, { store, now });
+ try {
+ appendMetric(ctx.vault, {
+ surface: "communities",
+ runAt: isoSecond(now),
+ payload: {
+ communities: communities.length,
+ sizes: communities.map((c) => c.size),
+ written: materialized.written.length,
+ removed: materialized.removed.length,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ return {
+ communities: communities.map((c) => ({
+ id: c.id,
+ size: c.size,
+ density: c.density,
+ members: c.members.map((m) => m.path),
+ })),
+ written: materialized.written,
+ removed: materialized.removed,
+ };
+ } finally {
+ await store.close();
+ }
+}
+
+// ----- brain_benchmark (t_e2215d49) -------------------------------------------
+
+/** Recall-quality benchmark over an inline dataset. */
+async function toolBrainBenchmark(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const op = args["operation"];
+ if (op !== "run") {
+ throw new MCPError(INVALID_PARAMS, "brain_benchmark: operation must be run");
+ }
+ const k = args["k"];
+ if (k !== undefined && (!Number.isInteger(k) || (k as number) < 1)) {
+ throw new MCPError(INVALID_PARAMS, "brain_benchmark run: k must be a positive integer");
+ }
+ let dataset;
+ try {
+ dataset = parseRecallBenchmarkDataset(args["dataset"]);
+ } catch (exc) {
+ throw new MCPError(INVALID_PARAMS, `brain_benchmark run: ${(exc as Error).message}`);
+ }
+ const searchConfig = resolveSearchConfig({
+ vault: ctx.vault,
+ configPath: ctx.configPath ?? undefined,
+ });
+ const now = new Date();
+ const report = await runRecallBenchmark(searchConfig, dataset, {
+ ...(k !== undefined ? { k: k as number } : {}),
+ expand: args["expand"] === true,
+ });
+ try {
+ appendMetric(ctx.vault, {
+ surface: "recall_benchmark",
+ runAt: isoSecond(now),
+ payload: {
+ total: report.total,
+ k: report.k,
+ expand: report.expand,
+ hit_at_k: report.hitAtK,
+ mrr: report.mrr,
+ misses: report.perQuery.filter((q) => !q.hit).map((q) => q.id),
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ return {
+ total: report.total,
+ k: report.k,
+ expand: report.expand,
+ hit_at_k: report.hitAtK,
+ mrr: report.mrr,
+ per_query: report.perQuery,
+ };
+}
+
+// ----- brain_tune (t_ae973491) -------------------------------------------------
+
+/** Opt-in self-tuning recall: run the grid, inspect, or reset. */
+async function toolBrainTune(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const op = args["operation"];
+ if (op !== "run" && op !== "status" && op !== "reset") {
+ throw new MCPError(INVALID_PARAMS, "brain_tune: operation must be run|status|reset");
+ }
+ const searchConfig = resolveSearchConfig({
+ vault: ctx.vault,
+ configPath: ctx.configPath ?? undefined,
+ });
+ if (op === "status") {
+ return {
+ enabled: searchConfig.recall.selfTuningEnabled,
+ tuned: loadTunedParameters(ctx.vault),
+ };
+ }
+ if (op === "reset") {
+ return { removed: resetTuning(ctx.vault) };
+ }
+ const k = args["k"];
+ if (k !== undefined && (!Number.isInteger(k) || (k as number) < 1)) {
+ throw new MCPError(INVALID_PARAMS, "brain_tune run: k must be a positive integer");
+ }
+ let dataset;
+ try {
+ dataset = parseRecallBenchmarkDataset(args["dataset"]);
+ } catch (exc) {
+ throw new MCPError(INVALID_PARAMS, `brain_tune run: ${(exc as Error).message}`);
+ }
+ const now = new Date();
+ const report = await tuneRecall(searchConfig, dataset, {
+ ...(k !== undefined ? { k: k as number } : {}),
+ now,
+ });
+ try {
+ appendMetric(ctx.vault, {
+ surface: "self_tuning",
+ runAt: isoSecond(now),
+ payload: {
+ chosen: report.chosen,
+ evaluated: report.evaluated.length,
+ best_mrr: Math.max(...report.evaluated.map((e) => e.mrr)),
+ dataset_hash: report.datasetHash,
+ },
+ });
+ } catch {
+ // Metrics are observability, not correctness.
+ }
+ return {
+ chosen: report.chosen,
+ evaluated: report.evaluated.map((e) => ({ params: e.params, mrr: e.mrr, hit_at_k: e.hitAtK })),
+ dataset_hash: report.datasetHash,
+ };
+}
+
// ----- brain_dead_ends (t_be62c62d) -----------------------------------------
/**
@@ -4728,7 +5114,7 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_maintenance",
description:
- "Quiet-window, lease-guarded heavy maintenance lane: run executes dream + reindex stale-first behind the local-time window, recall-telemetry busy gate, and an expiring lease (force bypasses the soft gates, never the lease); status renders the lease holder and recent journal.",
+ "Quiet-window, lease-guarded heavy maintenance lane: run executes dream, reindex, bridges, and clusters stale-first behind the local-time window, busy gate, and an expiring lease (force bypasses the soft gates, never the lease); status renders the lease holder and recent journal.",
inputSchema: {
type: "object",
properties: {
@@ -4755,6 +5141,96 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
handler: toolBrainMaintenance,
previewBudget: MCP_PREVIEW_BUDGET,
},
+ {
+ name: "brain_bridges",
+ description:
+ "Bridge discovery over the vec index: discover proposes links between embedding-near notes that share no edge (orphan-first, regenerates Brain/proposals/bridges.md, records a metric); accept writes one related wikilink into the source note; dismiss silences a pair; list reads the artifact back.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: {
+ type: "string",
+ enum: ["discover", "list", "accept", "dismiss"],
+ description: "Tool operation.",
+ },
+ source: { type: "string", description: "Vault-relative source note (accept/dismiss)." },
+ target: { type: "string", description: "Vault-relative target note (accept/dismiss)." },
+ max: { type: "integer", minimum: 1, description: "Proposal cap (discover)." },
+ min_similarity: {
+ type: "number",
+ exclusiveMinimum: 0,
+ maximum: 1,
+ description: "Cosine similarity threshold (discover, default 0.8).",
+ },
+ },
+ required: ["operation"],
+ additionalProperties: false,
+ },
+ handler: toolBrainBridges,
+ previewBudget: MCP_PREVIEW_BUDGET,
+ },
+ {
+ name: "brain_clusters",
+ description:
+ "Graph-wide community detection: run applies deterministic label propagation over the resolved link graph, materializes one derived note per community of size >= min_size under Brain/clusters/, removes stale generated notes, and records a metric; list reads the generated notes back.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: { type: "string", enum: ["run", "list"], description: "Tool operation." },
+ min_size: {
+ type: "integer",
+ minimum: 2,
+ description: "Smallest community that materializes (run, default 4).",
+ },
+ },
+ required: ["operation"],
+ additionalProperties: false,
+ },
+ handler: toolBrainClusters,
+ previewBudget: MCP_PREVIEW_BUDGET,
+ },
+ {
+ name: "brain_benchmark",
+ description:
+ "Recall-quality benchmark: score the vault's live hybrid recall against a fixed dataset ({queries: [{id, query, expected: [paths]}]}) - hit@k and MRR per query and aggregate - and record one recall_benchmark metric so quality is chartable over time.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: { type: "string", enum: ["run"], description: "Tool operation." },
+ dataset: {
+ type: "object",
+ description: "Benchmark dataset: {queries: [{id, query, expected, k?}]}.",
+ },
+ k: { type: "integer", minimum: 1, description: "Rank depth (default 5)." },
+ expand: { type: "boolean", description: "Route queries through deterministic expansion." },
+ },
+ required: ["operation", "dataset"],
+ additionalProperties: false,
+ },
+ handler: toolBrainBenchmark,
+ previewBudget: MCP_PREVIEW_BUDGET,
+ },
+ {
+ name: "brain_tune",
+ description:
+ "Opt-in self-tuning recall: run grid-evaluates bounded parameters (pool multiplier, traversal depth, learned weights, expansion) against a benchmark dataset and persists the winner to Brain/search/tuning.json; status shows the validated state; reset deletes it. Search honors it only when enabled.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ operation: {
+ type: "string",
+ enum: ["run", "status", "reset"],
+ description: "Tool operation.",
+ },
+ dataset: { type: "object", description: "Benchmark dataset (run)." },
+ k: { type: "integer", minimum: 1, description: "Rank depth (run, default 5)." },
+ },
+ required: ["operation"],
+ additionalProperties: false,
+ },
+ handler: toolBrainTune,
+ previewBudget: MCP_PREVIEW_BUDGET,
+ },
{
name: "brain_procedural_graph",
description:
diff --git a/tests/cli/brain-benchmark.test.ts b/tests/cli/brain-benchmark.test.ts
new file mode 100644
index 00000000..54d8b82f
--- /dev/null
+++ b/tests/cli/brain-benchmark.test.ts
@@ -0,0 +1,130 @@
+/**
+ * `o2b brain benchmark` + `o2b brain tune` CLI surfaces
+ * (t_e2215d49 / t_ae973491): benchmark scores a dataset and records
+ * the recall_benchmark metric; tune runs the grid, persists, reports
+ * status, and resets; search --expand reaches the expansion path.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { indexVault } from "../../src/core/search/indexer.ts";
+import { listMetrics } from "../../src/core/brain/metrics.ts";
+import { makeConfig } from "../helpers/search-fixtures.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let datasetPath: string;
+
+beforeEach(async () => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-cli-bench-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ writeFileSync(
+ join(vault, "canary.md"),
+ "# Canary rollout\n\nShip one instance first, observe, expand gradually.\n",
+ );
+ writeFileSync(join(vault, "other.md"), "# Other\n\nNothing relevant whatsoever.\n");
+ datasetPath = join(tmp, "dataset.json");
+ writeFileSync(
+ datasetPath,
+ JSON.stringify({
+ queries: [{ id: "canary", query: "canary rollout", expected: ["canary.md"] }],
+ }),
+ );
+ await indexVault(
+ makeConfig({ vault, dbPath: join(vault, ".open-second-brain", "brain.sqlite") }),
+ );
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+test("benchmark run scores the dataset and records the metric", async () => {
+ const r = await runCli([
+ "brain",
+ "benchmark",
+ "run",
+ "--dataset",
+ datasetPath,
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(r.returncode).toBe(0);
+ const parsed = JSON.parse(r.stdout) as { total: number; hit_at_k: number; mrr: number };
+ expect(parsed.total).toBe(1);
+ expect(parsed.hit_at_k).toBe(1);
+ expect(parsed.mrr).toBe(1);
+
+ const metrics = listMetrics(vault, { surface: "recall_benchmark" });
+ expect(metrics).toHaveLength(1);
+ expect(metrics[0]!.payload).toMatchObject({ total: 1, hit_at_k: 1 });
+});
+
+test("benchmark usage and dataset validation exit 2", async () => {
+ const noDataset = await runCli(["brain", "benchmark", "run", "--vault", vault]);
+ expect(noDataset.returncode).toBe(2);
+
+ const badPath = join(tmp, "bad.json");
+ writeFileSync(badPath, JSON.stringify({ queries: [] }));
+ const bad = await runCli(["brain", "benchmark", "run", "--dataset", badPath, "--vault", vault]);
+ expect(bad.returncode).toBe(2);
+});
+
+test("tune run -> status -> reset lifecycle with the self_tuning metric", async () => {
+ const run = await runCli([
+ "brain",
+ "tune",
+ "run",
+ "--dataset",
+ datasetPath,
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(run.returncode).toBe(0);
+ const ran = JSON.parse(run.stdout) as {
+ chosen: { poolMultiplier: number };
+ evaluated: unknown[];
+ };
+ expect(ran.evaluated).toHaveLength(24);
+ expect([3, 4, 5]).toContain(ran.chosen.poolMultiplier);
+ expect(existsSync(join(vault, "Brain", "search", "tuning.json"))).toBe(true);
+ expect(listMetrics(vault, { surface: "self_tuning" })).toHaveLength(1);
+
+ const status = await runCli(["brain", "tune", "status", "--vault", vault, "--json"]);
+ const state = JSON.parse(status.stdout) as { enabled: boolean; tuned: unknown };
+ expect(state.enabled).toBe(false);
+ expect(state.tuned).not.toBeNull();
+
+ const reset = await runCli(["brain", "tune", "reset", "--vault", vault, "--json"]);
+ expect(JSON.parse(reset.stdout)).toMatchObject({ removed: true });
+ const statusAfter = await runCli(["brain", "tune", "status", "--vault", vault, "--json"]);
+ expect((JSON.parse(statusAfter.stdout) as { tuned: unknown }).tuned).toBeNull();
+});
+
+test("tune run without a dataset exits 2", async () => {
+ const r = await runCli(["brain", "tune", "run", "--vault", vault]);
+ expect(r.returncode).toBe(2);
+});
+
+test("search --expand recovers the stopword-blocked hit", async () => {
+ // "the" appears nowhere in canary.md, so the implicit-AND lane misses.
+ const plain = await runCli(["search", "the canary rollout", "--vault", vault, "--json"]);
+ expect(JSON.parse(plain.stdout).results).toHaveLength(0);
+ const expanded = await runCli([
+ "search",
+ "the canary rollout",
+ "--expand",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ const results = JSON.parse(expanded.stdout).results as Array<{ path: string }>;
+ expect(results.some((r) => r.path === "canary.md")).toBe(true);
+});
diff --git a/tests/cli/brain-bridges.test.ts b/tests/cli/brain-bridges.test.ts
new file mode 100644
index 00000000..db990ec9
--- /dev/null
+++ b/tests/cli/brain-bridges.test.ts
@@ -0,0 +1,139 @@
+/**
+ * `o2b brain bridges` CLI surface (t_ab540afe): discover regenerates
+ * the proposals artifact and records the bridge_discovery metric;
+ * accept/dismiss manage one pair; list reads the artifact back.
+ * Fail-soft paths (no index, no embeddings) exit 0 with a reason.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { indexVault } from "../../src/core/search/indexer.ts";
+import { listMetrics } from "../../src/core/brain/metrics.ts";
+import { makeConfig } from "../helpers/search-fixtures.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-cli-bridges-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ writeFileSync(join(vault, "a-note.md"), "# A note\n\nCanary deployment content here.\n");
+ writeFileSync(join(vault, "b-note.md"), "# B note\n\nUnrelated content entirely.\n");
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+async function indexWithoutEmbeddings(): Promise<void> {
+ const config = makeConfig({
+ vault,
+ dbPath: join(vault, ".open-second-brain", "brain.sqlite"),
+ });
+ await indexVault(config);
+}
+
+test("discover on an unindexed vault exits 0 with a reason", async () => {
+ const r = await runCli(["brain", "bridges", "discover", "--vault", vault, "--json"]);
+ expect(r.returncode).toBe(0);
+ const parsed = JSON.parse(r.stdout) as { vec_available: boolean; reason: string };
+ expect(parsed.vec_available).toBe(false);
+ expect(parsed.reason).toContain("index");
+});
+
+test("discover without embeddings writes the artifact, metric, and exits 0", async () => {
+ await indexWithoutEmbeddings();
+ const r = await runCli(["brain", "bridges", "discover", "--vault", vault, "--json"]);
+ expect(r.returncode).toBe(0);
+ const parsed = JSON.parse(r.stdout) as { vec_available: boolean; proposals: unknown[] };
+ expect(parsed.vec_available).toBe(false);
+ expect(parsed.proposals).toEqual([]);
+ expect(existsSync(join(vault, "Brain", "proposals", "bridges.md"))).toBe(true);
+ const metrics = listMetrics(vault, { surface: "bridge_discovery" });
+ expect(metrics).toHaveLength(1);
+ expect(metrics[0]!.payload["vec_available"]).toBe(false);
+});
+
+test("list before and after discover", async () => {
+ const before = await runCli(["brain", "bridges", "list", "--vault", vault, "--json"]);
+ expect(JSON.parse(before.stdout)).toMatchObject({ exists: false });
+
+ await indexWithoutEmbeddings();
+ await runCli(["brain", "bridges", "discover", "--vault", vault]);
+ const after = await runCli(["brain", "bridges", "list", "--vault", vault, "--json"]);
+ const parsed = JSON.parse(after.stdout) as { exists: boolean; proposals: number };
+ expect(parsed.exists).toBe(true);
+ expect(parsed.proposals).toBe(0);
+});
+
+test("accept writes related into the source and is idempotent", async () => {
+ const first = await runCli([
+ "brain",
+ "bridges",
+ "accept",
+ "a-note.md",
+ "b-note.md",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(first.returncode).toBe(0);
+ expect(JSON.parse(first.stdout)).toMatchObject({ changed: true, related: ["[[b-note]]"] });
+
+ const again = await runCli([
+ "brain",
+ "bridges",
+ "accept",
+ "a-note.md",
+ "b-note.md",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(JSON.parse(again.stdout)).toMatchObject({ changed: false });
+});
+
+test("dismiss persists and reports repeats", async () => {
+ const first = await runCli([
+ "brain",
+ "bridges",
+ "dismiss",
+ "a-note.md",
+ "b-note.md",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(JSON.parse(first.stdout)).toMatchObject({ added: true });
+ const again = await runCli([
+ "brain",
+ "bridges",
+ "dismiss",
+ "b-note.md",
+ "a-note.md",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(JSON.parse(again.stdout)).toMatchObject({ added: false });
+});
+
+test("usage errors exit 2", async () => {
+ const r = await runCli(["brain", "bridges", "accept", "only-one.md", "--vault", vault]);
+ expect(r.returncode).toBe(2);
+ const bad = await runCli([
+ "brain",
+ "bridges",
+ "discover",
+ "--min-similarity",
+ "5",
+ "--vault",
+ vault,
+ ]);
+ expect(bad.returncode).toBe(2);
+});
diff --git a/tests/cli/brain-clusters.test.ts b/tests/cli/brain-clusters.test.ts
new file mode 100644
index 00000000..e5617d02
--- /dev/null
+++ b/tests/cli/brain-clusters.test.ts
@@ -0,0 +1,114 @@
+/**
+ * `o2b brain clusters` CLI surface (t_4ba927ec): run detects
+ * communities, materializes derived notes, records the communities
+ * metric; list reads them back; the maintenance lane executes the
+ * bridges and clusters tasks under its lease.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { indexVault } from "../../src/core/search/indexer.ts";
+import { listMetrics } from "../../src/core/brain/metrics.ts";
+import { makeConfig } from "../helpers/search-fixtures.ts";
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-cli-clusters-"));
+ vault = join(tmp, "vault");
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ const group = ["team-a", "team-b", "team-c", "team-d"];
+ for (const name of group) {
+ const others = group
+ .filter((g) => g !== name)
+ .map((g) => `[[${g}]]`)
+ .join(" ");
+ writeFileSync(join(vault, `${name}.md`), `# ${name}\n\nSee ${others}.\n`);
+ }
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+async function index(): Promise<void> {
+ await indexVault(
+ makeConfig({ vault, dbPath: join(vault, ".open-second-brain", "brain.sqlite") }),
+ );
+}
+
+test("run on an unindexed vault exits 0 with a reason", async () => {
+ const r = await runCli(["brain", "clusters", "run", "--vault", vault, "--json"]);
+ expect(r.returncode).toBe(0);
+ expect(JSON.parse(r.stdout)).toMatchObject({ communities: 0, reason: "index not built" });
+});
+
+test("run materializes the community, records the metric, list reads it back", async () => {
+ await index();
+ const run = await runCli(["brain", "clusters", "run", "--vault", vault, "--json"]);
+ expect(run.returncode).toBe(0);
+ const parsed = JSON.parse(run.stdout) as {
+ communities: Array<{ id: string; size: number }>;
+ written: string[];
+ };
+ expect(parsed.communities).toHaveLength(1);
+ expect(parsed.communities[0]!.size).toBe(4);
+ expect(parsed.written).toHaveLength(1);
+
+ const metrics = listMetrics(vault, { surface: "communities" });
+ expect(metrics).toHaveLength(1);
+ expect(metrics[0]!.payload).toMatchObject({ communities: 1, written: 1 });
+
+ const list = await runCli(["brain", "clusters", "list", "--vault", vault, "--json"]);
+ const listed = JSON.parse(list.stdout) as { clusters: Array<{ size: number }> };
+ expect(listed.clusters).toHaveLength(1);
+ expect(listed.clusters[0]!.size).toBe(4);
+});
+
+test("min-size above the community suppresses it", async () => {
+ await index();
+ const run = await runCli([
+ "brain",
+ "clusters",
+ "run",
+ "--min-size",
+ "5",
+ "--vault",
+ vault,
+ "--json",
+ ]);
+ expect(JSON.parse(run.stdout)).toMatchObject({ communities: [] });
+});
+
+test("maintenance lane executes the bridges and clusters tasks", async () => {
+ // dream needs an initialised Brain config.
+ const configPath = join(tmp, "config.yaml");
+ writeFileSync(configPath, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath });
+ const r = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"]);
+ expect(r.returncode).toBe(0);
+ const parsed = JSON.parse(r.stdout) as {
+ verdict: string;
+ tasks: Array<{ name: string; ok: boolean }>;
+ };
+ expect(parsed.verdict).toBe("run");
+ const names = parsed.tasks.map((t) => t.name);
+ expect(names).toEqual(["dream", "reindex", "bridges", "clusters"]);
+ expect(parsed.tasks.every((t) => t.ok)).toBe(true);
+ // The lane's reindex built the index, so both passes left a metric.
+ expect(listMetrics(vault, { surface: "bridge_discovery" })).toHaveLength(1);
+ expect(listMetrics(vault, { surface: "communities" })).toHaveLength(1);
+});
+
+test("usage errors exit 2", async () => {
+ const r = await runCli(["brain", "clusters", "nope", "--vault", vault]);
+ expect(r.returncode).toBe(2);
+ const bad = await runCli(["brain", "clusters", "run", "--min-size", "0", "--vault", vault]);
+ expect(bad.returncode).toBe(2);
+});
diff --git a/tests/cli/brain-maintenance.test.ts b/tests/cli/brain-maintenance.test.ts
index 3cc41308..ab20b9b2 100644
--- a/tests/cli/brain-maintenance.test.ts
+++ b/tests/cli/brain-maintenance.test.ts
@@ -42,7 +42,12 @@ test("run executes dream and reindex; status shows the journal", async () => {
tasks: Array<{ name: string; ok: boolean }>;
};
expect(ran.verdict).toBe("run");
- expect(ran.tasks.map((t) => t.name).toSorted()).toEqual(["dream", "reindex"]);
+ expect(ran.tasks.map((t) => t.name).toSorted()).toEqual([
+ "bridges",
+ "clusters",
+ "dream",
+ "reindex",
+ ]);
expect(ran.tasks.every((t) => t.ok)).toBe(true);
expect(existsSync(join(vault, ".open-second-brain", "maintenance-runs.jsonl"))).toBe(true);
diff --git a/tests/core/brain/bridge-discovery.test.ts b/tests/core/brain/bridge-discovery.test.ts
new file mode 100644
index 00000000..d60fd6a8
--- /dev/null
+++ b/tests/core/brain/bridge-discovery.test.ts
@@ -0,0 +1,207 @@
+/**
+ * Bridge discovery (link-recall-intelligence, t_ab540afe): an
+ * orphan-first pass over the vec index proposing links between
+ * embedding-near notes that share NO existing edge - reviewable
+ * proposal artifact, persistent dismissals, operator-initiated accept
+ * that writes one `related:` wikilink into the source frontmatter.
+ * Read-only against note bodies; fail-soft without a vec layer.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ acceptBridge,
+ bridgePairKey,
+ discoverBridges,
+ dismissBridge,
+ readDismissedBridges,
+ writeBridgeProposals,
+} from "../../../src/core/brain/link-graph/bridge-discovery.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { Store } from "../../../src/core/search/store.ts";
+import { parseFrontmatter } from "../../../src/core/vault.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+
+const NOW = new Date("2026-06-05T12:00:00Z");
+
+let vault: string;
+let config: ResolvedSearchConfig;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-bridge-"));
+ config = makeConfig({
+ vault,
+ dbPath: join(vault, "index.sqlite"),
+ semantic: { enabled: true, provider: "local", dimension: 256 },
+ });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+/** Two notes about the same topic that never name each other. */
+function writeTwinNotes(): void {
+ writeFileSync(
+ join(vault, "alpha-deploy.md"),
+ "# Canary deployment runbook\n\nShip the canary release to one production instance, watch error rates, expand the deployment gradually, roll back on regression.\n",
+ );
+ writeFileSync(
+ join(vault, "beta-deploy.md"),
+ "# Deployment safety checklist\n\nCanary release first: one production instance, watch error rates, expand deployment gradually, roll back the release on regression.\n",
+ );
+ writeFileSync(
+ join(vault, "borscht.md"),
+ "# Borscht\n\nBeets, cabbage, carrots, dill, sour cream. Simmer slowly until tender.\n",
+ );
+}
+
+async function withStore<T>(fn: (store: Store) => T | Promise<T>): Promise<T> {
+ const store = await Store.open(config, { mode: "read" });
+ try {
+ return await fn(store);
+ } finally {
+ await store.close();
+ }
+}
+
+describe("discoverBridges", () => {
+ test("proposes the embedding-near unlinked pair and skips the distractor", async () => {
+ writeTwinNotes();
+ await indexVault(config, { embeddings: true });
+ const report = await withStore((store) => discoverBridges(store, { minSimilarity: 0.5 }));
+ expect(report.vecAvailable).toBe(true);
+ expect(report.proposals.length).toBeGreaterThanOrEqual(1);
+ const pair = report.proposals[0]!;
+ expect([pair.source, pair.target].toSorted()).toEqual(["alpha-deploy.md", "beta-deploy.md"]);
+ expect(pair.similarity).toBeGreaterThan(0.5);
+ expect(
+ report.proposals.some((p) => p.source === "borscht.md" || p.target === "borscht.md"),
+ ).toBe(false);
+ });
+
+ test("an existing edge in either direction suppresses the pair", async () => {
+ writeTwinNotes();
+ writeFileSync(
+ join(vault, "alpha-deploy.md"),
+ "# Canary deployment runbook\n\nSee [[beta-deploy]]. Ship the canary release to one production instance, watch error rates, expand the deployment gradually, roll back on regression.\n",
+ );
+ await indexVault(config, { embeddings: true });
+ const report = await withStore((store) => discoverBridges(store, { minSimilarity: 0.5 }));
+ expect(
+ report.proposals.some(
+ (p) =>
+ bridgePairKey(p.source, p.target) === bridgePairKey("alpha-deploy.md", "beta-deploy.md"),
+ ),
+ ).toBe(false);
+ });
+
+ test("dismissed pairs stay out of the report", async () => {
+ writeTwinNotes();
+ await indexVault(config, { embeddings: true });
+ const dismissed = new Set([bridgePairKey("alpha-deploy.md", "beta-deploy.md")]);
+ const report = await withStore((store) =>
+ discoverBridges(store, { minSimilarity: 0.5, dismissed }),
+ );
+ expect(
+ report.proposals.some(
+ (p) =>
+ bridgePairKey(p.source, p.target) === bridgePairKey("alpha-deploy.md", "beta-deploy.md"),
+ ),
+ ).toBe(false);
+ });
+
+ test("a vault indexed without embeddings fails soft with a reason", async () => {
+ writeTwinNotes();
+ await indexVault(config);
+ const report = await withStore((store) => discoverBridges(store, {}));
+ expect(report.vecAvailable).toBe(false);
+ expect(report.proposals).toEqual([]);
+ expect(report.reason).toMatch(/embedding|vec/i);
+ });
+
+ test("the similarity threshold filters weak pairs", async () => {
+ writeTwinNotes();
+ await indexVault(config, { embeddings: true });
+ const strict = await withStore((store) => discoverBridges(store, { minSimilarity: 0.999 }));
+ expect(strict.proposals).toEqual([]);
+ });
+});
+
+describe("proposal artifact + dismiss state", () => {
+ test("writeBridgeProposals regenerates a marked markdown artifact", async () => {
+ writeTwinNotes();
+ await indexVault(config, { embeddings: true });
+ const report = await withStore((store) => discoverBridges(store, { minSimilarity: 0.5 }));
+ const path = writeBridgeProposals(vault, report, { now: NOW });
+ expect(path).toBe(join(vault, "Brain", "proposals", "bridges.md"));
+ const [fm, body] = parseFrontmatter(path);
+ expect(fm["kind"]).toBe("brain-bridge-proposals");
+ expect(fm["generated_at"]).toBe("2026-06-05T12:00:00Z");
+ expect(body).toContain("alpha-deploy.md");
+ expect(body).toContain("beta-deploy.md");
+
+ const empty = writeBridgeProposals(
+ vault,
+ { proposals: [], scannedCandidates: 0, vecAvailable: true },
+ { now: NOW },
+ );
+ expect(readFileSync(empty, "utf8")).toContain("No bridge proposals");
+ });
+
+ test("dismissBridge persists across runs and readDismissedBridges round-trips", () => {
+ expect(readDismissedBridges(vault).size).toBe(0);
+ dismissBridge(vault, "a.md", "b.md");
+ dismissBridge(vault, "b.md", "a.md"); // unordered - same pair
+ const dismissed = readDismissedBridges(vault);
+ expect(dismissed.size).toBe(1);
+ expect(dismissed.has(bridgePairKey("a.md", "b.md"))).toBe(true);
+ });
+});
+
+describe("acceptBridge", () => {
+ test("writes one related wikilink into the source frontmatter, idempotently", async () => {
+ writeTwinNotes();
+ await indexVault(config, { embeddings: true });
+ const first = acceptBridge(vault, "alpha-deploy.md", "beta-deploy.md");
+ expect(first.changed).toBe(true);
+ const [fm, body] = parseFrontmatter(join(vault, "alpha-deploy.md"));
+ expect(fm["related"]).toEqual("[[beta-deploy]]");
+ expect(body).toContain("Canary deployment runbook");
+
+ const again = acceptBridge(vault, "alpha-deploy.md", "beta-deploy.md");
+ expect(again.changed).toBe(false);
+ });
+
+ test("appends to an existing related list without clobbering", async () => {
+ writeFileSync(join(vault, "src.md"), '---\nrelated: "[[existing]]"\n---\n\n# Src\n\nBody.\n');
+ writeFileSync(join(vault, "tgt.md"), "# Tgt\n\nBody.\n");
+ const result = acceptBridge(vault, "src.md", "tgt.md");
+ expect(result.changed).toBe(true);
+ const [fm] = parseFrontmatter(join(vault, "src.md"));
+ expect(fm["related"]).toEqual(["[[existing]]", "[[tgt]]"]);
+ });
+
+ test("an ambiguous target basename keeps the full path in the wikilink", async () => {
+ mkdirSync(join(vault, "a-dir"), { recursive: true });
+ mkdirSync(join(vault, "b-dir"), { recursive: true });
+ writeFileSync(join(vault, "a-dir", "topic.md"), "# Topic A\n\nBody.\n");
+ writeFileSync(join(vault, "b-dir", "topic.md"), "# Topic B\n\nBody.\n");
+ writeFileSync(join(vault, "src.md"), "# Src\n\nBody.\n");
+ const result = acceptBridge(vault, "src.md", "a-dir/topic.md");
+ expect(result.changed).toBe(true);
+ const [fm] = parseFrontmatter(join(vault, "src.md"));
+ expect(fm["related"]).toEqual("[[a-dir/topic]]");
+ // Re-accept of the same pair stays idempotent on the full form.
+ expect(acceptBridge(vault, "src.md", "a-dir/topic.md").changed).toBe(false);
+ });
+
+ test("refuses paths outside the vault and missing notes", () => {
+ expect(() => acceptBridge(vault, "../escape.md", "x.md")).toThrow(/outside the vault/);
+ expect(() => acceptBridge(vault, "ghost.md", "also-ghost.md")).toThrow(/does not exist/);
+ });
+});
diff --git a/tests/core/brain/communities.test.ts b/tests/core/brain/communities.test.ts
new file mode 100644
index 00000000..41c356ec
--- /dev/null
+++ b/tests/core/brain/communities.test.ts
@@ -0,0 +1,184 @@
+/**
+ * Community detection + cluster note materialization
+ * (link-recall-intelligence, t_4ba927ec): deterministic synchronous
+ * label propagation over the resolved doc-level link graph; every
+ * community of size >= minSize materializes one derived cluster note
+ * under Brain/clusters/ (regenerated each run, stale notes removed,
+ * non-generated files never touched). No LLM prose - the digest is a
+ * deterministic projection.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ detectCommunities,
+ materializeClusterNotes,
+} from "../../../src/core/brain/link-graph/communities.ts";
+import { DEFAULT_TIER_MAP } from "../../../src/core/brain/frontmatter-tiers.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { Store } from "../../../src/core/search/store.ts";
+import { parseFrontmatter } from "../../../src/core/vault.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+
+const NOW = new Date("2026-06-05T12:00:00Z");
+
+let vault: string;
+let config: ResolvedSearchConfig;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-comm-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ config = makeConfig({ vault, dbPath: join(vault, "index.sqlite") });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+const link = (targets: string[]) => targets.map((t) => `[[${t}]]`).join(" and ");
+
+/** Two 4-cliques (deploy-*, cook-*) and one isolated note. */
+function writeTwoCommunities(): void {
+ const deploy = ["deploy-a", "deploy-b", "deploy-c", "deploy-d"];
+ const cook = ["cook-a", "cook-b", "cook-c", "cook-d"];
+ for (const group of [deploy, cook]) {
+ for (const name of group) {
+ const others = group.filter((g) => g !== name);
+ writeFileSync(
+ join(vault, `${name}.md`),
+ `# ${name}\n\nSee ${link(others)} for the rest of the series.\n`,
+ );
+ }
+ }
+ writeFileSync(join(vault, "loner.md"), "# Loner\n\nNo links here.\n");
+}
+
+async function withStore<T>(fn: (store: Store) => T): Promise<T> {
+ const store = await Store.open(config, { mode: "read" });
+ try {
+ return fn(store);
+ } finally {
+ await store.close();
+ }
+}
+
+describe("detectCommunities", () => {
+ test("finds the two seeded communities deterministically", async () => {
+ writeTwoCommunities();
+ await indexVault(config);
+ const first = await withStore((store) => detectCommunities(store, { minSize: 4 }));
+ const second = await withStore((store) => detectCommunities(store, { minSize: 4 }));
+ expect(first).toEqual(second);
+ expect(first).toHaveLength(2);
+ const memberSets = first.map((c) => c.members.map((m) => m.path).toSorted());
+ expect(memberSets).toContainEqual(["cook-a.md", "cook-b.md", "cook-c.md", "cook-d.md"]);
+ expect(memberSets).toContainEqual(["deploy-a.md", "deploy-b.md", "deploy-c.md", "deploy-d.md"]);
+ // Most-central member leads (full clique - degree ties break by path).
+ expect(first[0]!.members[0]!.internalDegree).toBeGreaterThanOrEqual(
+ first[0]!.members.at(-1)!.internalDegree,
+ );
+ });
+
+ test("communities below minSize are ignored", async () => {
+ writeFileSync(join(vault, "pair-a.md"), "# Pair A\n\nSee [[pair-b]].\n");
+ writeFileSync(join(vault, "pair-b.md"), "# Pair B\n\nSee [[pair-a]].\n");
+ await indexVault(config);
+ const communities = await withStore((store) => detectCommunities(store, { minSize: 4 }));
+ expect(communities).toEqual([]);
+ });
+
+ test("a bipartite star terminates within the iteration cap", async () => {
+ // Hub-and-spokes: synchronous propagation oscillates without a cap.
+ writeFileSync(
+ join(vault, "hub.md"),
+ "# Hub\n\n[[spoke-a]] [[spoke-b]] [[spoke-c]] [[spoke-d]]\n",
+ );
+ for (const s of ["spoke-a", "spoke-b", "spoke-c", "spoke-d"]) {
+ writeFileSync(join(vault, `${s}.md`), `# ${s}\n\nBack to [[hub]].\n`);
+ }
+ await indexVault(config);
+ const communities = await withStore((store) => detectCommunities(store, { minSize: 4 }));
+ expect(communities.length).toBeLessThanOrEqual(1);
+ });
+});
+
+test("two communities led by same-named hubs in different folders keep distinct ids", async () => {
+ mkdirSync(join(vault, "alpha"), { recursive: true });
+ mkdirSync(join(vault, "beta"), { recursive: true });
+ for (const dir of ["alpha", "beta"]) {
+ const group = ["topic", "x", "y", "z"];
+ for (const name of group) {
+ const others = group
+ .filter((g) => g !== name)
+ .map((g) => `[[${dir}/${g}]]`)
+ .join(" ");
+ writeFileSync(join(vault, dir, `${name}.md`), `# ${dir}/${name}\n\nSee ${others}.\n`);
+ }
+ }
+ await indexVault(config);
+ const communities = await withStore((store) => detectCommunities(store, { minSize: 4 }));
+ expect(communities).toHaveLength(2);
+ const ids = communities.map((c) => c.id).toSorted();
+ expect(new Set(ids).size).toBe(2);
+ const result = await withStore((store) =>
+ materializeClusterNotes(vault, communities, { store, now: NOW }),
+ );
+ expect(result.written).toHaveLength(2);
+ expect(new Set(result.written).size).toBe(2);
+});
+
+describe("materializeClusterNotes", () => {
+ test("writes one derived note per community and registers the tier kind", async () => {
+ writeTwoCommunities();
+ await indexVault(config);
+ const communities = await withStore((store) => detectCommunities(store, { minSize: 4 }));
+ const result = await withStore((store) =>
+ materializeClusterNotes(vault, communities, { store, now: NOW }),
+ );
+ expect(result.written).toHaveLength(2);
+ expect(result.removed).toEqual([]);
+
+ const dir = join(vault, "Brain", "clusters");
+ const files = readdirSync(dir).toSorted();
+ expect(files).toHaveLength(2);
+ const [fm, body] = parseFrontmatter(join(dir, files[0]!));
+ expect(fm["kind"]).toBe("brain-cluster");
+ expect(fm["generated_at"]).toBe("2026-06-05T12:00:00Z");
+ expect(Number(fm["size"])).toBeGreaterThanOrEqual(4);
+ expect(body).toContain("Auto-generated");
+ expect(DEFAULT_TIER_MAP["brain-cluster"]).toBeDefined();
+ });
+
+ test("a vanished community's note is removed on the next run", async () => {
+ writeTwoCommunities();
+ await indexVault(config);
+ const communities = await withStore((store) => detectCommunities(store, { minSize: 4 }));
+ await withStore((store) => materializeClusterNotes(vault, communities, { store, now: NOW }));
+
+ const onlyFirst = communities.slice(0, 1);
+ const second = await withStore((store) =>
+ materializeClusterNotes(vault, onlyFirst, { store, now: NOW }),
+ );
+ expect(second.removed).toHaveLength(1);
+ expect(readdirSync(join(vault, "Brain", "clusters"))).toHaveLength(1);
+ });
+
+ test("non-generated files in Brain/clusters/ are never touched", async () => {
+ writeTwoCommunities();
+ await indexVault(config);
+ mkdirSync(join(vault, "Brain", "clusters"), { recursive: true });
+ writeFileSync(
+ join(vault, "Brain", "clusters", "hand-written.md"),
+ "# My own cluster analysis\n\nDo not delete.\n",
+ );
+ const second = await withStore((store) =>
+ materializeClusterNotes(vault, [], { store, now: NOW }),
+ );
+ expect(second.removed).toEqual([]);
+ expect(existsSync(join(vault, "Brain", "clusters", "hand-written.md"))).toBe(true);
+ });
+});
diff --git a/tests/core/brain/metrics.test.ts b/tests/core/brain/metrics.test.ts
new file mode 100644
index 00000000..39e5e74c
--- /dev/null
+++ b/tests/core/brain/metrics.test.ts
@@ -0,0 +1,125 @@
+/**
+ * Dashboard-ready metrics sink (link-recall-intelligence, Task 1):
+ * one append-only schema-versioned JSONL file per surface under
+ * `Brain/metrics/`, the stable on-disk contract a dashboard plugin
+ * reads without importing OSB internals. Envelope mirrors the
+ * continuity-record discipline: additive-optional fields keep the
+ * version, renames/removals bump it.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ appendMetric,
+ listMetrics,
+ METRICS_SCHEMA_VERSION,
+ MetricSurfaceError,
+} from "../../../src/core/brain/metrics.ts";
+
+const NOW = "2026-06-05T10:00:00Z";
+
+let vault: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-metrics-"));
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("appendMetric", () => {
+ test("writes one schema-stamped line per call into the surface file", () => {
+ appendMetric(vault, { surface: "recall_benchmark", runAt: NOW, payload: { mrr: 0.91 } });
+ appendMetric(vault, {
+ surface: "recall_benchmark",
+ runAt: "2026-06-05T11:00:00Z",
+ payload: { mrr: 0.93 },
+ });
+ const raw = readFileSync(join(vault, "Brain", "metrics", "recall_benchmark.jsonl"), "utf8");
+ const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+ expect(lines).toHaveLength(2);
+ expect(JSON.parse(lines[0]!)).toEqual({
+ schema: METRICS_SCHEMA_VERSION,
+ surface: "recall_benchmark",
+ run_at: NOW,
+ payload: { mrr: 0.91 },
+ });
+ });
+
+ test("surfaces are isolated files", () => {
+ appendMetric(vault, { surface: "index", runAt: NOW, payload: { files: 3 } });
+ appendMetric(vault, { surface: "communities", runAt: NOW, payload: { count: 2 } });
+ expect(readFileSync(join(vault, "Brain", "metrics", "index.jsonl"), "utf8")).toContain(
+ '"files":3',
+ );
+ expect(readFileSync(join(vault, "Brain", "metrics", "communities.jsonl"), "utf8")).toContain(
+ '"count":2',
+ );
+ });
+
+ test("rejects surface names outside [a-z][a-z0-9_]*", () => {
+ for (const bad of ["", "Index", "9lives", "a-b", "a b", "a/../b", "x".repeat(65)]) {
+ expect(() => appendMetric(vault, { surface: bad, runAt: NOW, payload: {} })).toThrow(
+ MetricSurfaceError,
+ );
+ }
+ });
+
+ test("rejects a runAt that is not an ISO timestamp", () => {
+ expect(() =>
+ appendMetric(vault, { surface: "index", runAt: "yesterday", payload: {} }),
+ ).toThrow(/run_at/);
+ });
+});
+
+describe("listMetrics", () => {
+ test("missing dir or file reads as empty", () => {
+ expect(listMetrics(vault)).toEqual([]);
+ expect(listMetrics(vault, { surface: "index" })).toEqual([]);
+ });
+
+ test("newest-first per surface with since and limit filters", () => {
+ appendMetric(vault, { surface: "index", runAt: "2026-06-01T00:00:00Z", payload: { n: 1 } });
+ appendMetric(vault, { surface: "index", runAt: "2026-06-03T00:00:00Z", payload: { n: 2 } });
+ appendMetric(vault, { surface: "index", runAt: "2026-06-05T00:00:00Z", payload: { n: 3 } });
+ const all = listMetrics(vault, { surface: "index" });
+ expect(all.map((r) => r.payload["n"])).toEqual([3, 2, 1]);
+ const since = listMetrics(vault, { surface: "index", since: "2026-06-02T00:00:00Z" });
+ expect(since.map((r) => r.payload["n"])).toEqual([3, 2]);
+ const limited = listMetrics(vault, { surface: "index", limit: 1 });
+ expect(limited.map((r) => r.payload["n"])).toEqual([3]);
+ });
+
+ test("without a surface filter, merges every surface newest-first", () => {
+ appendMetric(vault, { surface: "index", runAt: "2026-06-01T00:00:00Z", payload: { n: 1 } });
+ appendMetric(vault, {
+ surface: "bridge_discovery",
+ runAt: "2026-06-04T00:00:00Z",
+ payload: { n: 2 },
+ });
+ appendMetric(vault, { surface: "index", runAt: "2026-06-05T00:00:00Z", payload: { n: 3 } });
+ const all = listMetrics(vault);
+ expect(all.map((r) => r.payload["n"])).toEqual([3, 2, 1]);
+ expect(all.map((r) => r.surface)).toEqual(["index", "bridge_discovery", "index"]);
+ });
+
+ test("a torn or malformed line never breaks the read", () => {
+ appendMetric(vault, { surface: "index", runAt: NOW, payload: { n: 1 } });
+ const path = join(vault, "Brain", "metrics", "index.jsonl");
+ writeFileSync(path, readFileSync(path, "utf8") + "{not json\n[]\n");
+ const records = listMetrics(vault, { surface: "index" });
+ expect(records).toHaveLength(1);
+ expect(records[0]!.payload["n"]).toBe(1);
+ });
+
+ test("ignores non-jsonl files in the metrics dir", () => {
+ mkdirSync(join(vault, "Brain", "metrics"), { recursive: true });
+ writeFileSync(join(vault, "Brain", "metrics", "README.md"), "# not a metric\n");
+ appendMetric(vault, { surface: "index", runAt: NOW, payload: { n: 1 } });
+ expect(listMetrics(vault)).toHaveLength(1);
+ });
+});
diff --git a/tests/core/search/indexer-aliases.test.ts b/tests/core/search/indexer-aliases.test.ts
new file mode 100644
index 00000000..c3918e08
--- /dev/null
+++ b/tests/core/search/indexer-aliases.test.ts
@@ -0,0 +1,110 @@
+/**
+ * Indexer alias extraction (link-recall-intelligence, Task 3):
+ * frontmatter `aliases:` arrays land in `doc_aliases` during the
+ * incremental pass, the alias resolve pass materializes
+ * `target_document_id` after exact-path resolution, the run's
+ * `IndexStats.aliasResolved` counts it, and a non-empty run leaves
+ * one `index` metric record for the dashboard contract.
+ */
+
+import { test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { Store } from "../../../src/core/search/store.ts";
+import { listMetrics } from "../../../src/core/brain/metrics.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+
+let vault: string;
+let config: ResolvedSearchConfig;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-idx-alias-"));
+ config = makeConfig({ vault, dbPath: join(vault, "index.sqlite") });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+async function aliasLinkTarget(sourcePath: string): Promise<number | null> {
+ const store = await Store.open(config, { mode: "read" });
+ try {
+ // Same private-db introspection idiom as time-range.test.ts.
+ const row = (store as any).db
+ .query(
+ "SELECT l.target_document_id AS t FROM links l " +
+ "JOIN documents d ON d.id = l.source_document_id WHERE d.path = ?",
+ )
+ .get(sourcePath) as { t: number | null } | null;
+ return row?.t ?? null;
+ } finally {
+ await store.close();
+ }
+}
+
+test("a wikilink to a declared alias materializes through the index run", async () => {
+ writeFileSync(
+ join(vault, "project-alpha.md"),
+ '---\ntitle: Project Alpha\naliases: ["PA", "Alpha"]\n---\n\n# Project Alpha\n\nThe canonical page.\n',
+ );
+ writeFileSync(join(vault, "source.md"), "# Source\n\nSee [[PA]] for details.\n");
+
+ const stats = await indexVault(config);
+ expect(stats.aliasResolved).toBe(1);
+ expect(await aliasLinkTarget("source.md")).not.toBeNull();
+
+ const metrics = listMetrics(vault, { surface: "index" });
+ expect(metrics).toHaveLength(1);
+ expect(metrics[0]!.payload).toMatchObject({
+ added: 2,
+ alias_resolved: 1,
+ relation_violations: 0,
+ tier_drift: 0,
+ });
+});
+
+test("removing the alias un-materializes on the next run", async () => {
+ writeFileSync(
+ join(vault, "project-alpha.md"),
+ '---\ntitle: Project Alpha\naliases: ["PA"]\n---\n\n# Project Alpha\n\nBody one.\n',
+ );
+ writeFileSync(join(vault, "source.md"), "# Source\n\nSee [[PA]].\n");
+ await indexVault(config);
+ expect(await aliasLinkTarget("source.md")).not.toBeNull();
+
+ // Different body length so the mtime+size fastpath cannot skip the
+ // rewrite inside the same second.
+ writeFileSync(
+ join(vault, "project-alpha.md"),
+ "---\ntitle: Project Alpha\n---\n\n# Project Alpha\n\nBody two, now without any alias declared.\n",
+ );
+ const second = await indexVault(config);
+ expect(second.aliasResolved).toBe(0);
+ expect(await aliasLinkTarget("source.md")).toBeNull();
+});
+
+test("non-array and non-string alias values are skipped quietly", async () => {
+ writeFileSync(
+ join(vault, "odd.md"),
+ "---\ntitle: Odd\naliases: just-a-string\n---\n\n# Odd\n\nBody.\n",
+ );
+ writeFileSync(
+ join(vault, "mixed.md"),
+ "---\ntitle: Mixed\naliases: [ok-alias, 42]\n---\n\n# Mixed\n\nBody.\n",
+ );
+ writeFileSync(join(vault, "src.md"), "# Src\n\n[[ok-alias]] and [[just-a-string]].\n");
+ const stats = await indexVault(config);
+ expect(stats.aliasResolved).toBe(1);
+ expect(stats.errors).toEqual([]);
+});
+
+test("an unchanged vault run emits no metric record", async () => {
+ writeFileSync(join(vault, "a.md"), "# A\n\nBody.\n");
+ await indexVault(config);
+ await indexVault(config);
+ expect(listMetrics(vault, { surface: "index" })).toHaveLength(1);
+});
diff --git a/tests/core/search/query-expansion.test.ts b/tests/core/search/query-expansion.test.ts
new file mode 100644
index 00000000..7af6ac65
--- /dev/null
+++ b/tests/core/search/query-expansion.test.ts
@@ -0,0 +1,121 @@
+/**
+ * Deterministic query expansion producer (link-recall-intelligence,
+ * Task 5 / t_2fa95db1): a bare query becomes a structured lex/vec/hyde
+ * document for the EXISTING structured-query consumer - no model, no
+ * paid call. Lex strips stopwords for the implicit-AND FTS lane, vec
+ * adds an entity-context line when registry entities match, hyde is
+ * one template passage. Opt-in via `search(config, {expand: true})`.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { expandQuery } from "../../../src/core/search/query-expansion.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import { upsertEntity } from "../../../src/core/brain/entities/registry.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+
+const NOW = new Date("2026-06-05T10:00:00Z");
+
+let vault: string;
+let config: ResolvedSearchConfig;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-expand-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ config = makeConfig({ vault, dbPath: join(vault, "index.sqlite") });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+describe("expandQuery", () => {
+ test("produces deterministic lex/vec/hyde lanes from a bare query", () => {
+ const first = expandQuery(vault, "the canary rollout plan");
+ const second = expandQuery(vault, "the canary rollout plan");
+ expect(first).toEqual(second);
+ expect(first.lex.include).toEqual(["canary", "rollout", "plan"]);
+ expect(first.lex.exclude).toEqual([]);
+ expect(first.vec[0]).toBe("the canary rollout plan");
+ expect(first.hyde).toHaveLength(1);
+ expect(first.hyde[0]).toContain("canary");
+ expect(first.intent).toBeNull();
+ });
+
+ test("keeps the raw tokens when every token is a stopword", () => {
+ const doc = expandQuery(vault, "the and of");
+ expect(doc.lex.include).toEqual(["the", "and", "of"]);
+ });
+
+ test("adds one entity-context vec line when a registry entity matches", () => {
+ upsertEntity(vault, { name: "Canary Deploy", category: "concept", agent: "tester", now: NOW });
+ upsertEntity(vault, {
+ name: "Unrelated Thing",
+ category: "concept",
+ agent: "tester",
+ now: NOW,
+ });
+ const doc = expandQuery(vault, "canary rollout");
+ expect(doc.vec).toHaveLength(2);
+ expect(doc.vec[1]).toContain("Canary Deploy");
+ expect(doc.vec[1]).not.toContain("Unrelated Thing");
+ expect(doc.hyde[0]).toContain("Canary Deploy");
+ });
+
+ test("caps lex terms and entity context deterministically", () => {
+ const long = Array.from({ length: 20 }, (_, i) => `term${i}`).join(" ");
+ const doc = expandQuery(vault, long, { maxLexTerms: 5 });
+ expect(doc.lex.include).toHaveLength(5);
+ expect(doc.lex.include[0]).toBe("term0");
+ });
+
+ test("a vault without an entity registry expands without entity context", () => {
+ const doc = expandQuery(vault, "canary rollout");
+ expect(doc.vec).toEqual(["canary rollout"]);
+ });
+});
+
+describe("search --expand", () => {
+ test("stopword stripping recovers a hit the implicit-AND lane misses", async () => {
+ writeFileSync(
+ join(vault, "canary.md"),
+ "# Canary rollout\n\nShip one instance first, observe, expand gradually.\n",
+ );
+ writeFileSync(join(vault, "other.md"), "# Other\n\nNothing relevant here at all.\n");
+ await indexVault(config);
+
+ const plain = await search(config, { query: "the canary rollout" });
+ expect(plain.results).toHaveLength(0);
+
+ const expanded = await search(config, { query: "the canary rollout", expand: true });
+ expect(expanded.results.some((r) => r.path === "canary.md")).toBe(true);
+ expect(
+ expanded.results
+ .find((r) => r.path === "canary.md")!
+ .reasons.some((reason) => reason.startsWith("lane:lex")),
+ ).toBe(true);
+ });
+
+ test("an explicit structuredQuery wins over expand", async () => {
+ writeFileSync(join(vault, "canary.md"), "# Canary\n\nCanary body.\n");
+ writeFileSync(join(vault, "zebra.md"), "# Zebra\n\nZebra body.\n");
+ await indexVault(config);
+ const outcome = await search(config, {
+ query: "canary",
+ expand: true,
+ structuredQuery: {
+ intent: null,
+ lex: { include: ["zebra"], exclude: [] },
+ vec: [],
+ hyde: [],
+ },
+ });
+ expect(outcome.results.some((r) => r.path === "zebra.md")).toBe(true);
+ expect(outcome.results.some((r) => r.path === "canary.md")).toBe(false);
+ });
+});
diff --git a/tests/core/search/recall-benchmark.test.ts b/tests/core/search/recall-benchmark.test.ts
new file mode 100644
index 00000000..647b0602
--- /dev/null
+++ b/tests/core/search/recall-benchmark.test.ts
@@ -0,0 +1,124 @@
+/**
+ * Recall benchmark CI gate (link-recall-intelligence, t_e2215d49):
+ * the committed fixture vault + dataset score against the live hybrid
+ * pipeline with the deterministic local embedding provider; pinned
+ * thresholds fail the suite on a ranking regression. Measured on
+ * 2026-06-05: hit@5 = 1.000, MRR = 0.958 - thresholds sit one
+ * failing-direction margin below so legitimate ranking improvements
+ * do not flap the gate.
+ */
+
+import { test, expect, beforeAll, afterAll, describe } from "bun:test";
+import { cpSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import {
+ parseRecallBenchmarkDataset,
+ runRecallBenchmark,
+} from "../../../src/core/search/benchmark.ts";
+import { SearchError } from "../../../src/core/search/types.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+
+const FIXTURE = join(import.meta.dir, "..", "..", "fixtures", "recall-benchmark");
+
+/**
+ * CI thresholds - margin below the measured values above. Re-measure
+ * (run the suite and read the report) whenever the fixture vault,
+ * dataset, or ranking pipeline changes, and update both the pins and
+ * the header comment.
+ */
+const MIN_HIT_AT_5 = 0.9;
+const MIN_MRR = 0.85;
+
+let vault: string;
+let config: ResolvedSearchConfig;
+
+beforeAll(async () => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-bench-"));
+ cpSync(join(FIXTURE, "vault"), vault, { recursive: true });
+ config = makeConfig({
+ vault,
+ dbPath: join(vault, "index.sqlite"),
+ semantic: { enabled: true, provider: "local", dimension: 256 },
+ });
+ await indexVault(config, { embeddings: true });
+});
+
+afterAll(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+function loadDataset() {
+ return parseRecallBenchmarkDataset(
+ JSON.parse(readFileSync(join(FIXTURE, "dataset.json"), "utf8")),
+ );
+}
+
+describe("parseRecallBenchmarkDataset", () => {
+ test("accepts the committed dataset", () => {
+ const dataset = loadDataset();
+ expect(dataset.queries.length).toBeGreaterThanOrEqual(10);
+ });
+
+ test("rejects malformed datasets naming the offender", () => {
+ expect(() => parseRecallBenchmarkDataset([])).toThrow(SearchError);
+ expect(() => parseRecallBenchmarkDataset({ queries: [] })).toThrow(/non-empty/);
+ expect(() =>
+ parseRecallBenchmarkDataset({ queries: [{ id: "x", query: "q", expected: [] }] }),
+ ).toThrow(/expected path/);
+ expect(() =>
+ parseRecallBenchmarkDataset({
+ queries: [
+ { id: "x", query: "q", expected: ["a.md"] },
+ { id: "x", query: "q2", expected: ["b.md"] },
+ ],
+ }),
+ ).toThrow(/duplicated/);
+ expect(() =>
+ parseRecallBenchmarkDataset({ queries: [{ id: "x", query: "q", expected: ["a.md"], k: 0 }] }),
+ ).toThrow(/k must be/);
+ });
+});
+
+describe("runRecallBenchmark", () => {
+ test("the fixture vault holds the pinned recall thresholds", async () => {
+ const report = await runRecallBenchmark(config, loadDataset(), { k: 5 });
+ expect(report.total).toBe(12);
+ expect(report.hitAtK).toBeGreaterThanOrEqual(MIN_HIT_AT_5);
+ expect(report.mrr).toBeGreaterThanOrEqual(MIN_MRR);
+ });
+
+ test("the benchmark is deterministic across runs", async () => {
+ const first = await runRecallBenchmark(config, loadDataset(), { k: 5 });
+ const second = await runRecallBenchmark(config, loadDataset(), { k: 5 });
+ expect(second).toEqual(first);
+ });
+
+ test("the alias-hop query reaches the alias owner through traversal", async () => {
+ const report = await runRecallBenchmark(config, loadDataset(), { k: 5 });
+ const aliasHop = report.perQuery.find((q) => q.id === "alias-hop")!;
+ expect(aliasHop.hit).toBe(true);
+ });
+
+ test("wrong expectations score as misses - the metric points the right way", async () => {
+ const report = await runRecallBenchmark(
+ config,
+ parseRecallBenchmarkDataset({
+ queries: [{ id: "wrong", query: "canary rollout", expected: ["recipe-borscht.md"] }],
+ }),
+ { k: 5 },
+ );
+ expect(report.hitAtK).toBe(0);
+ expect(report.mrr).toBe(0);
+ expect(report.perQuery[0]!.rank).toBeNull();
+ });
+
+ test("expand mode reports itself and keeps the gate", async () => {
+ const report = await runRecallBenchmark(config, loadDataset(), { k: 5, expand: true });
+ expect(report.expand).toBe(true);
+ expect(report.hitAtK).toBeGreaterThanOrEqual(MIN_HIT_AT_5);
+ });
+});
diff --git a/tests/core/search/store-aliases.test.ts b/tests/core/search/store-aliases.test.ts
new file mode 100644
index 00000000..67780358
--- /dev/null
+++ b/tests/core/search/store-aliases.test.ts
@@ -0,0 +1,193 @@
+/**
+ * doc_aliases store surface (link-recall-intelligence, Task 2):
+ * schema v7 table, per-document alias replacement, and the JS-driven
+ * alias resolve pass that materializes `target_document_id` for
+ * unresolved slash-free wikilink targets - exact path matches first,
+ * shadowing-safe (an alias never outranks a real document basename),
+ * collisions first-wins by sorted document path.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { Store, normalizeAlias } from "../../../src/core/search/store.ts";
+import { LATEST_SCHEMA_VERSION } from "../../../src/core/search/schema.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+
+let tmp: string;
+let config: ResolvedSearchConfig;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-aliases-"));
+ config = makeConfig({ vault: tmp, dbPath: join(tmp, "index.sqlite") });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+});
+
+function doc(store: Store, path: string, title?: string): number {
+ return store.upsertDocument({
+ path,
+ title: title ?? path,
+ contentHash: `hash-${path}`,
+ mtime: 1700000000,
+ size: 10,
+ });
+}
+
+function link(store: Store, sourceId: number, target: string): void {
+ store.replaceLinks(sourceId, [
+ { linkType: "wikilink", targetPath: target, linkText: null, sourceChunkId: null },
+ ]);
+}
+
+function targetDocId(store: Store, sourceId: number): number | null {
+ // Same private-db introspection idiom as time-range.test.ts.
+ const row = (store as any).db
+ .query("SELECT target_document_id FROM links WHERE source_document_id = ?")
+ .get(sourceId) as { target_document_id: number | null } | null;
+ return row?.target_document_id ?? null;
+}
+
+test("schema version is 7", () => {
+ expect(LATEST_SCHEMA_VERSION).toBe(7);
+});
+
+test("normalizeAlias lower-cases, trims, and NFC-normalises", () => {
+ expect(normalizeAlias(" Project Alpha ")).toBe("project alpha");
+ // U+0041 U+0301 (decomposed) -> U+00C1 -> lowercased U+00E1
+ expect(normalizeAlias("Á")).toBe("á");
+});
+
+describe("replaceDocAliases / aliasesForDocument", () => {
+ test("round-trips normalised aliases and replaces on re-call", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ const id = doc(store, "notes/project-alpha.md", "Project Alpha");
+ store.replaceDocAliases(id, ["PA", "Alpha Project"]);
+ expect(store.aliasesForDocument(id)).toEqual(["alpha project", "pa"]);
+ store.replaceDocAliases(id, ["PA"]);
+ expect(store.aliasesForDocument(id)).toEqual(["pa"]);
+ store.replaceDocAliases(id, []);
+ expect(store.aliasesForDocument(id)).toEqual([]);
+ } finally {
+ await store.close();
+ }
+ });
+
+ test("duplicate and empty aliases are dropped", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ const id = doc(store, "a.md");
+ store.replaceDocAliases(id, ["PA", "pa", " ", ""]);
+ expect(store.aliasesForDocument(id)).toEqual(["pa"]);
+ } finally {
+ await store.close();
+ }
+ });
+});
+
+describe("resolveAliasTargets", () => {
+ test("resolves an unresolved slash-free wikilink target through an alias", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ const alpha = doc(store, "notes/project-alpha.md", "Project Alpha");
+ store.replaceDocAliases(alpha, ["PA"]);
+ const src = doc(store, "notes/source.md");
+ link(store, src, "PA");
+ store.resolveLinkTargets();
+ expect(targetDocId(store, src)).toBeNull();
+ const resolved = store.resolveAliasTargets();
+ expect(resolved).toBe(1);
+ expect(targetDocId(store, src)).toBe(alpha);
+ } finally {
+ await store.close();
+ }
+ });
+
+ test("an exact path match wins and the alias pass leaves it alone", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ const real = doc(store, "exact.md");
+ const other = doc(store, "other.md");
+ store.replaceDocAliases(other, ["exact.md"]);
+ const src = doc(store, "src.md");
+ link(store, src, "exact.md");
+ store.resolveLinkTargets();
+ expect(targetDocId(store, src)).toBe(real);
+ store.resolveAliasTargets();
+ expect(targetDocId(store, src)).toBe(real);
+ } finally {
+ await store.close();
+ }
+ });
+
+ test("an alias that shadows a real document basename never resolves", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ doc(store, "notes/foo.md");
+ const impostor = doc(store, "notes/impostor.md");
+ store.replaceDocAliases(impostor, ["foo"]);
+ const src = doc(store, "src.md");
+ link(store, src, "foo");
+ store.resolveLinkTargets();
+ const resolved = store.resolveAliasTargets();
+ expect(resolved).toBe(0);
+ // Read-time basename fallback still finds notes/foo.md; the
+ // materialized id must not point at the impostor.
+ expect(targetDocId(store, src)).toBeNull();
+ } finally {
+ await store.close();
+ }
+ });
+
+ test("two documents claiming one alias resolve first-wins by sorted path", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ const b = doc(store, "b-notes/claim.md");
+ const a = doc(store, "a-notes/claim2.md");
+ store.replaceDocAliases(b, ["shared"]);
+ store.replaceDocAliases(a, ["shared"]);
+ const src = doc(store, "src.md");
+ link(store, src, "Shared");
+ store.resolveAliasTargets();
+ expect(targetDocId(store, src)).toBe(a);
+ } finally {
+ await store.close();
+ }
+ });
+
+ test("targets with a slash are never alias-resolved", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ const alpha = doc(store, "notes/alpha.md");
+ store.replaceDocAliases(alpha, ["nested/pa"]);
+ const src = doc(store, "src.md");
+ link(store, src, "nested/pa");
+ const resolved = store.resolveAliasTargets();
+ expect(resolved).toBe(0);
+ expect(targetDocId(store, src)).toBeNull();
+ } finally {
+ await store.close();
+ }
+ });
+
+ test("deleting the alias owner cascades its alias rows", async () => {
+ const store = await Store.open(config, { mode: "write" });
+ try {
+ const alpha = doc(store, "notes/alpha.md");
+ store.replaceDocAliases(alpha, ["pa"]);
+ store.deleteDocument("notes/alpha.md");
+ const count = (store as any).db.query("SELECT COUNT(*) AS n FROM doc_aliases").get() as {
+ n: number;
+ } | null;
+ expect(count?.n).toBe(0);
+ } finally {
+ await store.close();
+ }
+ });
+});
diff --git a/tests/core/search/store.test.ts b/tests/core/search/store.test.ts
index a36c759b..9820df48 100644
--- a/tests/core/search/store.test.ts
+++ b/tests/core/search/store.test.ts
@@ -55,6 +55,8 @@ function makeConfig(overrides?: Partial<ResolvedSearchConfig>): ResolvedSearchCo
learnedWeightsEnabled: false,
activationEnabled: true,
twoPassEnabled: true,
+ poolMultiplier: 3,
+ selfTuningEnabled: false,
}),
...overrides,
});
diff --git a/tests/core/search/store.vec.test.ts b/tests/core/search/store.vec.test.ts
index 2777596f..8f0e45bc 100644
--- a/tests/core/search/store.vec.test.ts
+++ b/tests/core/search/store.vec.test.ts
@@ -58,6 +58,8 @@ function semanticConfig(
learnedWeightsEnabled: false,
activationEnabled: true,
twoPassEnabled: true,
+ poolMultiplier: 3,
+ selfTuningEnabled: false,
}),
...overrides,
});
diff --git a/tests/core/search/tuning.test.ts b/tests/core/search/tuning.test.ts
new file mode 100644
index 00000000..424bd582
--- /dev/null
+++ b/tests/core/search/tuning.test.ts
@@ -0,0 +1,193 @@
+/**
+ * Opt-in self-tuning recall (link-recall-intelligence, t_ae973491):
+ * a bounded parameter grid (pool multiplier, traversal depth, learned
+ * weights, expansion) evaluated deterministically against the recall
+ * benchmark; the winner persists to Brain/search/tuning.json and
+ * search() consults it ONLY when self-tuning is enabled. Replayable:
+ * delete the file and nothing else changes; out-of-bounds values are
+ * ignored on read.
+ */
+
+import { test, expect, beforeEach, afterEach, describe } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ applyTunedParameters,
+ defaultTuningGrid,
+ loadTunedParameters,
+ resetTuning,
+ tuneRecall,
+} from "../../../src/core/search/tuning.ts";
+import { parseRecallBenchmarkDataset } from "../../../src/core/search/benchmark.ts";
+import { indexVault } from "../../../src/core/search/indexer.ts";
+import { search } from "../../../src/core/search/search.ts";
+import { makeConfig } from "../../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
+
+const NOW = new Date("2026-06-05T12:00:00Z");
+
+let vault: string;
+let config: ResolvedSearchConfig;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-tuning-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ config = makeConfig({ vault, dbPath: join(vault, "index.sqlite") });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+const DATASET = parseRecallBenchmarkDataset({
+ queries: [
+ { id: "canary", query: "canary rollout", expected: ["canary.md"] },
+ { id: "stopword", query: "the nightly backup", expected: ["backup.md"] },
+ ],
+});
+
+function writeNotes(): void {
+ writeFileSync(
+ join(vault, "canary.md"),
+ "# Canary rollout\n\nShip one instance first, observe, expand gradually.\n",
+ );
+ writeFileSync(
+ join(vault, "backup.md"),
+ "# Nightly backup\n\nSnapshot databases every night, verify checksums offsite.\n",
+ );
+ writeFileSync(join(vault, "other.md"), "# Other\n\nNothing relevant whatsoever.\n");
+}
+
+describe("grid + apply", () => {
+ test("the default grid is bounded, stable, and starts at the defaults", () => {
+ const grid = defaultTuningGrid();
+ expect(grid).toHaveLength(24);
+ expect(grid[0]).toEqual({
+ poolMultiplier: 3,
+ traversalDepth: 1,
+ learnedWeights: false,
+ expansion: false,
+ });
+ expect(defaultTuningGrid()).toEqual(grid);
+ });
+
+ test("applyTunedParameters overrides recall knobs and disarms recursion", () => {
+ const tuned = applyTunedParameters(config, {
+ poolMultiplier: 5,
+ traversalDepth: 2,
+ learnedWeights: true,
+ expansion: false,
+ });
+ expect(tuned.recall.poolMultiplier).toBe(5);
+ expect(tuned.recall.maxHops).toBe(2);
+ expect(tuned.recall.learnedWeightsEnabled).toBe(true);
+ expect(tuned.recall.selfTuningEnabled).toBe(false);
+ // The base config is untouched.
+ expect(config.recall.poolMultiplier).toBe(3);
+ });
+});
+
+describe("tuneRecall", () => {
+ test("evaluates the grid, persists the winner, and is deterministic", async () => {
+ writeNotes();
+ await indexVault(config);
+ const grid = [
+ { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: false },
+ { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: true },
+ ];
+ const first = await tuneRecall(config, DATASET, { grid, now: NOW });
+ // The stopword query only hits with expansion - it must win.
+ expect(first.chosen.expansion).toBe(true);
+ expect(first.evaluated).toHaveLength(2);
+
+ const raw = JSON.parse(readFileSync(join(vault, "Brain", "search", "tuning.json"), "utf8")) as {
+ schema: string;
+ chosen: { expansion: boolean };
+ dataset_hash: string;
+ };
+ expect(raw.schema).toBe("o2b.tuning.v1");
+ expect(raw.chosen.expansion).toBe(true);
+
+ const second = await tuneRecall(config, DATASET, { grid, now: NOW });
+ expect(second.chosen).toEqual(first.chosen);
+ expect(second.evaluated).toEqual(first.evaluated);
+ });
+
+ test("loadTunedParameters round-trips and rejects out-of-bounds values", async () => {
+ writeNotes();
+ await indexVault(config);
+ const grid = [
+ { poolMultiplier: 4, traversalDepth: 2, learnedWeights: false, expansion: false },
+ ];
+ await tuneRecall(config, DATASET, { grid, now: NOW });
+ expect(loadTunedParameters(vault)).toEqual(grid[0]!);
+
+ const path = join(vault, "Brain", "search", "tuning.json");
+ const tampered = JSON.parse(readFileSync(path, "utf8")) as {
+ chosen: { poolMultiplier: number };
+ };
+ tampered.chosen.poolMultiplier = 99;
+ writeFileSync(path, JSON.stringify(tampered));
+ expect(loadTunedParameters(vault)).toBeNull();
+
+ writeFileSync(path, "{not json");
+ expect(loadTunedParameters(vault)).toBeNull();
+ });
+
+ test("resetTuning removes the persisted state", async () => {
+ writeNotes();
+ await indexVault(config);
+ await tuneRecall(config, DATASET, {
+ grid: [{ poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: false }],
+ now: NOW,
+ });
+ expect(resetTuning(vault)).toBe(true);
+ expect(existsSync(join(vault, "Brain", "search", "tuning.json"))).toBe(false);
+ expect(loadTunedParameters(vault)).toBeNull();
+ expect(resetTuning(vault)).toBe(false);
+ });
+});
+
+describe("search() under self-tuning", () => {
+ test("opt-out ignores a persisted tuning file entirely", async () => {
+ writeNotes();
+ await indexVault(config);
+ mkdirSync(join(vault, "Brain", "search"), { recursive: true });
+ writeFileSync(
+ join(vault, "Brain", "search", "tuning.json"),
+ JSON.stringify({
+ schema: "o2b.tuning.v1",
+ chosen: { poolMultiplier: 5, traversalDepth: 2, learnedWeights: false, expansion: true },
+ }),
+ );
+ // selfTuningEnabled is false in the default test config.
+ const outcome = await search(config, { query: "the nightly backup" });
+ expect(outcome.results).toHaveLength(0);
+ });
+
+ test("opt-in applies the tuned expansion to a bare query", async () => {
+ writeNotes();
+ await indexVault(config);
+ mkdirSync(join(vault, "Brain", "search"), { recursive: true });
+ writeFileSync(
+ join(vault, "Brain", "search", "tuning.json"),
+ JSON.stringify({
+ schema: "o2b.tuning.v1",
+ chosen: { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: true },
+ }),
+ );
+ const tunedConfig = makeConfig({
+ vault,
+ dbPath: join(vault, "index.sqlite"),
+ selfTuningEnabled: true,
+ });
+ const outcome = await search(tunedConfig, { query: "the nightly backup" });
+ expect(outcome.results.some((r) => r.path === "backup.md")).toBe(true);
+
+ // An explicit expand: false wins over the tuned default.
+ const explicit = await search(tunedConfig, { query: "the nightly backup", expand: false });
+ expect(explicit.results).toHaveLength(0);
+ });
+});
diff --git a/tests/e2e/link-recall-intelligence.integration.test.ts b/tests/e2e/link-recall-intelligence.integration.test.ts
new file mode 100644
index 00000000..b0975dd4
--- /dev/null
+++ b/tests/e2e/link-recall-intelligence.integration.test.ts
@@ -0,0 +1,201 @@
+/**
+ * Link & Recall Intelligence Suite - end-to-end composition over one
+ * vault: a wikilink to a frontmatter alias materializes at index time
+ * (t_d6660a83), bridge discovery proposes the embedding-near unlinked
+ * pair and accept wires it (t_ab540afe), community detection
+ * materializes a cluster note (t_4ba927ec), the recall benchmark
+ * scores the vault (t_e2215d49), self-tuning persists a grid choice
+ * that search honors under the flag (t_ae973491) with deterministic
+ * expansion (t_2fa95db1), and every surface left a run-level record
+ * in Brain/metrics/ - the dashboard contract.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ acceptBridge,
+ discoverBridges,
+ readDismissedBridges,
+ writeBridgeProposals,
+} from "../../src/core/brain/link-graph/bridge-discovery.ts";
+import {
+ detectCommunities,
+ materializeClusterNotes,
+} from "../../src/core/brain/link-graph/communities.ts";
+import { appendMetric, listMetrics } from "../../src/core/brain/metrics.ts";
+import { isoSecond } from "../../src/core/brain/time.ts";
+import {
+ parseRecallBenchmarkDataset,
+ runRecallBenchmark,
+} from "../../src/core/search/benchmark.ts";
+import { tuneRecall } from "../../src/core/search/tuning.ts";
+import { indexVault } from "../../src/core/search/indexer.ts";
+import { search } from "../../src/core/search/search.ts";
+import { Store } from "../../src/core/search/store.ts";
+import { makeConfig } from "../helpers/search-fixtures.ts";
+import type { ResolvedSearchConfig } from "../../src/core/search/types.ts";
+
+const NOW = new Date("2026-06-05T12:00:00Z");
+
+let vault: string;
+let config: ResolvedSearchConfig;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-lri-e2e-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+ config = makeConfig({
+ vault,
+ dbPath: join(vault, "index.sqlite"),
+ semantic: { enabled: true, provider: "local", dimension: 256 },
+ });
+});
+
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+});
+
+test("the suite composes end to end on one vault", async () => {
+ // -- 1. Vault: an alias owner, twin unlinked notes, one community ------
+ writeFileSync(
+ join(vault, "project-alpha.md"),
+ '---\ntitle: Project Alpha\naliases: ["PA"]\n---\n\n# Project Alpha\n\nUmbrella initiative: importer, dashboard, billing pipeline.\n',
+ );
+ writeFileSync(
+ join(vault, "weekly-review.md"),
+ "# Weekly review\n\nProgress on [[PA]]: importer merged, dashboard design approved.\n",
+ );
+ writeFileSync(
+ join(vault, "alpha-deploy.md"),
+ "# Canary deployment runbook\n\nShip the canary release to one production instance, watch error rates, expand the deployment gradually, roll back on regression.\n",
+ );
+ writeFileSync(
+ join(vault, "beta-deploy.md"),
+ "# Deployment safety checklist\n\nCanary release first: one production instance, watch error rates, expand deployment gradually, roll back the release on regression.\n",
+ );
+ const team = ["team-a", "team-b", "team-c", "team-d"];
+ for (const name of team) {
+ const others = team
+ .filter((t) => t !== name)
+ .map((t) => `[[${t}]]`)
+ .join(" ");
+ writeFileSync(join(vault, `${name}.md`), `# ${name}\n\nSee ${others}.\n`);
+ }
+
+ // -- 2. Alias resolution materializes at index time --------------------
+ const stats = await indexVault(config, { embeddings: true });
+ expect(stats.aliasResolved).toBe(1);
+ expect(listMetrics(vault, { surface: "index" })).toHaveLength(1);
+
+ // -- 3. Bridge discovery: twin pair proposed, accept wires it ----------
+ const store = await Store.open(config, { mode: "read" });
+ try {
+ const report = discoverBridges(store, {
+ minSimilarity: 0.5,
+ dismissed: readDismissedBridges(vault),
+ });
+ expect(report.vecAvailable).toBe(true);
+ const pair = report.proposals.find(
+ (p) => [p.source, p.target].toSorted().join("|") === "alpha-deploy.md|beta-deploy.md",
+ );
+ expect(pair).toBeDefined();
+ writeBridgeProposals(vault, report, { now: NOW });
+ appendMetric(vault, {
+ surface: "bridge_discovery",
+ runAt: isoSecond(NOW),
+ payload: { proposals: report.proposals.length },
+ });
+
+ const accepted = acceptBridge(vault, pair!.source, pair!.target);
+ expect(accepted.changed).toBe(true);
+
+ // -- 4. Communities: the 4-clique materializes a cluster note --------
+ const communities = detectCommunities(store, { minSize: 4 });
+ expect(communities.some((c) => c.size === 4)).toBe(true);
+ const materialized = materializeClusterNotes(vault, communities, { store, now: NOW });
+ expect(materialized.written.length).toBeGreaterThanOrEqual(1);
+ appendMetric(vault, {
+ surface: "communities",
+ runAt: isoSecond(NOW),
+ payload: { communities: communities.length },
+ });
+ expect(readdirSync(join(vault, "Brain", "clusters")).length).toBeGreaterThanOrEqual(1);
+ } finally {
+ await store.close();
+ }
+
+ // -- 5. Reindex sees the accepted bridge: pair no longer proposed ------
+ await indexVault(config, { embeddings: true });
+ const store2 = await Store.open(config, { mode: "read" });
+ try {
+ const second = discoverBridges(store2, {
+ minSimilarity: 0.5,
+ dismissed: readDismissedBridges(vault),
+ });
+ expect(
+ second.proposals.some(
+ (p) => [p.source, p.target].toSorted().join("|") === "alpha-deploy.md|beta-deploy.md",
+ ),
+ ).toBe(false);
+ } finally {
+ await store2.close();
+ }
+
+ // -- 6. Benchmark scores the vault, alias hop included -----------------
+ const dataset = parseRecallBenchmarkDataset({
+ queries: [
+ { id: "canary", query: "canary deployment runbook", expected: ["alpha-deploy.md"] },
+ { id: "alias-hop", query: "PA importer dashboard", expected: ["project-alpha.md"] },
+ { id: "stopword", query: "the weekly review importer", expected: ["weekly-review.md"] },
+ ],
+ });
+ const bench = await runRecallBenchmark(config, dataset, { k: 5 });
+ expect(bench.perQuery.find((q) => q.id === "canary")!.hit).toBe(true);
+ expect(bench.perQuery.find((q) => q.id === "alias-hop")!.hit).toBe(true);
+ appendMetric(vault, {
+ surface: "recall_benchmark",
+ runAt: isoSecond(NOW),
+ payload: { mrr: bench.mrr, hit_at_k: bench.hitAtK },
+ });
+
+ // -- 7. Self-tuning: expansion wins on the stopword query. Tuning
+ // runs keyword-only so the lex lane decides - with the semantic
+ // layer on, the vec lane already recovers the stopword case and the
+ // grid points tie.
+ const kwConfig = makeConfig({ vault, dbPath: join(vault, "index.sqlite") });
+ const tuneReport = await tuneRecall(kwConfig, dataset, {
+ grid: [
+ { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: false },
+ { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: true },
+ ],
+ now: NOW,
+ });
+ expect(tuneReport.chosen.expansion).toBe(true);
+ appendMetric(vault, {
+ surface: "self_tuning",
+ runAt: isoSecond(NOW),
+ payload: { chosen: tuneReport.chosen },
+ });
+
+ const tunedConfig = makeConfig({
+ vault,
+ dbPath: join(vault, "index.sqlite"),
+ selfTuningEnabled: true,
+ });
+ const tunedSearch = await search(tunedConfig, { query: "the weekly review importer" });
+ expect(tunedSearch.results.some((r) => r.path === "weekly-review.md")).toBe(true);
+
+ // -- 8. Dashboard contract: every surface left a record ----------------
+ const surfaces = new Set(listMetrics(vault).map((m) => m.surface));
+ for (const surface of [
+ "index",
+ "bridge_discovery",
+ "communities",
+ "recall_benchmark",
+ "self_tuning",
+ ]) {
+ expect(surfaces.has(surface)).toBe(true);
+ }
+});
diff --git a/tests/fixtures/recall-benchmark/dataset.json b/tests/fixtures/recall-benchmark/dataset.json
new file mode 100644
index 00000000..87e4fe77
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/dataset.json
@@ -0,0 +1,24 @@
+{
+ "queries": [
+ { "id": "canary", "query": "canary rollout", "expected": ["deploy-canary.md"] },
+ {
+ "id": "bluegreen",
+ "query": "blue green deployment swap",
+ "expected": ["deploy-bluegreen.md"]
+ },
+ { "id": "oauth", "query": "oauth token refresh", "expected": ["auth-oauth.md"] },
+ { "id": "passwords", "query": "password hashing salts", "expected": ["auth-passwords.md"] },
+ { "id": "backups", "query": "nightly backup strategy", "expected": ["db-backups.md"] },
+ { "id": "indexing", "query": "slow queries missing index", "expected": ["db-indexing.md"] },
+ { "id": "incident", "query": "outage root cause timeout", "expected": ["incident-2026-05.md"] },
+ { "id": "alias-hop", "query": "PA importer progress", "expected": ["project-alpha.md"] },
+ {
+ "id": "embeddings",
+ "query": "embedding provider configuration",
+ "expected": ["embeddings-pipeline.md"]
+ },
+ { "id": "tuning", "query": "tune recall top-k parameters", "expected": ["search-tuning.md"] },
+ { "id": "standup", "query": "standup blockers staging", "expected": ["notes-standup.md"] },
+ { "id": "style", "query": "writing conventions active voice", "expected": ["style-guide.md"] }
+ ]
+}
diff --git a/tests/fixtures/recall-benchmark/vault/auth-oauth.md b/tests/fixtures/recall-benchmark/vault/auth-oauth.md
new file mode 100644
index 00000000..c46bdf5d
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/auth-oauth.md
@@ -0,0 +1,4 @@
+# OAuth token refresh
+
+Access tokens expire after an hour; the client exchanges the refresh token at
+the authorization server and rotates both. Store refresh tokens encrypted.
diff --git a/tests/fixtures/recall-benchmark/vault/auth-passwords.md b/tests/fixtures/recall-benchmark/vault/auth-passwords.md
new file mode 100644
index 00000000..ef1dbcbb
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/auth-passwords.md
@@ -0,0 +1,4 @@
+# Password hashing
+
+Use argon2id with per-user salts for password hashing. Never store plaintext;
+migrate legacy bcrypt hashes on the next successful login.
diff --git a/tests/fixtures/recall-benchmark/vault/db-backups.md b/tests/fixtures/recall-benchmark/vault/db-backups.md
new file mode 100644
index 00000000..20b2fdc6
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/db-backups.md
@@ -0,0 +1,4 @@
+# Nightly backup strategy
+
+A cron job snapshots the SQLite database every night, verifies integrity with
+a checksum, and rotates the last fourteen backup archives offsite.
diff --git a/tests/fixtures/recall-benchmark/vault/db-indexing.md b/tests/fixtures/recall-benchmark/vault/db-indexing.md
new file mode 100644
index 00000000..6a61b918
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/db-indexing.md
@@ -0,0 +1,4 @@
+# Query performance
+
+Slow queries usually mean a missing index. Add a covering index for the hot
+path, then re-check the plan with EXPLAIN before shipping.
diff --git a/tests/fixtures/recall-benchmark/vault/deploy-bluegreen.md b/tests/fixtures/recall-benchmark/vault/deploy-bluegreen.md
new file mode 100644
index 00000000..604b9e00
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/deploy-bluegreen.md
@@ -0,0 +1,4 @@
+# Blue-green deployment
+
+Run two identical environments and swap traffic between blue and green at the
+load balancer. Zero-downtime releases with an instant rollback path.
diff --git a/tests/fixtures/recall-benchmark/vault/deploy-canary.md b/tests/fixtures/recall-benchmark/vault/deploy-canary.md
new file mode 100644
index 00000000..dfc4f06c
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/deploy-canary.md
@@ -0,0 +1,4 @@
+# Canary rollout
+
+Ship the new version to one instance first, observe error rates and latency,
+then expand the rollout gradually. Roll back instantly if the canary degrades.
diff --git a/tests/fixtures/recall-benchmark/vault/embeddings-pipeline.md b/tests/fixtures/recall-benchmark/vault/embeddings-pipeline.md
new file mode 100644
index 00000000..2e94a6c0
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/embeddings-pipeline.md
@@ -0,0 +1,4 @@
+# Embedding provider configuration
+
+The indexer batches chunk texts to the configured embedding provider; the
+local hashing provider needs no key, openai-compat needs base URL and model.
diff --git a/tests/fixtures/recall-benchmark/vault/incident-2026-05.md b/tests/fixtures/recall-benchmark/vault/incident-2026-05.md
new file mode 100644
index 00000000..fb7152c9
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/incident-2026-05.md
@@ -0,0 +1,4 @@
+# Outage postmortem
+
+Root cause: a connection-pool timeout cascaded into worker starvation during
+the deploy. Action items: tighter timeouts, circuit breaker, alert on queue depth.
diff --git a/tests/fixtures/recall-benchmark/vault/link-source.md b/tests/fixtures/recall-benchmark/vault/link-source.md
new file mode 100644
index 00000000..3dcc5f37
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/link-source.md
@@ -0,0 +1,4 @@
+# Weekly review
+
+Reviewed progress on [[PA]] this week: importer merged, dashboard design
+approved, billing pipeline still in discovery.
diff --git a/tests/fixtures/recall-benchmark/vault/notes-standup.md b/tests/fixtures/recall-benchmark/vault/notes-standup.md
new file mode 100644
index 00000000..108c8dae
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/notes-standup.md
@@ -0,0 +1,4 @@
+# Standup notes
+
+Yesterday the team finished the importer; today the focus is review backlog.
+Blockers: staging credentials expired.
diff --git a/tests/fixtures/recall-benchmark/vault/project-alpha.md b/tests/fixtures/recall-benchmark/vault/project-alpha.md
new file mode 100644
index 00000000..b263c4ff
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/project-alpha.md
@@ -0,0 +1,9 @@
+---
+title: Project Alpha
+aliases: [PA]
+---
+
+# Project Alpha
+
+The umbrella initiative covering the importer, the dashboard, and the new
+billing pipeline. Quarterly milestones tracked in the roadmap.
diff --git a/tests/fixtures/recall-benchmark/vault/recipe-borscht.md b/tests/fixtures/recall-benchmark/vault/recipe-borscht.md
new file mode 100644
index 00000000..44ac035b
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/recipe-borscht.md
@@ -0,0 +1,3 @@
+# Borscht recipe
+
+Beets, cabbage, carrots, and a long simmer. Serve with sour cream and dill.
diff --git a/tests/fixtures/recall-benchmark/vault/search-tuning.md b/tests/fixtures/recall-benchmark/vault/search-tuning.md
new file mode 100644
index 00000000..8ecffefe
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/search-tuning.md
@@ -0,0 +1,4 @@
+# Recall parameters
+
+Top-k, candidate pool multipliers, and fusion weights decide recall quality.
+Measure with the fixed benchmark dataset before changing any of them.
diff --git a/tests/fixtures/recall-benchmark/vault/style-guide.md b/tests/fixtures/recall-benchmark/vault/style-guide.md
new file mode 100644
index 00000000..deb0d25d
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/style-guide.md
@@ -0,0 +1,4 @@
+# Writing conventions
+
+Short sentences, active voice, no exclamation marks in technical prose.
+Headings in sentence case; code identifiers in backticks.
diff --git a/tests/fixtures/recall-benchmark/vault/vacation-policy.md b/tests/fixtures/recall-benchmark/vault/vacation-policy.md
new file mode 100644
index 00000000..e6ed31c5
--- /dev/null
+++ b/tests/fixtures/recall-benchmark/vault/vacation-policy.md
@@ -0,0 +1,4 @@
+# Vacation policy
+
+Twenty-five days per year, carry over five. Request through the HR portal at
+least two weeks ahead.
diff --git a/tests/helpers/search-fixtures.ts b/tests/helpers/search-fixtures.ts
index 7183db89..a3b5fa18 100644
--- a/tests/helpers/search-fixtures.ts
+++ b/tests/helpers/search-fixtures.ts
@@ -71,6 +71,8 @@ export function makeConfig(opts: {
twoPassEnabled?: boolean;
/** Rank-fusion mode; defaults to "linear". */
fusionMode?: "linear" | "rrf";
+ /** Opt-in self-tuning recall; defaults to false. */
+ selfTuningEnabled?: boolean;
/** RRF damping constant; defaults to 60. */
rrfK?: number;
}): ResolvedSearchConfig {
@@ -122,6 +124,8 @@ export function makeConfig(opts: {
learnedWeightsEnabled: opts.learnedWeightsEnabled ?? false,
activationEnabled: opts.activationEnabled ?? true,
twoPassEnabled: opts.twoPassEnabled ?? true,
+ poolMultiplier: 3,
+ selfTuningEnabled: opts.selfTuningEnabled ?? false,
}),
});
}
diff --git a/tests/mcp/brain-governance.test.ts b/tests/mcp/brain-governance.test.ts
index e61ec60d..d0a27bcf 100644
--- a/tests/mcp/brain-governance.test.ts
+++ b/tests/mcp/brain-governance.test.ts
@@ -165,7 +165,10 @@ test("brain_maintenance run executes the lane; status reads the journal", async
await initialize(server);
const ran = await call(server, "brain_maintenance", { operation: "run" });
expect(ran["verdict"]).toBe("run");
- expect((ran["tasks"] as Array<{ ok: boolean }>).every((t) => t.ok)).toBe(true);
+ const tasks = ran["tasks"] as Array<{ name: string; ok: boolean }>;
+ // Same lane contract as the CLI verb (link-recall-intelligence).
+ expect(tasks.map((t) => t.name)).toEqual(["dream", "reindex", "bridges", "clusters"]);
+ expect(tasks.every((t) => t.ok)).toBe(true);
const status = await call(server, "brain_maintenance", { operation: "status" });
expect(status["lease"]).toBeNull();
diff --git a/tests/mcp/link-recall-tools.test.ts b/tests/mcp/link-recall-tools.test.ts
new file mode 100644
index 00000000..9303a503
--- /dev/null
+++ b/tests/mcp/link-recall-tools.test.ts
@@ -0,0 +1,235 @@
+/**
+ * Link & Recall Intelligence Suite MCP tools: brain_bridges
+ * (discover/list/accept/dismiss over the vec index), brain_clusters
+ * (community detection + derived notes), brain_benchmark (fixed
+ * dataset scoring), brain_tune (bounded self-tuning lifecycle).
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { bootstrapBrain } from "../../src/core/brain/init.ts";
+import { listMetrics } from "../../src/core/brain/metrics.ts";
+import { indexVault } from "../../src/core/search/indexer.ts";
+import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
+import { makeConfig } from "../helpers/search-fixtures.ts";
+import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
+
+let tmp: string;
+let vault: string;
+let configHome: string;
+let configPath: string;
+const savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-lri-"));
+ vault = join(tmp, "vault");
+ configHome = mkdtempSync(join(tmpdir(), "o2b-mcp-lri-cfg-"));
+ configPath = join(configHome, "config.yaml");
+ for (const key of [
+ "VAULT_AGENT_NAME",
+ "VAULT_TIMEZONE",
+ "VAULT_DIR",
+ "OPEN_SECOND_BRAIN_CONFIG",
+ ]) {
+ savedEnv[key] = process.env[key];
+ delete process.env[key];
+ }
+ process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
+ atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
+ bootstrapBrain(vault, { configPath });
+});
+
+afterEach(() => {
+ rmSync(tmp, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+ for (const [key, value] of Object.entries(savedEnv)) {
+ if (value === undefined) delete process.env[key];
+ else process.env[key] = value;
+ }
+});
+
+async function initialize(server: MCPServer): Promise<void> {
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 1,
+ method: "initialize",
+ params: {
+ protocolVersion: PROTOCOL_VERSION,
+ capabilities: {},
+ clientInfo: { name: "lri-test", version: "0" },
+ },
+ });
+ await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ method: "notifications/initialized",
+ });
+}
+
+async function call(
+ server: MCPServer,
+ tool: string,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const res = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 99,
+ method: "tools/call",
+ params: { name: tool, arguments: args },
+ })) as { result?: { content?: Array<{ text?: string }> }; error?: { message: string } };
+ if (res.error !== undefined) throw new Error(res.error.message);
+ return JSON.parse(res.result!.content![0]!.text!) as Record<string, unknown>;
+}
+
+async function callError(
+ server: MCPServer,
+ tool: string,
+ args: Record<string, unknown>,
+): Promise<{ code: number; message: string }> {
+ const res = (await server.handleRequest({
+ jsonrpc: JSONRPC_VERSION,
+ id: 100,
+ method: "tools/call",
+ params: { name: tool, arguments: args },
+ })) as { error?: { code: number; message: string } };
+ expect(res.error).toBeDefined();
+ return res.error!;
+}
+
+function writeGroup(): void {
+ const group = ["team-a", "team-b", "team-c", "team-d"];
+ for (const name of group) {
+ const others = group
+ .filter((g) => g !== name)
+ .map((g) => `[[${g}]]`)
+ .join(" ");
+ writeFileSync(join(vault, `${name}.md`), `# ${name}\n\nSee ${others}.\n`);
+ }
+ writeFileSync(join(vault, "canary.md"), "# Canary rollout\n\nShip one instance first.\n");
+}
+
+async function indexDefaultLocation(): Promise<void> {
+ await indexVault(
+ makeConfig({ vault, dbPath: join(vault, ".open-second-brain", "brain.sqlite") }),
+ );
+}
+
+const DATASET = {
+ queries: [{ id: "canary", query: "canary rollout", expected: ["canary.md"] }],
+};
+
+test("brain_bridges validates params before touching the environment", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const bad = await callError(server, "brain_bridges", { operation: "accept", source: "a.md" });
+ expect(bad.code).toBe(-32602);
+ expect(bad.message).toMatch(/target/);
+ const badOp = await callError(server, "brain_bridges", { operation: "nope" });
+ expect(badOp.code).toBe(-32602);
+});
+
+test("brain_bridges discover fails soft without an index, dismiss/list round-trip", async () => {
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const discover = await call(server, "brain_bridges", { operation: "discover" });
+ expect(discover["vec_available"]).toBe(false);
+
+ const dismissed = await call(server, "brain_bridges", {
+ operation: "dismiss",
+ source: "a.md",
+ target: "b.md",
+ });
+ expect(dismissed["added"]).toBe(true);
+
+ const list = await call(server, "brain_bridges", { operation: "list" });
+ expect(list["exists"]).toBe(false);
+});
+
+test("brain_bridges accept writes the related wikilink through the vault boundary", async () => {
+ writeGroup();
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+ const accepted = await call(server, "brain_bridges", {
+ operation: "accept",
+ source: "team-a.md",
+ target: "canary.md",
+ });
+ expect(accepted["changed"]).toBe(true);
+
+ const escape = await callError(server, "brain_bridges", {
+ operation: "accept",
+ source: "../outside.md",
+ target: "canary.md",
+ });
+ expect(escape.code).toBe(-32602);
+});
+
+test("brain_clusters run materializes derived notes and the metric", async () => {
+ writeGroup();
+ await indexDefaultLocation();
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const run = await call(server, "brain_clusters", { operation: "run" });
+ const communities = run["communities"] as Array<{ size: number }>;
+ expect(communities).toHaveLength(1);
+ expect(communities[0]!.size).toBe(4);
+ expect(listMetrics(vault, { surface: "communities" })).toHaveLength(1);
+
+ const list = await call(server, "brain_clusters", { operation: "list" });
+ expect(list["clusters"]).toHaveLength(1);
+
+ const bad = await callError(server, "brain_clusters", { operation: "run", min_size: 1 });
+ expect(bad.code).toBe(-32602);
+});
+
+test("brain_benchmark run scores an inline dataset and records the metric", async () => {
+ writeGroup();
+ await indexDefaultLocation();
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const report = await call(server, "brain_benchmark", { operation: "run", dataset: DATASET });
+ expect(report["total"]).toBe(1);
+ expect(report["hit_at_k"]).toBe(1);
+ expect(listMetrics(vault, { surface: "recall_benchmark" })).toHaveLength(1);
+
+ const bad = await callError(server, "brain_benchmark", {
+ operation: "run",
+ dataset: { queries: [] },
+ });
+ expect(bad.code).toBe(-32602);
+});
+
+test("brain_tune run/status/reset lifecycle", async () => {
+ writeGroup();
+ await indexDefaultLocation();
+ const server = new MCPServer({ vault, configPath });
+ await initialize(server);
+
+ const before = await call(server, "brain_tune", { operation: "status" });
+ expect(before["tuned"]).toBeNull();
+
+ // The full grid report exceeds the preview budget and arrives as an
+ // artifact envelope; the persisted file is the source of truth.
+ const run = await call(server, "brain_tune", { operation: "run", dataset: DATASET });
+ expect(run["preview_truncated"] === true || Array.isArray(run["evaluated"])).toBe(true);
+ const persisted = JSON.parse(
+ readFileSync(join(vault, "Brain", "search", "tuning.json"), "utf8"),
+ ) as { evaluated: unknown[] };
+ expect(persisted.evaluated).toHaveLength(24);
+ expect(listMetrics(vault, { surface: "self_tuning" })).toHaveLength(1);
+
+ const status = await call(server, "brain_tune", { operation: "status" });
+ expect(status["tuned"]).not.toBeNull();
+ expect(status["enabled"]).toBe(false);
+
+ const reset = await call(server, "brain_tune", { operation: "reset" });
+ expect(reset["removed"]).toBe(true);
+
+ const missingDataset = await callError(server, "brain_tune", { operation: "run" });
+ expect(missingDataset.code).toBe(-32602);
+});
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index 81d07926..19705c72 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -266,6 +266,11 @@ describe("tool listing", () => {
"brain_tiers",
"brain_secrets",
"brain_maintenance",
+ // Link & Recall Intelligence Suite (v0.45.0).
+ "brain_bridges",
+ "brain_clusters",
+ "brain_benchmark",
+ "brain_tune",
// Agent Write Contract Suite: provider-agnostic write sessions.
"brain_write_session",
].toSorted(),
@@ -524,7 +529,7 @@ describe("stdio loop", () => {
// (Entity Truth & Self-Improving Dream Suite) = 69.
// + brain_labels / brain_tiers / brain_secrets / brain_maintenance
// (Write-Time Integrity & Governance Suite) = 73.
- expect(list.result.tools.length).toBe(73);
+ expect(list.result.tools.length).toBe(77);
});
test("returns parse error for invalid JSON", async () => {