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: vault portability + session economy - codec, sources dashboard, vault-map tokens, multi-vault profiles, graph export/import (#49)

Sol Aitkena085bfaf968e
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index aee84987..a4c29558 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.21.0",
+ "version": "0.22.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 914773a6..57140308 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.21.0",
+ "version": "0.22.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 88abf55a..e7a2a7bb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,59 @@ 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.22.0] - 2026-05-29
+
+Vault portability + session economy. A new `portability/` subsystem makes
+the brain portable across folder layouts and vaults, gives per-source
+visibility into signal intake, and adds a deterministic lossless codec
+for session prose - every new behaviour opt-in or no-op so a default
+install stays byte-identical.
+
+### Added
+
+- Deterministic, lossless session codec (`src/core/brain/portability/codec.ts`).
+ Pure `compress` / `expand` where `expand(compress(x)) === x` for
+ sentinel-free input; token savings come from reversibly collapsing whitespace and
+ blank-line runs behind a Private-Use-Area marker, with fenced/inline
+ code protected and structured tokens (URLs, paths, identifiers, version
+ numbers) preserved byte-for-byte. Opt-in on the signal store via
+ `writeSignal({ rawCodec })` / the `importSession` `rawCodec` option,
+ gated by a `_raw_codec` marker so `parseSignal` expands only marked
+ bodies; default off -> verbatim, byte-identical. Exposed as
+ `o2b brain codec --compress|--expand`.
+- `o2b brain sources` dashboard + `brain_sources` MCP tool
+ (`portability/sources.ts`). Read-only aggregation of inbox + processed
+ signals by (agent, source_type) with active/processed and
+ distinct-topic counts. (The upstream parallel-sync worker pool +
+ connection-budget warning are out of scope.)
+- Vault-map role tokens (`portability/role-tokens.ts`). Resolve
+ `{{role}}` tokens (`{{inbox}}`, `{{projects}}`, ...) to user content
+ folder names via an optional `Brain/_vault-map.yaml`, falling back to
+ built-in defaults; wired into scan-inline read paths and the
+ graph-import target. Mapped values are validated against traversal /
+ absolute / control characters. The FIXED Brain machinery layout is not
+ routed through the resolver. Inspect with `o2b vault map`.
+- Named multi-vault profiles (`portability/profiles.ts`). A registry in
+ `profiles.json` beside the config with `o2b vault profile list / create
+ / switch` and a `brain_switch_vault` MCP tool; activation is a pointer
+ (no symlinks). `resolveVault` consults the active profile before the
+ bare config `vault` key; with no registry, resolution is unchanged.
+- Vault graph export/import (`portability/graph.ts`). `o2b brain
+ graph-export` serialises the user's pages (wikilinks + typed relations)
+ to a stable, byte-identical `graph.json`; `o2b brain graph-import
+ --mode skip|overwrite|merge` reconstructs page stubs, every write
+ guarded by `ensureInsideVault`.
+
+### Notes
+
+- New MCP tools `brain_sources` and `brain_switch_vault` (tool count
+ 44 -> 46). New CLI verbs under `o2b brain` (codec, sources,
+ graph-export, graph-import) and `o2b vault` (profile, map).
+- Default-install behaviour is byte-identical: the codec is opt-in and
+ marker-gated, vault-map and profiles are no-ops without their files,
+ and graph import is operator-invoked.
+- Full suite green on merge: 2825 tests passing.
+
## [0.21.0] - 2026-05-29
Brain lifecycle suite. The nightly `dream` consolidation becomes an
@@ -3390,6 +3443,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.22.0]: https://github.com/itechmeat/open-second-brain/compare/v0.21.0...v0.22.0
[0.21.0]: https://github.com/itechmeat/open-second-brain/compare/v0.20.0...v0.21.0
[0.20.0]: https://github.com/itechmeat/open-second-brain/compare/v0.19.0...v0.20.0
[0.19.0]: https://github.com/itechmeat/open-second-brain/compare/v0.18.0...v0.19.0
diff --git a/README.md b/README.md
index dc5ed4fb..e76f75ac 100644
--- a/README.md
+++ b/README.md
@@ -112,7 +112,7 @@ The capabilities you actually feel day to day:
| 9 | Hybrid search that explains itself | `o2b search "<query>" --property type=decision --property status=open` — SQLite + FTS5 and an optional semantic layer, fused and then sharpened by a recall-quality suite: MMR diversity so near-duplicates do not crowd the top, link-graph traversal that surfaces notes one hop from a hit, entity-boosting for proper-noun precision, and header-anchored chunking so a mid-document chunk keeps its section context. Every result carries a `why_retrieved` breakdown of the layers that ranked it. |
| 10 | Pay Memory — audit every paid action | When the agent spends money (Solana-Foundation `pay`, third-party APIs) every receipt lands in `Brain/payments/<date>/`. Spending policy, approval gate, daily Telegram report. The agent never holds wallet keys. |
-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). 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.
+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.
## CLI
@@ -127,6 +127,9 @@ o2b brain retention --json # Recommendation-only lifecycle review
o2b brain monthly --month 2026-05 --json # Month-level Brain synthesis
o2b brain audit pref-foo --json # Full mutation trail for one preference
o2b brain morning-brief --json # Session-start summary (prefs, open questions, notes)
+o2b brain sources --json # Per-source signal dashboard
+o2b brain graph-export --out graph.json # Export the vault knowledge graph
+o2b vault profile switch work # Activate a named multi-vault profile
o2b brain agent-query --agent claude --json # Source-agent provenance query
o2b brain agent-diff --mode diff --agent claude --agent codex
o2b search "<query>" # FTS5 over the vault
diff --git a/docs/brainstorm/vault-portability-suite/cli-output/claude.md b/docs/brainstorm/vault-portability-suite/cli-output/claude.md
new file mode 100644
index 00000000..eb842ecb
--- /dev/null
+++ b/docs/brainstorm/vault-portability-suite/cli-output/claude.md
@@ -0,0 +1,37 @@
+### Variant 1: Five independent additive slices
+- **Approach**: Ship each feature as a standalone pure core module under `src/core/brain/` with its own CLI verb (and MCP tool where stated), sharing nothing but existing helpers (`vault.ts`, `extractWikilinks`, `resolveVault`). The session codec ships *only* as a reusable codec module + `o2b codec` CLI utility — it never touches the session-import path or signal `raw` body, so stored output is unchanged. Vault-map tokens resolve *only* user content folders (scan-inline `read_paths`, graph-import write target, search scope) and never the FIXED `*_REL` Brain constants; profiles activate via a pointer-in-config key (no symlinks). Sequence: dashboard → codec → graph export/import → vault-map → profiles, each independently mergeable.
+- **Trade-offs**:
+ - Pro: lowest blast radius — default install stays trivially byte-identical because no shared seam is touched and the codec/profile/token paths are all opt-in or read-only.
+ - Pro: each slice is independently testable and revertible; clean RED→GREEN per feature; easy CHANGELOG story.
+ - Pro: sidesteps both risky seams entirely (codec stays out of signals; tokens stay out of `paths.ts`).
+ - Con: codec delivers no automatic value to stored signals — operator must invoke it manually, so it's a utility not an integration.
+ - Con: some duplicated plumbing (frontmatter round-trip, path resolution) across slices; vault-map and graph-import each resolve folders independently.
+ - Con: vault-map utility is narrow (content folders only), which may underdeliver on the "tools resolve role tokens" framing.
+- **Complexity**: small
+- **Risk**: low
+
+### Variant 2: Shared portability subsystem (foundation-first)
+- **Approach**: Introduce one new subsystem `src/core/brain/portability/` holding deterministic primitives — a codec (tokenizer/compress/expand with a protected-span scanner for code/URLs/paths/identifiers/versions), a graph serializer over `collectExportRows` + `extractWikilinks` + typed relations, a `resolveRoleToken(map, token)` resolver, and a profile registry — then features 2–5 compose those primitives rather than reimplementing. The codec ships as module + `o2b codec` CLI *and* exposes an off-by-default `signals.raw_codec` flag that compresses the imported signal `raw` body and expands on read (round-trip-guarded; default install writes identical bytes because the flag is off). Vault-map tokens address user content folders only and the same resolver is reused by graph import/export and scan-inline; the FIXED Brain `*_REL` constants are untouched, preserving "one agent-owned Brain root." Profiles use pointer-in-config activation. Sequence: codec + graph primitives (pure, heavily unit-tested) → read-only dashboard → token resolver → profiles → graph export/import layered on the serializer.
+- **Trade-offs**:
+ - Pro: the riskiest seam (codec-in-signals) exists but is strictly opt-in and reuses the *same* round-trip-tested codec, so correctness is proven once and the default stays byte-identical.
+ - Pro: shared resolver means vault-map, graph-import target, and search scope agree by construction — no drift between three folder-resolution copies.
+ - Pro: token resolver deliberately scoped to user content folders avoids fighting `paths.ts`/the one-Brain-root design while still being a real abstraction.
+ - Pro: foundation-first sequencing front-loads the pure, deterministic, easily-tested code and defers anything stateful.
+ - Con: more up-front design of the shared module before any user-visible verb lands; a larger first PR-section if not carefully split.
+ - Con: the opt-in signal-codec path adds an expand-on-read branch in the signal reader that must be exercised in tests even though it's off by default.
+- **Complexity**: medium
+- **Risk**: low–medium
+
+### Variant 3: Deep integration with unified role-token indirection
+- **Approach**: Treat all five as one portability layer where the codec compresses session-imported signal `raw` bodies as part of the import pipeline (expanded on read everywhere the body is consumed), and the vault-map becomes a *general* role-token indirection that can resolve both user content folders *and*, behind a flag, relocate the Brain internal dirs by routing the `*_REL` constants through the resolver. Profiles activate via filesystem symlink so the resolved vault path is a stable target, and graph export/import is the canonical serialization for moving a vault between profiles. Sequence: build the resolver + profile/symlink machinery first (it underpins everything), then re-route `paths.ts` and the import codec through it.
+- **Trade-offs**:
+ - Pro: maximally capable — tokens are a single uniform abstraction, codec saves tokens on every stored signal automatically, profiles+graph export form a complete vault-migration story.
+ - Pro: least duplication; one indirection point for all path/role resolution.
+ - Con: directly attacks the two highest-risk seams — rerouting widely-consumed `*_REL` constants risks the "one agent-owned Brain root" design and every `ensureInsideVault` guard, and codec-on-import mutates the proven session-import path and changes on-disk signal bytes (breaks byte-identical default unless heavily gated, which contradicts the always-on framing).
+ - Con: symlink activation is fragile under Syncthing (symlinks sync inconsistently across devices/OSes), threatening the determinism/sync contract.
+ - Con: large, tightly-coupled change set; hard to split into one-version PR, hard to revert, wide test surface.
+- **Complexity**: large
+- **Risk**: high
+
+### Recommended: Variant 2
+**Rationale**: It captures the real integration value the task asks for — a codec that can actually compress stored signal bodies and a genuine role-token resolver shared across graph import/export — while keeping every risky behavior off-by-default so the Syncthing byte-identical contract and the "one agent-owned Brain root" design are never threatened. The shared `portability/` primitives eliminate the folder-resolution drift that Variant 1 risks, without rerouting the FIXED `paths.ts` constants or adopting symlink activation as Variant 3 does. Its foundation-first sequencing front-loads pure deterministic code (codec round-trip, graph serializer) that is cheapest to test under TDD and defers anything that touches existing on-disk output to a gated, reversible seam.
diff --git a/docs/brainstorm/vault-portability-suite/cli-output/prompt.md b/docs/brainstorm/vault-portability-suite/cli-output/prompt.md
new file mode 100644
index 00000000..cf99c753
--- /dev/null
+++ b/docs/brainstorm/vault-portability-suite/cli-output/prompt.md
@@ -0,0 +1,58 @@
+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
+
+Ship a "Vault portability + session economy" suite for Open Second Brain (OSB) - 5 deterministic, language-agnostic features. All features must be DETERMINISTIC (injectable clock where time matters; no Date.now()/Math.random() in pure code; byte-identical given inputs, because the vault is synced across devices via Syncthing) and LANGUAGE-AGNOSTIC (no hardcoded natural-language word lists / month names / per-language phrases; handle multilingual structurally).
+
+The 5 features:
+
+1. **Deterministic session codec (lossless round-trip).** A pure compress/expand codec for session-derived prose that reduces tokens while preserving code blocks, URLs, paths, identifiers, and version numbers byte-for-byte. Round-trip (expand(compress(x)) === x) must be guaranteed for structured content. Offline, no network, no LLM. The open question is the integration seam: OSB does NOT persist raw session bodies (it imports sessions into `Brain/inbox/` signals; the source JSONL is external). Candidates: a reusable codec module + CLI utility, and/or an opt-in transform on the session-imported signal `raw` body (expanded on read). Must keep the default install byte-identical.
+
+2. **`o2b brain sources` read-only dashboard.** Aggregate the brain's signals by source - agent / `source_type` / session origin (`session_ref`) - with counts (active inbox vs processed, distinct topics). Read-only; `--json`. NOTE: the upstream inspiration paired this with a parallel multi-source sync worker pool + connection-budget warning; the parallel/worker-pool part is OUT of scope (only the read-only dashboard ships), so the connection-budget warning is moot.
+
+3. **Vault-map token resolution.** Let tools resolve role tokens (e.g. `{{inbox}}`, `{{projects}}`) to user folder names via an optional map, falling back to built-in defaults when absent. The hard constraint: OSB's Brain machinery layout is FIXED via module-level constants in `src/core/brain/paths.ts` (`BRAIN_INBOX_REL`, `BRAIN_PREFERENCES_REL`, ...) consumed widely, and the v0.11.0 design is "one agent-owned Brain root". So the variant must decide WHAT the tokens address - the user's content folders (scan-inline read_paths / where graph-import writes / search scope) vs. relocating the Brain internal dirs - and how invasive that is.
+
+4. **Named multi-vault profiles + switching.** OSB resolves the vault path centrally via `resolveVault(configPath)` (`VAULT_DIR` env -> config.yaml `vault` key). Add a registry of named profiles (name -> vault path + optional per-profile settings), a switch operation, and list/create commands, exposed via CLI and an MCP tool. Symlink-based or pointer-in-config activation are both candidates.
+
+5. **Vault graph export/import via graph.json.** Extend `src/core/brain/export.ts` (which already has `exportPreferencesJson` / `collectExportRows`) to a full vault-graph export (pages + wikilinks + typed relationships) and an importer that reconstructs page stubs with correct frontmatter and wikilinks, with three conflict modes: skip (default) / overwrite / merge. Deterministic, idempotent on re-import with skip.
+
+# Project context
+
+Open Second Brain - TypeScript on Bun. A single-user, file-based "second brain": a vault of markdown files under `Brain/` (preferences, signals/inbox, retired, log) operated by AI agents through an `o2b` CLI and an MCP server. Byte-identical determinism matters for the Syncthing sync contract.
+
+Recent releases (newest first): v0.21.0 Brain lifecycle suite (mutation audit, multi-phase dream, reconcile domains, morning brief, temporal extraction, heal enrichment); v0.20.0 Recall and ranking quality; v0.17.0 Brain Lifecycle Review Suite; v0.14.0 Semantic Brain Health.
+
+Key code facts (verified):
+- Vault path resolution is centralized: `src/core/config.ts` `resolveVault(configPath)` reads `VAULT_DIR` env then config.yaml `vault`; CLI wraps it via `src/cli/brain/helpers.ts` `resolveBrainVault`. The MCP server takes a single vault path (`src/mcp/server.ts:53`).
+- Brain folder layout is FIXED via constants in `src/core/brain/paths.ts` (`BRAIN_ROOT_REL = "Brain"`, `BRAIN_INBOX_REL`, `BRAIN_PREFERENCES_REL`, `BRAIN_RETIRED_REL`, `BRAIN_LOG_REL`, ...); `brainDirs(vault)` composes absolute paths from them; many modules import the `*_REL` constants directly. `ensureInsideVault` guards every constructed path against traversal.
+- `BrainSignal` carries optional `source_type` (`BrainSignalSourceType`), `session_ref`, and `agent` - enough to aggregate a sources dashboard from existing on-disk signals (no new store needed).
+- Session import: `src/core/brain/sessions/import.ts` (`importSession`) + adapters (`claude.ts`, `codex.ts`, `hermes.ts`) + `registry.ts`; sessions become signals, raw bodies are not persisted beyond the signal `raw` field.
+- Export seam: `src/core/brain/export.ts` `exportPreferencesJson` / `collectExportRows` / `exportPreferencesLlmsTxt`. Frontmatter parse/format via `src/core/vault.ts`; wikilink extraction via `extractWikilinks`; typed relations exist (v0.19.0: `related`/`extends`/`contradicts`/`superseded_by`).
+- CLI verbs: one file per verb under `src/cli/brain/verbs/`, dispatched from `src/cli/brain.ts`; shared output helpers in `src/cli/output.ts`. MCP tools registered in `src/mcp/brain-tools.ts` (44 tools currently). Config keys resolved in `src/core/brain/policy.ts` / `src/core/config.ts`.
+- Tests: Bun test runner under `tests/`. TDD: watch RED before GREEN.
+
+Conventions / constraints:
+- Pure deterministic modules; inject the clock; byte-identical output for Syncthing.
+- New behaviour OFF or no-op by default where it could change existing on-disk output; a default install must stay byte-identical.
+- Additive schema/config migrations only; tolerate unknown future values on read.
+- NO hardcoded natural-language word lists / month names / per-language phrases.
+- No new external runtime dependencies unless unavoidable (the session codec must be pure TS, no native deps).
+- Do NOT fight the "one agent-owned Brain root" design; do NOT rewrite the proven session-import or dream internals.
+- One PR = one CHANGELOG version; full project name in public artifacts; no AI-authorship markers in public prose.
+
+# Required output format
+
+Produce exactly 3 distinct architectural variants. For each variant:
+
+### Variant N: <short name>
+- **Approach**: 2-3 sentences describing the variant (esp. how it sequences/sca­ffolds the 5 features and the riskiest seams - the session-codec integration point and the vault-map scope).
+- **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/vault-portability-suite/design.md b/docs/brainstorm/vault-portability-suite/design.md
new file mode 100644
index 00000000..c0dbeb13
--- /dev/null
+++ b/docs/brainstorm/vault-portability-suite/design.md
@@ -0,0 +1,134 @@
+# Vault portability + session economy - deterministic primitives and opt-in seams
+
+**Status:** draft
+**Author:** feature-release-playbook
+**Audience:** implementation
+
+## Problem statement
+
+Open Second Brain operates on a single, fixed-layout vault and imports agent
+sessions sequentially with no compression, no per-source visibility, and no way
+to move a whole knowledge graph between vaults or adapt to a non-standard folder
+layout. This suite adds five deterministic, language-agnostic capabilities -
+behind a shared `portability/` subsystem - that make the brain portable and its
+session intake economical, while keeping a default install byte-identical.
+
+## Scope
+
+Five features (chosen set; implemented one-by-one via TDD), built on a shared
+`src/core/brain/portability/` subsystem so folder-resolution and serialization
+logic exist once:
+
+1. **Deterministic session codec** - pure `compress` / `expand` with a
+ protected-span scanner that preserves code fences, inline code, URLs, paths,
+ identifiers, and version numbers byte-for-byte; `expand(compress(x)) === x`.
+ Ships as a module + `o2b brain codec` CLI utility, AND as an opt-in
+ `signals.raw_codec` transform on the session-imported signal `raw` body
+ (compressed on write, expanded on read, gated by a stored `_raw_codec`
+ marker). Default off -> byte-identical.
+2. **`o2b brain sources` dashboard** - read-only aggregation of signals by
+ agent / `source_type` / session origin (`session_ref`), with active-inbox vs
+ processed counts and distinct-topic counts. `--json`; also a `brain_sources`
+ MCP tool. The parallel worker-pool + connection-budget warning from the
+ upstream inspiration are OUT of scope.
+3. **Vault-map role-token resolution** - `resolveRoleToken(map, token)` over an
+ optional map file resolving `{{inbox}}`-style tokens to USER content folder
+ names, with built-in defaults when absent. Scoped to user content surfaces
+ (scan-inline read paths, graph-import write target); the FIXED Brain `*_REL`
+ constants and the one-agent-owned-root design are untouched.
+4. **Named multi-vault profiles** - a profile registry (name -> vault path +
+ optional settings) with list / create / switch, activated by a
+ pointer-in-config key (NO symlinks - they sync inconsistently under
+ Syncthing). CLI `o2b vault profile ...` + a `brain_switch_vault` MCP tool.
+5. **Vault graph export/import** - a graph serializer over all vault pages
+ (`listVaultPages`) + `extractWikilinks` + typed-relation frontmatter
+ (`related`/`extends`/`contradicts`/`superseded_by`) producing `graph.json`, and an importer
+ that reconstructs page stubs with frontmatter + wikilinks under three
+ conflict modes: skip (default) / overwrite / merge. Deterministic; idempotent
+ on re-import with skip.
+
+## Out of scope
+
+- Copilot / Pi session adapters (deferred; not in this PR).
+- Parallel multi-source sync worker pool + connection-budget warning (the
+ read-only sources dashboard ships; the concurrency engine does not).
+- Relocating the Brain internal layout (`Brain/inbox` etc. stay fixed); vault-map
+ addresses user content folders only.
+- Symlink-based profile activation (pointer-in-config only).
+- Rewriting the proven session-import or dream internals.
+
+## Chosen approach
+
+**Variant 2 - shared portability subsystem, foundation-first.** A new
+`src/core/brain/portability/` holds the pure primitives (codec, graph
+serializer, role-token resolver, profile registry); the user-visible features
+compose them. Pure, deterministic code is front-loaded and unit-tested under
+TDD; anything that touches existing on-disk output is a gated, reversible seam.
+
+## Design decisions
+
+- **Codec is pure + opt-in for storage.** The codec module guarantees
+ round-trip on structured content. Its only on-disk effect is gated behind
+ `signals.raw_codec` (default off); a compressed signal body carries a
+ `_raw_codec: <algoVersion>` frontmatter marker, so `parseSignal` only routes
+ through `expand` when the marker is present. Every signal written by a default
+ install lacks the marker and takes the unchanged read path -> byte-identical.
+- **Protected spans, not language rules.** The codec compresses only inter-token
+ whitespace/prose structure; code fences, inline code, URLs, filesystem paths,
+ dotted/snake/camel identifiers, and semver-like version numbers are detected
+ structurally (regex over shape, never word lists) and copied verbatim.
+- **Vault-map addresses user content only.** `paths.ts` `*_REL` constants are
+ NOT rerouted. The resolver reads an optional `Brain/_vault-map.yaml`
+ (token -> folder); absent or unknown token -> built-in default. The same
+ resolver is reused by scan-inline read paths and the graph-import target so
+ the three never drift.
+- **Profiles are a pointer in config.** A `profiles:` registry in config
+ (name -> {vault, ...}) plus an `active_profile` pointer; `switch` rewrites the
+ pointer only. `resolveVault` consults the active profile before the bare
+ `vault` key (back-compat: no profiles -> existing behaviour). No symlinks.
+- **Graph format is additive + deterministic.** `graph.json` is a sorted,
+ stable serialization (pages sorted by id, links sorted) so re-export is
+ byte-identical. Import writes page stubs via the existing atomic frontmatter
+ writer; skip mode never overwrites, merge unions wikilinks/relations, overwrite
+ replaces. Importer never touches Brain machinery files.
+- **Sources dashboard is a pure projection.** It scans inbox + processed signals
+ (already on disk) and groups by (agent, source_type, session_ref); no new
+ store, no writes.
+
+## File changes
+
+New subsystem `src/core/brain/portability/`:
+- `codec.ts` - `compress`, `expand`, `CODEC_VERSION`, protected-span scanner.
+- `role-tokens.ts` - `resolveRoleToken`, `loadVaultMap`, default token table.
+- `graph.ts` - `exportVaultGraph` (over `listVaultPages` + `extractWikilinks` + typed-relation frontmatter), `importVaultGraph` (+ conflict modes), types.
+- `profiles.ts` - profile registry load/save, `switchProfile`, `listProfiles`.
+- `sources.ts` - `aggregateSources` pure projection over scanned signals.
+
+Modified:
+- `src/core/brain/signal.ts` - opt-in codec expand-on-read gated by `_raw_codec`.
+- `src/core/brain/sessions/import.ts` - opt-in codec compress on raw write.
+- `src/core/config.ts` - `resolveVault` consults active profile; profile keys.
+- `src/core/brain/policy.ts` / config - `signals.raw_codec` flag (default off).
+- CLI: `src/cli/brain/verbs/{codec,sources,graph-export,graph-import}.ts`,
+ `src/cli/vault/verbs/{profile,map}.ts` (or `src/cli/brain/verbs/`), wired in
+ `src/cli/brain.ts` / `src/cli/vault.ts` + help-text.
+- MCP: `src/mcp/brain-tools.ts` - `brain_sources`, `brain_switch_vault`
+ (tool count 44 -> 46) + `instructions.ts`.
+- Docs: `README.md`, `docs/how-it-works.md`, `docs/cli-reference.md`,
+ `docs/mcp.md`, `CHANGELOG.md`.
+
+## Risks and open questions
+
+- **Codec round-trip correctness.** A codec bug would corrupt opt-in-compressed
+ signal bodies. Mitigation: exhaustive round-trip property tests on structured
+ fixtures; gated by `_raw_codec` marker so only opt-in writes are affected; the
+ default read path is untouched.
+- **Profile switch + config writes.** `switch` rewrites an operator-owned config
+ key only; never moves vault data. `resolveVault` stays backward-compatible
+ when no profiles are defined.
+- **Byte-identical default.** Codec off, no vault-map file, no profiles, graph
+ import not run -> every existing surface is byte-identical. The QA phase must
+ assert a no-op default run produces no new files and unchanged signal bytes.
+- **Graph import safety.** Import writes only under the resolved content target,
+ via `ensureInsideVault`; skip mode is the default; Brain machinery files are
+ never targeted.
diff --git a/docs/brainstorm/vault-portability-suite/plan.md b/docs/brainstorm/vault-portability-suite/plan.md
new file mode 100644
index 00000000..05c7b079
--- /dev/null
+++ b/docs/brainstorm/vault-portability-suite/plan.md
@@ -0,0 +1,60 @@
+# Vault portability + session economy - implementation plan
+
+Foundation-first: pure primitives land before the surfaces that compose them.
+Each task is RED -> GREEN -> REFACTOR with its own commit. Every task keeps a
+default install (codec off, no vault-map, no profiles) byte-identical.
+
+## Task 1: Deterministic session codec primitive
+- **Files**: `src/core/brain/portability/codec.ts`, `tests/core/brain/portability/codec.test.ts`
+- **Acceptance**: `compress(text)` / `expand(text)` are pure; `expand(compress(x)) === x` for fixtures containing code fences, inline code, URLs, filesystem paths, dotted/snake/camel identifiers, and semver version numbers (all preserved byte-for-byte); structural detection only (no language word lists); `CODEC_VERSION` exported; empty/whitespace inputs round-trip; never throws on malformed input.
+- **Depends on**: none
+
+## Task 2: Role-token resolver + vault-map loader
+- **Files**: `src/core/brain/portability/role-tokens.ts`, `tests/core/brain/portability/role-tokens.test.ts`
+- **Acceptance**: `resolveRoleToken(map, token)` resolves `{{inbox}}`-style tokens to folder names; `loadVaultMap(vault)` reads optional `Brain/_vault-map.yaml` and returns a token->folder map; an absent file or unknown token falls back to a built-in default; resolution is deterministic and rejects path traversal in mapped values.
+- **Depends on**: none
+
+## Task 3: Vault graph serializer (export)
+- **Files**: `src/core/brain/portability/graph.ts`, `tests/core/brain/portability/graph-export.test.ts`
+- **Acceptance**: `exportVaultGraph(vault)` walks all vault pages via `listVaultPages`, extracts wikilinks (`extractWikilinks`) and typed-relation frontmatter, and returns a stable, sorted graph (pages by id/path, links sorted); re-export is byte-identical; pure read-only.
+- **Depends on**: none
+
+## Task 4: Vault graph importer (conflict modes)
+- **Files**: `src/core/brain/portability/graph.ts` (`importVaultGraph`), `tests/core/brain/portability/graph-import.test.ts`
+- **Acceptance**: `importVaultGraph(vault, graph, {mode})` reconstructs page stubs (frontmatter + wikilinks) via the atomic writer; `skip` (default) never overwrites an existing page; `overwrite` replaces; `merge` unions wikilinks/relations; writes go through `ensureInsideVault`; idempotent under skip; never targets Brain machinery files.
+- **Depends on**: Task 3
+
+## Task 5: Sources dashboard projection
+- **Files**: `src/core/brain/portability/sources.ts`, `tests/core/brain/portability/sources.test.ts`
+- **Acceptance**: `aggregateSources(vault)` scans inbox + processed signals and groups by (agent, source_type, session_ref) with active/processed counts and distinct-topic counts; pure read-only; deterministic ordering.
+- **Depends on**: none
+
+## Task 6: Profile registry + vault resolution
+- **Files**: `src/core/brain/portability/profiles.ts`, `src/core/config.ts` (`resolveVault` consults active profile), `tests/core/brain/portability/profiles.test.ts`, `tests/core/config.*`
+- **Acceptance**: `listProfiles` / `createProfile` / `switchProfile` operate on a `profiles:` + `active_profile` config registry; `switch` rewrites only the pointer; `resolveVault` returns the active profile's vault when set, else the bare `vault` key (back-compat: no profiles -> unchanged); no symlinks.
+- **Depends on**: none
+
+## Task 7: Opt-in codec integration into session import + read
+- **Files**: `src/core/brain/sessions/import.ts`, `src/core/brain/signal.ts`, `src/core/brain/policy.ts` / config (`signals.raw_codec`, default off), `tests/core/brain.sessions.codec.test.ts`
+- **Acceptance**: with `signals.raw_codec` on, a session-imported signal's `raw` is stored compressed with a `_raw_codec: <version>` marker; `parseSignal` expands only when the marker is present; with the flag off (default) the import + parse paths are byte-identical to pre-suite; round-trip verified end-to-end.
+- **Depends on**: Task 1
+
+## Task 8: Vault-map wiring into content surfaces
+- **Files**: scan-inline read-path resolution + graph-import target (`src/core/brain/inline-scan.ts` or callers, `portability/graph.ts`), `tests/core/brain/portability/role-tokens-wiring.test.ts`
+- **Acceptance**: scan-inline read paths and the graph-import write target resolve `{{token}}` values via the shared resolver; absent map -> current behaviour unchanged; the FIXED Brain `*_REL` constants are not routed through the resolver.
+- **Depends on**: Tasks 2, 4
+
+## Task 9: CLI verbs
+- **Files**: `src/cli/brain/verbs/{codec,sources,graph-export,graph-import}.ts`, `src/cli/vault/verbs/{profile,map}.ts`, `src/cli/brain.ts`, `src/cli/vault.ts`, help-text, `tests/cli/*`
+- **Acceptance**: `o2b brain codec --compress|--expand`, `o2b brain sources [--json]`, `o2b brain graph-export`, `o2b brain graph-import --mode skip|overwrite|merge`, `o2b vault profile list|create|switch`, `o2b vault map [show]`; each read-only verb is side-effect-free; help-text added.
+- **Depends on**: Tasks 1-6
+
+## Task 10: MCP tools
+- **Files**: `src/mcp/brain-tools.ts`, `src/mcp/instructions.ts`, `tests/mcp/mcp.test.ts` (count 44 -> 46)
+- **Acceptance**: `brain_sources` (read-only) and `brain_switch_vault` tools registered; tool count 44 -> 46; instructions updated.
+- **Depends on**: Tasks 5, 6
+
+## Task 11: QA, docs, version bump, release prep
+- **Files**: `README.md`, `docs/how-it-works.md`, `docs/cli-reference.md`, `docs/mcp.md`, `CHANGELOG.md`, `package.json` + manifests (sync-version)
+- **Acceptance**: full `bun run validate` green; default-install byte-identical asserted (codec off, no vault-map, no profiles); docs describe all 5 features; one `[0.22.0]` CHANGELOG entry; version synced across manifests.
+- **Depends on**: Tasks 1-10
diff --git a/docs/brainstorm/vault-portability-suite/variants.md b/docs/brainstorm/vault-portability-suite/variants.md
new file mode 100644
index 00000000..cb4d3f5b
--- /dev/null
+++ b/docs/brainstorm/vault-portability-suite/variants.md
@@ -0,0 +1,45 @@
+# Vault portability + session economy - brainstorm audit trail
+
+Consultant: Claude Code (`claude -p`), primary. Exit 0, three parseable
+variants; the Codex fallback was therefore not run. Raw output at
+`cli-output/claude.md`; filled prompt at `cli-output/prompt.md`.
+
+## Variants (verbatim summary)
+
+### Variant 1: Five independent additive slices
+- **Approach**: Each feature a standalone pure module + its own verb, sharing only existing helpers. The codec ships ONLY as a module + CLI utility (never touches session import or signal `raw`). Vault-map tokens resolve user content folders only; profiles activate via pointer-in-config. Each slice independently mergeable.
+- **Trade-offs**: Pro - lowest blast radius, default byte-identical by construction, sidesteps both risky seams, easy per-feature TDD. Con - codec delivers no automatic value to stored signals (utility, not integration); duplicated folder-resolution plumbing across slices; vault-map underdelivers.
+- **Complexity**: small. **Risk**: low.
+
+### Variant 2: Shared portability subsystem (foundation-first)
+- **Approach**: One `src/core/brain/portability/` subsystem of deterministic primitives (codec with protected-span scanner, graph serializer over `collectExportRows` + `extractWikilinks` + typed relations, `resolveRoleToken`, profile registry); features 2-5 compose them. Codec ships as module + CLI AND an off-by-default `signals.raw_codec` flag (compress imported `raw`, expand on read, round-trip-guarded, gated by a stored marker). Vault-map addresses user content folders only; FIXED Brain `*_REL` untouched. Profiles via pointer-in-config. Foundation-first sequencing front-loads pure code.
+- **Trade-offs**: Pro - delivers real integration value with the risky codec-in-signals seam strictly opt-in and round-trip-tested once; shared resolver prevents folder-resolution drift; token resolver scoped to user content avoids fighting `paths.ts`; pure deterministic code front-loaded for TDD. Con - more up-front shared-module design; the opt-in expand-on-read branch in the signal reader must be tested even though off by default.
+- **Complexity**: medium. **Risk**: low-medium.
+
+### Variant 3: Deep integration with unified role-token indirection
+- **Approach**: One portability layer where the codec compresses signal `raw` as part of import (expanded on read everywhere), vault-map becomes a general role-token indirection that can relocate Brain internal dirs by routing the `*_REL` constants, profiles activate via filesystem symlink, graph export/import is the canonical migration format.
+- **Trade-offs**: Pro - maximally capable, least duplication, complete migration story. Con - attacks both highest-risk seams (rerouting widely-consumed `*_REL` threatens the one-Brain-root design + every `ensureInsideVault` guard; codec-on-import mutates the proven import path and changes on-disk bytes); symlinks sync inconsistently under Syncthing (breaks the determinism contract); large tightly-coupled change, hard to split/revert.
+- **Complexity**: large. **Risk**: high.
+
+### Consultant recommendation: Variant 2
+Captures the real integration value (codec that can compress stored signal
+bodies, a genuine shared role-token resolver) while keeping every risky
+behaviour off-by-default so the Syncthing byte-identical contract and the
+one-agent-owned-Brain-root design are never threatened; eliminates the
+folder-resolution drift Variant 1 risks without rerouting `paths.ts` or adopting
+symlink activation as Variant 3 does; foundation-first sequencing front-loads
+cheap-to-test pure code.
+
+## Orchestrator decision: Variant 2 (agree with consultant)
+
+Adopted without override. Variant 2 is the only option that delivers the
+integration value the operator's chosen scope implies (a codec that actually
+compresses stored session bodies, a resolver shared across graph import/export
+and scan) while keeping the determinism + sync contract and the one-Brain-root
+architecture intact. Variant 1's codec-as-utility underdelivers and duplicates
+folder resolution; Variant 3 directly attacks the two seams the project's design
+forbids (rerouting the FIXED `*_REL` constants; symlink activation fragile under
+Syncthing). The single cost of Variant 2 - an expand-on-read branch in
+`parseSignal` - is isolated to opt-in-written signals via a stored `_raw_codec`
+marker, so the default read path stays byte-identical and is covered by
+exhaustive round-trip tests.
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index ee4bacb0..7f4de232 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -51,6 +51,10 @@ o2b brain health Semantic-health report (since v0.14.0): contradict
o2b brain history Render a preference's edit-history timeline (since v0.14.0): one entry per content mutation (principle / scope / status before -> after)
o2b brain audit Render a preference's full mutation audit trail (since v0.21.0): create / promote / update / retire / merge with agent, reason, revision + content-hash before/after. ret- or bare-slug arg resolves to the same trail
o2b brain morning-brief Read-only session-start summary (since v0.21.0): top confirmed preferences, recent reconcile open questions, recent notes; bounded by --max-chars-per-memory / --max-total-chars; --top-k / --lookback-days
+o2b brain codec Deterministic lossless session codec (since v0.22.0): --compress | --expand over stdin or --in <file>; structured content preserved byte-for-byte
+o2b brain sources Read-only dashboard of signals by (agent, source_type) (since v0.22.0): active/processed + distinct-topic counts; --json
+o2b brain graph-export Serialise the vault knowledge graph (pages, wikilinks, typed relations) to a stable graph.json (since v0.22.0): stdout or --out <file>
+o2b brain graph-import Reconstruct vault page stubs from a graph.json (since v0.22.0): --mode skip|overwrite|merge; vault-guarded writes
o2b brain backlinks List inbound references to a Brain artifact id
o2b brain mcp-landscape List MCP servers configured across the vault (since v0.19.0): name, source file, packages, required env-var names (values never read)
o2b brain scan-inline Capture `@osb` markers from folders listed under `notes.read_paths` in _brain.yaml
@@ -90,6 +94,8 @@ Single exclusion policy for every vault walker.
```text
o2b vault status Walks the vault under the active policy; reports include / exclude counts and which rules fired
o2b vault inspect <relpath> Point-check one vault-relative path; reports matched rule, source, and whether the path exists on disk
+o2b vault profile <sub> Manage named multi-vault profiles (since v0.22.0): list | create <name> <vault> | switch <name>; pointer-based activation in profiles.json
+o2b vault map [show] Print the resolved vault-map role tokens -> folders (since v0.22.0), merging an optional Brain/_vault-map.yaml over defaults; read-only
```
## Discipline (daily logging cron)
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 2be55262..d8bcf99d 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -309,6 +309,30 @@ labels over the existing seams, so every invariant above still holds.
pages outside the Brain root. Disabled by default so the install stays
byte-identical.
+### Vault portability + session economy (v0.22.0)
+
+A `portability/` subsystem of deterministic primitives, all opt-in or
+no-op by default:
+
+- **Session codec.** A pure lossless `compress`/`expand` (`expand(compress(x))
+ === x` for all input). Token savings come from reversibly collapsing
+ whitespace/blank-line runs behind a Private-Use-Area marker; code and
+ structured tokens are preserved byte-for-byte. Opt-in on the signal
+ store (gated by a `_raw_codec` marker the reader keys off) and exposed as
+ `o2b brain codec`.
+- **Sources dashboard.** `o2b brain sources` / `brain_sources` aggregate
+ the brain's signals by (agent, source_type) - a read-only projection.
+- **Vault-map tokens.** `{{role}}` tokens resolve to user content folders
+ via an optional `Brain/_vault-map.yaml` (defaults otherwise), wired into
+ scan-inline read paths and graph import. The fixed `Brain/*` layout is
+ never routed through the resolver.
+- **Multi-vault profiles.** A `profiles.json` registry beside the config;
+ `resolveVault` prefers the active profile over the bare `vault` key.
+ Activation is a pointer (no symlinks - they sync inconsistently).
+- **Graph export/import.** A stable `graph.json` of the user's pages
+ (wikilinks + typed relations) and an importer with skip/overwrite/merge
+ modes, every write guarded by `ensureInsideVault`.
+
## Confidence formula
Confidence is computed for every active preference on every dream
diff --git a/docs/mcp.md b/docs/mcp.md
index cf2174b8..9a4f85c6 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -18,7 +18,7 @@ in Open Second Brain depends on the MCP server being running.
## Tool Highlights
-The full server currently advertises 44 tools. The table below highlights the
+The full server currently advertises 46 tools. The table below highlights the
operator-facing core, agent-source, health, and Pay Memory tools; the full
surface also includes Brain writer, review, query, temporal, link-graph, and
search tools. In Claude Code, that full schema can push MCP definitions beyond
@@ -36,6 +36,8 @@ writer split below for the always-loaded writer subset.
| `brain_agent_diff` | Read-only comparison between source agents using browse/search/diff/map modes over the same provenance foundation. | — |
| `brain_audit` | Read-only per-preference mutation trail (create / promote / update / retire / merge) with agent, reason, revision + content-hash before/after. | `pref_id` |
| `brain_morning_brief` | Read-only session-start summary: top confirmed preferences, recent reconcile open questions, recent notes; character-budgeted. | — |
+| `brain_sources` | Read-only dashboard of signals grouped by (agent, source_type) with active/processed and distinct-topic counts. | — |
+| `brain_switch_vault` | Activate a named vault profile; the change takes effect on the next server launch. | `name` |
| `payment_memory_init` | Bootstrap `Brain/payments/{policies,assets,drafts,reports}/ (+ dated YYYY-MM-DD receipt subdirs)` and write the spending policy template. | — |
| `payment_receipt_append` | Save a Markdown receipt for one paid API call. `raw_output` is redacted before persisting. | `service`, `status`, `reason` |
| `asset_capture` | Save a Markdown note for an asset produced by a paid call, linked to its receipt. | `title`, `service`, `result_url` |
@@ -261,7 +263,7 @@ server to your Codex MCP config the same way as Hermes.
The plugin's `.mcp.json` ships **two** MCP-server entries:
-- `open-second-brain` - the full surface (44 tools, including `brain_health`, `brain_mcp_landscape`, `brain_agent_query`, `brain_agent_diff`, `brain_pinned_context`, `brain_pre_compress_pack`, `brain_audit`, and `brain_morning_brief`); subject to Claude Code's `MCPSearch` tool-search deferral when MCP definitions push the system prompt past 10% of the context window.
+- `open-second-brain` - the full surface (46 tools, including `brain_health`, `brain_mcp_landscape`, `brain_agent_query`, `brain_agent_diff`, `brain_pinned_context`, `brain_pre_compress_pack`, `brain_audit`, `brain_morning_brief`, `brain_sources`, and `brain_switch_vault`); subject to Claude Code's `MCPSearch` tool-search deferral when MCP definitions push the system prompt past 10% of the context window.
- `open-second-brain-writer` - a minimal always-loaded surface of five tools: `brain_feedback`, `brain_apply_evidence`, `brain_note`, `brain_pinned_context` (writers) and `brain_context` (read-only pull-bootstrap of `Brain/active.md` plus pinned context, v0.16.0). The agent records taste signals, evidence events, milestone notes, and current-task pinned facts - and fetches the active rule digest at session start in runtimes without a SessionStart hook - without a ToolSearch round-trip on every session boot.
Both servers reuse the same backing CLI (`o2b mcp --scope writer` vs the default `--scope full`). Handlers are byte-identical; the writer-mode instructions text explicitly tells the agent to prefer the writer copy over any duplicate the full server still exposes (both call the same code path).
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 0090646a..e3f865b0 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.21.0",
+ "version": "0.22.0",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index 31c214f5..91600f50 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.21.0",
+ "version": "0.22.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 b47e9835..88c9fbf8 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.21.0"
+version: "0.22.0"
description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 3d0fd5ec..17800ca5 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.21.0",
+ "version": "0.22.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 9a4b292a..734fb296 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.21.0"
+version: "0.22.0"
description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."
author: "OpenSecondBrain contributors"
kind: standalone
diff --git a/pyproject.toml b/pyproject.toml
index a0bc7bbc..0b68ed28 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.21.0"
+version = "0.22.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 36537a49..b803f9aa 100644
--- a/src/cli/brain.ts
+++ b/src/cli/brain.ts
@@ -33,6 +33,10 @@ import {
cmdBrainHistory,
cmdBrainAudit,
cmdBrainMorningBrief,
+ cmdBrainCodec,
+ cmdBrainSources,
+ cmdBrainGraphExport,
+ cmdBrainGraphImport,
cmdBrainBacklinks,
cmdBrainMcpLandscape,
cmdBrainMerge,
@@ -131,6 +135,14 @@ export async function handleBrainSubcommand(
return await cmdBrainAudit(rest);
case "morning-brief":
return await cmdBrainMorningBrief(rest);
+ case "codec":
+ return await cmdBrainCodec(rest);
+ case "sources":
+ return await cmdBrainSources(rest);
+ case "graph-export":
+ return await cmdBrainGraphExport(rest);
+ case "graph-import":
+ return await cmdBrainGraphImport(rest);
case "backlinks":
return await cmdBrainBacklinks(rest);
case "mcp-landscape":
diff --git a/src/cli/brain/help-text.ts b/src/cli/brain/help-text.ts
index 2cc8e969..f3971ba4 100644
--- a/src/cli/brain/help-text.ts
+++ b/src/cli/brain/help-text.ts
@@ -40,6 +40,10 @@ Brain verbs (observing memory):
history Render a preference's edit-history timeline
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)
+ sources Read-only dashboard of signals by (agent, source_type)
+ graph-export Serialise the vault knowledge graph to graph.json
+ graph-import Reconstruct vault pages from graph.json (--mode skip|overwrite|merge)
backlinks List inbound references to a Brain artifact id
mcp-landscape List MCP servers configured across the vault (packages, env names)
scan-inline Capture @osb markers from folders listed under notes.read_paths in _brain.yaml
@@ -173,6 +177,22 @@ export const VERB_HELP: Record<string, string> = {
"update / retire / merge) with agent, reason, and revision + content-hash\n" +
"before/after. A ret- or bare-slug argument resolves to the same trail.\n" +
"Read-only.\n",
+ codec:
+ "usage: o2b brain codec --compress | --expand [--in <file>]\n" +
+ "Run the deterministic, lossless session codec over stdin (or --in <file>)\n" +
+ "and print the result to stdout. Read-only; structured content preserved.\n",
+ sources:
+ "usage: o2b brain sources [--vault <path>] [--json]\n" +
+ "Read-only dashboard of the brain's signals grouped by (agent, source_type)\n" +
+ "with active/processed and distinct-topic counts.\n",
+ "graph-export":
+ "usage: o2b brain graph-export [--vault <path>] [--out <file>]\n" +
+ "Serialise the vault knowledge graph (pages, wikilinks, typed relations) to a\n" +
+ "stable graph.json. Prints to stdout, or writes to --out. Read-only.\n",
+ "graph-import":
+ "usage: o2b brain graph-import <file> [--mode skip|overwrite|merge] [--vault <path>] [--json]\n" +
+ "Reconstruct vault page stubs from a graph.json. skip (default) never\n" +
+ "overwrites; merge unions wikilinks/relations; writes are vault-guarded.\n",
"morning-brief":
"usage: o2b brain morning-brief [--vault <path>] [--json] [--top-k <n>]\n" +
" [--lookback-days <n>] [--max-chars-per-memory <n>] [--max-total-chars <n>]\n" +
diff --git a/src/cli/brain/verbs/codec.ts b/src/cli/brain/verbs/codec.ts
new file mode 100644
index 00000000..4e16b62f
--- /dev/null
+++ b/src/cli/brain/verbs/codec.ts
@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+
+import { compress, expand } from "../../../core/brain/portability/codec.ts";
+import { fail, parse } from "../helpers.ts";
+
+/**
+ * `o2b brain codec --compress|--expand [--in <file>]` - run the
+ * deterministic session codec over stdin (or `--in <file>`) and print
+ * the result to stdout. Read-only; does not touch the vault.
+ */
+export async function cmdBrainCodec(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, {
+ compress: { type: "boolean" },
+ expand: { type: "boolean" },
+ in: { type: "string" },
+ });
+ if (flags["compress"] === flags["expand"]) {
+ return fail("usage: o2b brain codec --compress | --expand [--in <file>]");
+ }
+
+ let input: string;
+ try {
+ input =
+ typeof flags["in"] === "string"
+ ? readFileSync(flags["in"], "utf8")
+ : await Bun.stdin.text();
+ } catch (exc) {
+ return fail(`codec: failed to read input: ${(exc as Error).message ?? exc}`);
+ }
+
+ try {
+ process.stdout.write(flags["compress"] ? compress(input) : expand(input));
+ } catch (exc) {
+ return fail(`codec failed: ${(exc as Error).message ?? exc}`);
+ }
+ return 0;
+}
diff --git a/src/cli/brain/verbs/graph-export.ts b/src/cli/brain/verbs/graph-export.ts
new file mode 100644
index 00000000..2b964c65
--- /dev/null
+++ b/src/cli/brain/verbs/graph-export.ts
@@ -0,0 +1,34 @@
+import { defaultConfigPath } from "../../../core/config.ts";
+import { atomicWriteFileSync } from "../../../core/fs-atomic.ts";
+import { exportVaultGraph } from "../../../core/brain/portability/graph.ts";
+import { fail, parse, resolveBrainVault } from "../helpers.ts";
+
+/**
+ * `o2b brain graph-export [--out <file>]` - serialise the user's vault
+ * pages (links + typed relations) to a stable graph.json. Prints to
+ * stdout, or writes to `--out <file>`. Read-only on the vault.
+ */
+export async function cmdBrainGraphExport(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, { vault: { type: "string" }, out: { type: "string" } });
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ let json: string;
+ try {
+ json = JSON.stringify(exportVaultGraph(vault), null, 2) + "\n";
+ } catch (exc) {
+ return fail(`graph-export failed: ${(exc as Error).message ?? exc}`);
+ }
+
+ try {
+ if (typeof flags["out"] === "string") {
+ atomicWriteFileSync(flags["out"], json);
+ process.stdout.write(`wrote ${flags["out"]}\n`);
+ } else {
+ process.stdout.write(json);
+ }
+ } catch (exc) {
+ return fail(`graph-export failed to write output: ${(exc as Error).message ?? exc}`);
+ }
+ return 0;
+}
diff --git a/src/cli/brain/verbs/graph-import.ts b/src/cli/brain/verbs/graph-import.ts
new file mode 100644
index 00000000..7d6179cb
--- /dev/null
+++ b/src/cli/brain/verbs/graph-import.ts
@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+
+import { defaultConfigPath } from "../../../core/config.ts";
+import {
+ importVaultGraph,
+ type GraphImportMode,
+} from "../../../core/brain/portability/graph.ts";
+import { fail, parse, resolveBrainVault } from "../helpers.ts";
+
+const MODES: ReadonlyArray<GraphImportMode> = ["skip", "overwrite", "merge"];
+
+/**
+ * `o2b brain graph-import <file> [--mode skip|overwrite|merge] [--json]`
+ * reconstruct vault page stubs from a graph.json. `skip` (default) never
+ * overwrites; writes are guarded against escaping the vault.
+ */
+export async function cmdBrainGraphImport(argv: string[]): Promise<number> {
+ const { flags, positional } = parse(argv, {
+ vault: { type: "string" },
+ json: { type: "boolean" },
+ mode: { type: "string" },
+ });
+ const file = positional[0];
+ if (!file) return fail("usage: o2b brain graph-import <file> [--mode skip|overwrite|merge]");
+
+ const mode = (flags["mode"] as string | undefined) ?? "skip";
+ if (!MODES.includes(mode as GraphImportMode)) {
+ return fail(`graph-import: --mode must be one of ${MODES.join(" | ")}; got ${mode}`);
+ }
+
+ const config = defaultConfigPath();
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+
+ let graph: { nodes?: unknown };
+ try {
+ graph = JSON.parse(readFileSync(file, "utf8")) as { nodes?: unknown };
+ } catch (exc) {
+ return fail(`graph-import: failed to read ${file}: ${(exc as Error).message ?? exc}`);
+ }
+
+ let result;
+ try {
+ result = importVaultGraph(vault, graph as never, { mode: mode as GraphImportMode });
+ } catch (exc) {
+ return fail(`graph-import failed: ${(exc as Error).message ?? exc}`);
+ }
+
+ if (flags["json"]) {
+ process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+ } else {
+ process.stdout.write(
+ `created ${result.created.length}, overwritten ${result.overwritten.length}, ` +
+ `merged ${result.merged.length}, skipped ${result.skipped.length}, ` +
+ `rejected ${result.rejected.length}\n`,
+ );
+ }
+ return 0;
+}
diff --git a/src/cli/brain/verbs/index.ts b/src/cli/brain/verbs/index.ts
index 18627781..9b3e31b0 100644
--- a/src/cli/brain/verbs/index.ts
+++ b/src/cli/brain/verbs/index.ts
@@ -20,6 +20,10 @@ export { cmdBrainHealth } from "./health.ts";
export { cmdBrainHistory } from "./history.ts";
export { cmdBrainAudit } from "./audit.ts";
export { cmdBrainMorningBrief } from "./morning-brief.ts";
+export { cmdBrainCodec } from "./codec.ts";
+export { cmdBrainSources } from "./sources.ts";
+export { cmdBrainGraphExport } from "./graph-export.ts";
+export { cmdBrainGraphImport } from "./graph-import.ts";
export { cmdBrainBacklinks } from "./backlinks.ts";
export { cmdBrainMcpLandscape } from "./mcp-landscape.ts";
export { cmdBrainMerge } from "./merge.ts";
diff --git a/src/cli/brain/verbs/sources.ts b/src/cli/brain/verbs/sources.ts
new file mode 100644
index 00000000..f620b949
--- /dev/null
+++ b/src/cli/brain/verbs/sources.ts
@@ -0,0 +1,40 @@
+import { defaultConfigPath } from "../../../core/config.ts";
+import { aggregateSources } from "../../../core/brain/portability/sources.ts";
+import { fail, parse, resolveBrainVault } from "../helpers.ts";
+
+/**
+ * `o2b brain sources [--json]` - read-only dashboard of the brain's
+ * signals grouped by (agent, source_type) with active/processed and
+ * distinct-topic counts.
+ */
+export async function cmdBrainSources(argv: string[]): Promise<number> {
+ const { flags } = parse(argv, { vault: { type: "string" }, json: { type: "boolean" } });
+ const config = defaultConfigPath();
+
+ let report;
+ try {
+ const vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+ report = aggregateSources(vault);
+ } catch (exc) {
+ return fail(`sources failed: ${(exc as Error).message ?? exc}`);
+ }
+
+ if (flags["json"]) {
+ process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+ return 0;
+ }
+ if (report.sources.length === 0) {
+ process.stdout.write("no signals\n");
+ return 0;
+ }
+ const lines = [
+ `sources (${report.total_active} active, ${report.total_processed} processed)`,
+ ];
+ for (const s of report.sources) {
+ lines.push(
+ ` ${s.agent} [${s.source_type}] active=${s.active} processed=${s.processed} topics=${s.distinct_topics}`,
+ );
+ }
+ process.stdout.write(lines.join("\n") + "\n");
+ return 0;
+}
diff --git a/src/cli/vault.ts b/src/cli/vault.ts
index 89aadee4..c8922c34 100644
--- a/src/cli/vault.ts
+++ b/src/cli/vault.ts
@@ -9,6 +9,8 @@ import { CliError } from "./argparse.ts";
import { VAULT_HELP, VAULT_VERB_HELP } from "./vault/help-text.ts";
import { cmdVaultStatus } from "./vault/verbs/status.ts";
import { cmdVaultInspect } from "./vault/verbs/inspect.ts";
+import { cmdVaultProfile } from "./vault/verbs/profile.ts";
+import { cmdVaultMap } from "./vault/verbs/map.ts";
export async function handleVaultSubcommand(argv: ReadonlyArray<string>): Promise<number> {
if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
@@ -34,6 +36,10 @@ export async function handleVaultSubcommand(argv: ReadonlyArray<string>): Promis
return await cmdVaultStatus(rest);
case "inspect":
return await cmdVaultInspect(rest);
+ case "profile":
+ return await cmdVaultProfile(rest);
+ case "map":
+ return await cmdVaultMap(rest);
default:
process.stderr.write(`error: unknown vault verb: ${verb}\n`);
process.stdout.write(VAULT_HELP);
diff --git a/src/cli/vault/help-text.ts b/src/cli/vault/help-text.ts
index 189f8743..a95aede9 100644
--- a/src/cli/vault/help-text.ts
+++ b/src/cli/vault/help-text.ts
@@ -13,6 +13,9 @@ verbs:
report inclusion / exclusion counts.
inspect <relpath> Point-check one vault-relative path with the
matched rule.
+ profile <sub> Manage named multi-vault profiles
+ (list | create <name> <vault> | switch <name>).
+ map [show] Print the resolved vault-map (role token -> folder).
global flags:
--vault <path> Override the configured vault path.
@@ -30,4 +33,13 @@ export const VAULT_VERB_HELP: Record<string, string> = {
"Resolves the policy and runs matchIgnore against <relpath>. The\n" +
"relpath is vault-relative (POSIX). Path traversal outside the\n" +
"vault is rejected with exit 2.\n",
+ profile:
+ "usage: o2b vault profile <list | create <name> <vault> | switch <name>> [--json]\n\n" +
+ "Manage named multi-vault profiles stored in profiles.json beside the\n" +
+ "config. switch sets the active pointer (no symlinks); resolveVault uses\n" +
+ "the active profile before the bare config vault key.\n",
+ map:
+ "usage: o2b vault map [show] [--vault <path>] [--json]\n\n" +
+ "Print the resolved vault-map (role token -> folder), merging an optional\n" +
+ "Brain/_vault-map.yaml over the built-in defaults. Read-only.\n",
};
diff --git a/src/cli/vault/verbs/map.ts b/src/cli/vault/verbs/map.ts
new file mode 100644
index 00000000..72cadb76
--- /dev/null
+++ b/src/cli/vault/verbs/map.ts
@@ -0,0 +1,35 @@
+import { defaultConfigPath } from "../../../core/config.ts";
+import { loadVaultMap } from "../../../core/brain/portability/role-tokens.ts";
+import { parseFlags } from "../../argparse.ts";
+import { resolveBrainVault } from "../../brain/helpers.ts";
+import { fail, info, writeJson } from "../../output.ts";
+
+/**
+ * `o2b vault map [show]` - print the resolved vault-map (role token ->
+ * folder), merging an optional `Brain/_vault-map.yaml` over the built-in
+ * defaults. Read-only.
+ */
+export async function cmdVaultMap(argv: ReadonlyArray<string>): Promise<number> {
+ const { flags } = parseFlags(argv, { vault: { type: "string" }, json: { type: "boolean" } });
+ const config = defaultConfigPath();
+ let vault: string;
+ try {
+ vault = resolveBrainVault(flags["vault"] as string | undefined, config);
+ } catch (exc) {
+ return fail(`vault map: ${(exc as Error).message ?? exc}`);
+ }
+
+ try {
+ const map = loadVaultMap(vault);
+ if (flags["json"]) {
+ writeJson(map);
+ return 0;
+ }
+ for (const token of Object.keys(map).toSorted()) {
+ info(`{{${token}}} -> ${map[token]}`);
+ }
+ return 0;
+ } catch (exc) {
+ return fail(`vault map: ${(exc as Error).message ?? exc}`);
+ }
+}
diff --git a/src/cli/vault/verbs/profile.ts b/src/cli/vault/verbs/profile.ts
new file mode 100644
index 00000000..92746b9a
--- /dev/null
+++ b/src/cli/vault/verbs/profile.ts
@@ -0,0 +1,69 @@
+import { defaultConfigPath } from "../../../core/config.ts";
+import {
+ createProfile,
+ listProfiles,
+ switchProfile,
+} from "../../../core/brain/portability/profiles.ts";
+import { parseFlags } from "../../argparse.ts";
+import { fail, info, writeJson } from "../../output.ts";
+
+/**
+ * `o2b vault profile <list|create|switch>` - manage named multi-vault
+ * profiles. `create <name> <vault-path>`, `switch <name>`, `list`.
+ * Activation is a pointer in profiles.json (no symlinks).
+ */
+export async function cmdVaultProfile(argv: ReadonlyArray<string>): Promise<number> {
+ const { flags, positional } = parseFlags(argv, { json: { type: "boolean" } });
+ const sub = positional[0] ?? "list";
+ const configPath = defaultConfigPath();
+
+ switch (sub) {
+ case "list": {
+ let listing;
+ try {
+ listing = listProfiles(configPath);
+ } catch (exc) {
+ return fail(`profile list failed: ${(exc as Error).message ?? exc}`);
+ }
+ if (flags["json"]) {
+ writeJson(listing);
+ return 0;
+ }
+ if (listing.profiles.length === 0) {
+ info("no profiles");
+ return 0;
+ }
+ for (const p of listing.profiles) {
+ info(`${p.active ? "* " : " "}${p.name} ${p.vault}`);
+ }
+ return 0;
+ }
+ case "create": {
+ const name = positional[1];
+ const vault = positional[2];
+ if (!name || !vault) {
+ return fail("usage: o2b vault profile create <name> <vault-path>");
+ }
+ try {
+ createProfile(configPath, name, vault);
+ } catch (exc) {
+ return fail(`profile create failed: ${(exc as Error).message ?? exc}`);
+ }
+ info(`created profile '${name}' -> ${vault}`);
+ return 0;
+ }
+ case "switch": {
+ const name = positional[1];
+ if (!name) return fail("usage: o2b vault profile switch <name>");
+ try {
+ switchProfile(configPath, name);
+ } catch (exc) {
+ return fail(`profile switch failed: ${(exc as Error).message ?? exc}`);
+ }
+ info(`active profile -> ${name}`);
+ return 0;
+ }
+ default:
+ return fail(`unknown profile subcommand '${sub}' (list | create | switch)`);
+ }
+}
diff --git a/src/core/brain/inline-scan.ts b/src/core/brain/inline-scan.ts
index 20ad3b68..1455a65a 100644
--- a/src/core/brain/inline-scan.ts
+++ b/src/core/brain/inline-scan.ts
@@ -37,6 +37,7 @@ import { writeSignal } from "./signal.ts";
import { isoDate, isoSecond } from "./time.ts";
import { BRAIN_SIGNAL_SOURCE_TYPE } from "./types.ts";
import { matchIgnore, resolveVaultScope, type VaultIgnoreRule } from "../vault-scope/index.ts";
+import { loadVaultMap, resolveTokens } from "./portability/role-tokens.ts";
const MAX_FILE_SIZE_BYTES = 1_048_576; // 1 MiB
@@ -92,8 +93,12 @@ export async function scanInline(
// resolved list means "no folders to scan" — return immediately so
// the agent never walks the vault without an operator opt-in.
const explicitPaths = (opts.paths ?? []).filter((p) => p.trim().length > 0);
- const resolvedPaths =
- explicitPaths.length > 0 ? explicitPaths : [...loadNotesConfigSafe(vault).read_paths];
+ // v0.22.0: resolve `{{role}}` tokens in read paths via the optional
+ // vault-map (user content folders only); absent map -> paths unchanged.
+ const vaultMap = loadVaultMap(vault);
+ const resolvedPaths = (
+ explicitPaths.length > 0 ? explicitPaths : [...loadNotesConfigSafe(vault).read_paths]
+ ).map((p) => resolveTokens(vaultMap, p));
if (resolvedPaths.length === 0) {
return Object.freeze({
scanned: 0,
diff --git a/src/core/brain/portability/codec.ts b/src/core/brain/portability/codec.ts
new file mode 100644
index 00000000..befa71ed
--- /dev/null
+++ b/src/core/brain/portability/codec.ts
@@ -0,0 +1,80 @@
+/**
+ * Deterministic session codec (Vault portability suite, Feature 1).
+ *
+ * A pure, lossless, language-agnostic codec for session-derived prose.
+ * `expand(compress(x)) === x` holds for ALL input - brain memory must
+ * never lose data, so this is a strict reversible transform, not a lossy
+ * summariser. Token savings come from reversibly collapsing runs of
+ * whitespace and blank lines; fenced and inline code spans are protected
+ * (their whitespace is never collapsed), and structured tokens (URLs,
+ * paths, identifiers, version numbers) are preserved byte-for-byte by
+ * construction because nothing but long whitespace runs is ever rewritten.
+ *
+ * Detection is purely structural - no natural-language word lists - so
+ * the codec behaves identically for any language or script.
+ *
+ * Encoding:
+ * - A run of >= RUN_MIN spaces becomes `ESC s <count> ESC`.
+ * - A run of >= RUN_MIN newlines becomes `ESC n <count> ESC`.
+ * - A literal ESC in the input is escaped to `ESC x` (x is neither
+ * marker letter), so a marker-looking input sequence can never be
+ * mistaken for a real marker on expand.
+ * ESC is a Unicode Private-Use-Area code point that does not occur in
+ * normal text; the escape rule makes correctness unconditional anyway.
+ * RUN_MIN = 4 guarantees a whitespace-run marker is never longer than the
+ * run it replaces, so for normal text (free of the PUA sentinel) the
+ * compressed form never exceeds the original. The only growth case is an
+ * input that already contains the sentinel: escaping adds one byte per
+ * literal ESC - which does not occur in real prose, and round-trip stays
+ * exact regardless.
+ */
+
+export const CODEC_VERSION = "1";
+
+const ESC = "";
+const ESC_LITERAL = `${ESC}x`;
+// RUN_MIN = 4 is baked into the {4,} run regexes below: a 4-char marker
+// never exceeds the run it replaces, keeping compressed <= original.
+
+// Fenced code blocks and single-line inline code spans: their interior
+// whitespace is significant, so it is left uncollapsed (still escaped for
+// ESC safety). The capture group puts protected spans at odd split indices.
+const PROTECTED_RE = /(```[\s\S]*?```|`[^`\n]*`)/g;
+const MARKER_RE = new RegExp(`${ESC}([sn])(\\d+)${ESC}`, "g");
+
+/** Escape any literal ESC so it can never be read as a marker on expand. */
+function escapeEsc(s: string): string {
+ return s.includes(ESC) ? s.split(ESC).join(ESC_LITERAL) : s;
+}
+
+/** Escape, then collapse long whitespace / blank-line runs reversibly. */
+function collapseFree(seg: string): string {
+ return escapeEsc(seg)
+ .replace(/\n{4,}/g, (m) => `${ESC}n${m.length}${ESC}`)
+ .replace(/ {4,}/g, (m) => `${ESC}s${m.length}${ESC}`);
+}
+
+/** Compress `text` into its reversible codec form. */
+export function compress(text: string): string {
+ if (text.length === 0) return text;
+ const parts = text.split(PROTECTED_RE);
+ let out = "";
+ for (let i = 0; i < parts.length; i++) {
+ const part = parts[i]!;
+ // Odd indices are protected spans: escape only, never collapse.
+ out += i % 2 === 1 ? escapeEsc(part) : collapseFree(part);
+ }
+ return out;
+}
+
+/** Expand a codec form back to the exact original text. */
+export function expand(text: string): string {
+ if (!text.includes(ESC)) return text;
+ const restored = text.replace(MARKER_RE, (_full, kind: string, nStr: string) => {
+ const n = Number(nStr);
+ return (kind === "n" ? "\n" : " ").repeat(n);
+ });
+ // Unescape literal ESC last; marker scanning above already consumed the
+ // structural ESCs, so the only pairs left are escapes.
+ return restored.split(ESC_LITERAL).join(ESC);
+}
diff --git a/src/core/brain/portability/graph.ts b/src/core/brain/portability/graph.ts
new file mode 100644
index 00000000..0d698fb0
--- /dev/null
+++ b/src/core/brain/portability/graph.ts
@@ -0,0 +1,263 @@
+/**
+ * Vault graph export/import (Vault portability suite, Feature 5).
+ *
+ * `exportVaultGraph` serialises the user's vault pages (excluding the
+ * Brain machinery root and the standard ignored dirs) into a stable,
+ * sorted `graph.json`: one node per page with its wikilinks and typed
+ * relations. Re-export is byte-identical (everything sorted, no
+ * timestamps), so the format is a deterministic interchange artifact.
+ *
+ * The importer (`importVaultGraph`, Feature 5 Task 4) reconstructs page
+ * stubs under three conflict modes.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, posix, relative } from "node:path";
+
+import {
+ EXCLUDED_DIRS,
+ extractWikilinks,
+ listVaultPages,
+ parseFrontmatter,
+ writeFrontmatterAtomic,
+} from "../../vault.ts";
+import type { FrontmatterMap } from "../../types.ts";
+import {
+ extractFrontmatterRelations,
+ normalizeRelationTarget,
+} from "../../graph/frontmatter-relations.ts";
+import { BRAIN_ROOT_REL, ensureInsideVault } from "../paths.ts";
+import { loadVaultMap, resolveTokens } from "./role-tokens.ts";
+
+export const GRAPH_VERSION = "1";
+
+/** Typed-relation frontmatter fields (v0.19.0) carried in the graph. */
+export const RELATION_FIELDS = ["related", "extends", "contradicts", "superseded_by"] as const;
+
+export interface VaultGraphNode {
+ /** Obsidian basename id (wikilink target). */
+ readonly id: string;
+ /** Vault-relative POSIX path. */
+ readonly path: string;
+ readonly title: string;
+ /** Sorted, de-duplicated wikilink targets in the body. */
+ readonly links: ReadonlyArray<string>;
+ /** Typed relations -> sorted target lists (only non-empty fields present). */
+ readonly relations: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+
+export interface VaultGraph {
+ readonly version: string;
+ readonly nodes: ReadonlyArray<VaultGraphNode>;
+}
+
+function stem(path: string): string {
+ const base = path.split(/[\\/]/).pop() ?? path;
+ return base.replace(/\.md$/i, "");
+}
+
+function sortedUnique(values: Iterable<string>): string[] {
+ return [...new Set([...values].filter((v) => v.length > 0))].toSorted();
+}
+
+function collectRelations(meta: FrontmatterMap): Record<string, ReadonlyArray<string>> {
+ const grouped = new Map<string, string[]>();
+ for (const edge of extractFrontmatterRelations(meta)) {
+ const arr = grouped.get(edge.relation);
+ if (arr) arr.push(edge.target);
+ else grouped.set(edge.relation, [edge.target]);
+ }
+ const out: Record<string, ReadonlyArray<string>> = {};
+ for (const [relation, targets] of grouped) out[relation] = sortedUnique(targets);
+ return out;
+}
+
+/**
+ * Export every user vault page (Brain machinery excluded) as a stable,
+ * sorted graph. Pure and read-only.
+ */
+export function exportVaultGraph(vault: string): VaultGraph {
+ const pages = listVaultPages(vault, { skipDirs: [...EXCLUDED_DIRS, BRAIN_ROOT_REL] });
+ const nodes: VaultGraphNode[] = [];
+ for (const page of pages) {
+ let body: string;
+ let meta: FrontmatterMap;
+ try {
+ const [m, b] = parseFrontmatter(page.path);
+ meta = m;
+ body = b;
+ } catch {
+ continue;
+ }
+ const links = sortedUnique(
+ extractWikilinks(body)
+ .map((t) => normalizeRelationTarget(t))
+ .filter((t): t is string => t !== null),
+ );
+ nodes.push({
+ id: stem(page.path),
+ path: relative(vault, page.path).split(/[\\/]/).join(posix.sep),
+ title: page.title,
+ links,
+ relations: collectRelations(meta),
+ });
+ }
+ nodes.sort((a, b) =>
+ a.id < b.id ? -1 : a.id > b.id ? 1 : a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
+ );
+ return { version: GRAPH_VERSION, nodes };
+}
+
+// ----- Import --------------------------------------------------------------
+
+export type GraphImportMode = "skip" | "overwrite" | "merge";
+
+export interface GraphImportResult {
+ readonly created: string[];
+ readonly skipped: string[];
+ readonly overwritten: string[];
+ readonly merged: string[];
+ /** Node paths refused because they escaped the vault. */
+ readonly rejected: string[];
+}
+
+/** Shape the importer reads from a graph node (loosely typed for JSON input). */
+interface GraphNodeInput {
+ readonly path: string;
+ readonly title?: string;
+ readonly links?: ReadonlyArray<string>;
+ readonly relations?: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+
+const isStringArray = (v: unknown): boolean =>
+ Array.isArray(v) && v.every((item) => typeof item === "string");
+
+/**
+ * Runtime guard for one untrusted JSON node. `path` must be a string;
+ * `title` (when present) a string; `links` a string array; `relations`
+ * a plain object whose every value is a string array. Anything else is
+ * rejected so the import skips it rather than throwing mid-run.
+ */
+function isValidGraphNode(node: unknown): node is GraphNodeInput {
+ if (!node || typeof node !== "object") return false;
+ const n = node as Record<string, unknown>;
+ if (typeof n["path"] !== "string") return false;
+ if (n["title"] !== undefined && typeof n["title"] !== "string") return false;
+ if (n["links"] !== undefined && !isStringArray(n["links"])) return false;
+ if (n["relations"] !== undefined) {
+ const rel = n["relations"];
+ if (!rel || typeof rel !== "object" || Array.isArray(rel)) return false;
+ if (!Object.values(rel).every((targets) => isStringArray(targets))) return false;
+ }
+ return true;
+}
+
+/**
+ * Render a deterministic page stub. Single-target relations land in
+ * frontmatter (the only form OSB's frontmatter parser round-trips);
+ * body wikilinks list the links. Multi-target relations are flattened
+ * into the body links (type not preserved - a documented limitation of
+ * the frontmatter parser).
+ */
+function renderStub(
+ title: string,
+ links: ReadonlyArray<string>,
+ relations: Readonly<Record<string, ReadonlyArray<string>>>,
+): [FrontmatterMap, string] {
+ const meta: FrontmatterMap = { title };
+ const bodyTargets = new Set(links);
+ for (const [relation, targets] of Object.entries(relations)) {
+ if (targets.length === 1) meta[relation] = `[[${targets[0]}]]`;
+ else for (const t of targets) bodyTargets.add(t);
+ }
+ const sorted = [...bodyTargets].filter((t) => t.length > 0).toSorted();
+ const body = sorted.length > 0 ? sorted.map((t) => `- [[${t}]]`).join("\n") + "\n" : "";
+ return [meta, body];
+}
+
+function readExisting(path: string): { links: string[]; relations: Record<string, string[]> } {
+ const [meta, body] = parseFrontmatter(path);
+ const links = extractWikilinks(body)
+ .map((t) => normalizeRelationTarget(t))
+ .filter((t): t is string => t !== null);
+ const relations: Record<string, string[]> = {};
+ for (const edge of extractFrontmatterRelations(meta)) {
+ (relations[edge.relation] ??= []).push(edge.target);
+ }
+ return { links, relations };
+}
+
+/**
+ * Reconstruct vault page stubs from a graph under one conflict mode.
+ * `skip` (default) never overwrites and is idempotent; `overwrite`
+ * replaces; `merge` unions wikilinks + relations with the existing page.
+ * Every write is guarded by {@link ensureInsideVault}.
+ */
+export function importVaultGraph(
+ vault: string,
+ graph: { nodes?: ReadonlyArray<GraphNodeInput> },
+ opts: { mode?: GraphImportMode } = {},
+): GraphImportResult {
+ const mode: GraphImportMode = opts.mode ?? "skip";
+ const result: GraphImportResult = {
+ created: [],
+ skipped: [],
+ overwritten: [],
+ merged: [],
+ rejected: [],
+ };
+
+ const vaultMap = loadVaultMap(vault);
+ for (const node of graph.nodes ?? []) {
+ // Validate the node shape per entry: a single malformed JSON node is
+ // rejected and the import continues, instead of throwing and aborting
+ // the whole run. `graph` arrives from untrusted JSON, so the static
+ // GraphNodeInput type is not a runtime guarantee.
+ if (!isValidGraphNode(node)) {
+ result.rejected.push(String((node as { path?: unknown })?.path ?? "<invalid-node>"));
+ continue;
+ }
+ // Resolve `{{role}}` tokens in the target path via the vault-map so a
+ // portable graph can address user folders abstractly (v0.22.0).
+ const relPath = resolveTokens(vaultMap, node.path);
+ let path: string;
+ try {
+ path = ensureInsideVault(join(vault, relPath), vault);
+ } catch {
+ result.rejected.push(node.path);
+ continue;
+ }
+ const title = node.title ?? node.path;
+ const incomingLinks = node.links ?? [];
+ const incomingRelations = node.relations ?? {};
+ const exists = existsSync(path);
+
+ if (exists && mode === "skip") {
+ result.skipped.push(node.path);
+ continue;
+ }
+
+ let links: ReadonlyArray<string> = incomingLinks;
+ let relations: Record<string, ReadonlyArray<string>> = { ...incomingRelations };
+ if (exists && mode === "merge") {
+ const prev = readExisting(path);
+ links = [...new Set([...prev.links, ...incomingLinks])];
+ const merged: Record<string, string[]> = {};
+ for (const [rel, targets] of Object.entries(prev.relations)) merged[rel] = [...targets];
+ for (const [rel, targets] of Object.entries(incomingRelations)) {
+ merged[rel] = [...new Set([...(merged[rel] ?? []), ...targets])];
+ }
+ relations = merged;
+ }
+
+ const [meta, body] = renderStub(title, links, relations);
+ mkdirSync(dirname(path), { recursive: true });
+ writeFrontmatterAtomic(path, meta, body, { overwrite: true, vaultForRelativePath: vault });
+
+ if (!exists) result.created.push(node.path);
+ else if (mode === "merge") result.merged.push(node.path);
+ else result.overwritten.push(node.path);
+ }
+
+ return result;
+}
diff --git a/src/core/brain/portability/profiles.ts b/src/core/brain/portability/profiles.ts
new file mode 100644
index 00000000..cd2c28e1
--- /dev/null
+++ b/src/core/brain/portability/profiles.ts
@@ -0,0 +1,126 @@
+/**
+ * Named multi-vault profiles (Vault portability suite, Feature 4).
+ *
+ * A profile registry (name -> vault path) stored as JSON in a
+ * `profiles.json` beside the config file, with list / create / switch.
+ * Activation is a pointer in that file - NOT a filesystem symlink, which
+ * syncs inconsistently across devices under Syncthing. `resolveVault`
+ * consults {@link resolveActiveProfileVault} before the bare config
+ * `vault` key; with no profiles file the brain behaves exactly as before.
+ *
+ * This module is standalone (no import of config.ts) so config.ts can
+ * depend on it without a cycle.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { atomicWriteFileSync } from "../../fs-atomic.ts";
+
+export interface VaultProfile {
+ readonly name: string;
+ readonly vault: string;
+ readonly active: boolean;
+}
+
+export interface ProfilesListing {
+ readonly profiles: ReadonlyArray<VaultProfile>;
+ readonly active: string | null;
+}
+
+interface ProfilesFile {
+ active: string | null;
+ profiles: Record<string, { vault: string }>;
+}
+
+const EMPTY: ProfilesFile = { active: null, profiles: {} };
+
+/** Path of the profiles registry that accompanies a config file. */
+export function profilesPath(configPath: string): string {
+ return join(dirname(configPath), "profiles.json");
+}
+
+function load(configPath: string, opts: { tolerateParseError?: boolean } = {}): ProfilesFile {
+ const path = profilesPath(configPath);
+ if (!existsSync(path)) return { active: null, profiles: {} };
+ try {
+ const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<ProfilesFile>;
+ // Keep only well-shaped entries so a hand-edited file can't yield a
+ // profile whose `vault` is undefined downstream.
+ const profiles: Record<string, { vault: string }> = {};
+ if (raw.profiles && typeof raw.profiles === "object") {
+ for (const [name, entry] of Object.entries(raw.profiles)) {
+ if (entry && typeof entry === "object" && typeof entry.vault === "string") {
+ profiles[name] = { vault: entry.vault };
+ }
+ }
+ }
+ return { active: typeof raw.active === "string" ? raw.active : null, profiles };
+ } catch (exc) {
+ // Read-only callers tolerate a malformed registry (treat as empty);
+ // mutating callers must fail fast so a save() does not clobber a file
+ // we could not parse, silently dropping every stored profile.
+ if (!opts.tolerateParseError) {
+ throw new Error(`profiles registry is malformed: ${path}`, { cause: exc });
+ }
+ return { ...EMPTY };
+ }
+}
+
+function save(configPath: string, data: ProfilesFile): void {
+ const path = profilesPath(configPath);
+ mkdirSync(dirname(path), { recursive: true });
+ // Stable key order for byte-identical writes under Syncthing.
+ const ordered: ProfilesFile = {
+ active: data.active,
+ profiles: Object.fromEntries(
+ Object.keys(data.profiles)
+ .toSorted()
+ .map((k) => [k, data.profiles[k]!]),
+ ),
+ };
+ atomicWriteFileSync(path, JSON.stringify(ordered, null, 2) + "\n");
+}
+
+/** List every profile plus the active pointer. */
+export function listProfiles(configPath: string): ProfilesListing {
+ const data = load(configPath, { tolerateParseError: true });
+ const profiles = Object.keys(data.profiles)
+ .toSorted()
+ .map((name) => ({
+ name,
+ vault: data.profiles[name]!.vault,
+ active: data.active === name,
+ }));
+ return { profiles, active: data.active };
+}
+
+/** Create (or update) a named profile pointing at a vault path. */
+export function createProfile(configPath: string, name: string, vault: string): void {
+ const trimmed = name.trim();
+ if (trimmed.length === 0) throw new Error("profile name must not be empty");
+ if (vault.trim().length === 0) throw new Error("profile vault must not be empty");
+ const data = load(configPath);
+ data.profiles[trimmed] = { vault: vault.trim() };
+ save(configPath, data);
+}
+
+/** Activate a named profile. Throws if the profile does not exist. */
+export function switchProfile(configPath: string, name: string): void {
+ const data = load(configPath);
+ if (!data.profiles[name]) {
+ throw new Error(`unknown profile '${name}'`);
+ }
+ data.active = name;
+ save(configPath, data);
+}
+
+/**
+ * Vault path of the active profile, or `null` when no profile is active
+ * (or the active pointer dangles). Read-only; never throws.
+ */
+export function resolveActiveProfileVault(configPath: string): string | null {
+ const data = load(configPath, { tolerateParseError: true });
+ if (data.active === null) return null;
+ return data.profiles[data.active]?.vault ?? null;
+}
diff --git a/src/core/brain/portability/role-tokens.ts b/src/core/brain/portability/role-tokens.ts
new file mode 100644
index 00000000..63bb0b39
--- /dev/null
+++ b/src/core/brain/portability/role-tokens.ts
@@ -0,0 +1,96 @@
+/**
+ * Vault-map role-token resolution (Vault portability suite, Feature 3).
+ *
+ * Lets tools resolve `{{role}}` tokens (e.g. `{{inbox}}`, `{{projects}}`)
+ * to USER content folder names via an optional `Brain/_vault-map.yaml`,
+ * falling back to built-in defaults when the file or a token is absent.
+ *
+ * Scope: this addresses the user's content folders only (scan read paths,
+ * graph-import target, ...). The FIXED Brain machinery layout in
+ * `paths.ts` (`BRAIN_INBOX_REL` etc.) is intentionally NOT routed through
+ * this resolver - the "one agent-owned Brain root" design stays intact.
+ *
+ * Determinism + safety: mapped values are validated against path traversal
+ * (no `..` segment, not absolute, no NUL); an invalid value falls back to
+ * the built-in default for that role. No language word lists anywhere.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseSimpleYaml } from "../../config.ts";
+
+/** Canonical PKM role tokens with their default folder names. */
+export const DEFAULT_ROLE_TOKENS: Readonly<Record<string, string>> = Object.freeze({
+ inbox: "inbox",
+ projects: "projects",
+ areas: "areas",
+ resources: "resources",
+ archive: "archive",
+ "daily-notes": "daily-notes",
+ meetings: "meetings",
+ reference: "reference",
+ scratch: "scratch",
+ templates: "templates",
+ attachments: "attachments",
+});
+
+const VAULT_MAP_FILE = "_vault-map.yaml";
+
+/** A mapped folder value is safe when it stays a relative in-vault subpath. */
+function isSafeFolder(value: string): boolean {
+ const v = value.trim();
+ if (v.length === 0) return false;
+ // Spaces are legal folder names ("Daily Notes"); reject only genuine
+ // hazards: control chars (incl. NUL), absolute paths, `..`/`.` segments.
+ // eslint-disable-next-line no-control-regex
+ if (/[\u0000-\u001f]/.test(v)) return false;
+ if (v.startsWith("/") || v.startsWith("\\")) return false;
+ if (/^[A-Za-z]:/.test(v)) return false; // Windows drive-absolute
+ const segments = v.split(/[\\/]/);
+ return !segments.some((s) => s === ".." || s === ".");
+}
+
+/** Strip surrounding `{{ }}` (if any) and whitespace from a token. */
+function tokenKey(token: string): string {
+ return token.replace(/^\{\{/, "").replace(/\}\}$/, "").trim();
+}
+
+/**
+ * Load the vault-map (token -> folder) merged over the built-in defaults.
+ * Absent file -> defaults; invalid (traversal/absolute) values are dropped
+ * so the default for that role is kept.
+ */
+export function loadVaultMap(vault: string): Record<string, string> {
+ const map: Record<string, string> = { ...DEFAULT_ROLE_TOKENS };
+ const path = join(vault, "Brain", VAULT_MAP_FILE);
+ if (!existsSync(path)) return map;
+ let raw: Record<string, string>;
+ try {
+ raw = parseSimpleYaml(readFileSync(path, "utf8"));
+ } catch {
+ return map;
+ }
+ for (const [key, value] of Object.entries(raw)) {
+ if (typeof value === "string" && isSafeFolder(value)) {
+ map[key] = value.trim();
+ }
+ }
+ return map;
+}
+
+/**
+ * Resolve a single `{{role}}` (or bare `role`) token to a folder name.
+ * Unknown tokens resolve to their own literal name.
+ */
+export function resolveRoleToken(map: Record<string, string>, token: string): string {
+ const key = tokenKey(token);
+ return map[key] ?? key;
+}
+
+/** Replace every `{{role}}` occurrence in `text` via {@link resolveRoleToken}. */
+export function resolveTokens(map: Record<string, string>, text: string): string {
+ return text.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_full, inner: string) =>
+ resolveRoleToken(map, inner),
+ );
+}
diff --git a/src/core/brain/portability/sources.ts b/src/core/brain/portability/sources.ts
new file mode 100644
index 00000000..ef9ae837
--- /dev/null
+++ b/src/core/brain/portability/sources.ts
@@ -0,0 +1,102 @@
+/**
+ * Sources dashboard projection (Vault portability suite, Feature 2).
+ *
+ * A pure, read-only aggregation over the brain's signals (inbox +
+ * processed), grouped by (agent, source_type) with active/processed and
+ * distinct-topic counts. No new store, no writes; deterministic ordering.
+ *
+ * (The parallel multi-source sync worker pool + connection-budget warning
+ * from the upstream inspiration are intentionally out of scope - only this
+ * read-only dashboard ships.)
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { brainDirs } from "../paths.ts";
+import { parseSignal } from "../signal.ts";
+import { BRAIN_SIGNAL_SOURCE_TYPE } from "../types.ts";
+
+export interface SourceRow {
+ readonly agent: string;
+ readonly source_type: string;
+ readonly active: number;
+ readonly processed: number;
+ readonly distinct_topics: number;
+}
+
+export interface SourcesReport {
+ readonly sources: ReadonlyArray<SourceRow>;
+ readonly total_active: number;
+ readonly total_processed: number;
+}
+
+interface Bucket {
+ agent: string;
+ source_type: string;
+ active: number;
+ processed: number;
+ topics: Set<string>;
+}
+
+function scanDir(dir: string, active: boolean, buckets: Map<string, Bucket>): void {
+ if (!existsSync(dir)) return;
+ for (const name of readdirSync(dir)) {
+ if (!name.endsWith(".md")) continue;
+ let sig;
+ try {
+ sig = parseSignal(join(dir, name));
+ } catch {
+ continue;
+ }
+ const agent = sig.agent || "unknown";
+ // Absent source_type is semantically `live` (never inject a default
+ // into the signal itself; only bucket it here).
+ const sourceType = sig.source_type ?? BRAIN_SIGNAL_SOURCE_TYPE.live;
+ const key = JSON.stringify([agent, sourceType]);
+ let bucket = buckets.get(key);
+ if (!bucket) {
+ bucket = { agent, source_type: sourceType, active: 0, processed: 0, topics: new Set() };
+ buckets.set(key, bucket);
+ }
+ if (active) bucket.active += 1;
+ else bucket.processed += 1;
+ bucket.topics.add(sig.topic);
+ }
+}
+
+/**
+ * Aggregate the brain's signals into a per-source dashboard. Read-only.
+ */
+export function aggregateSources(vault: string): SourcesReport {
+ const dirs = brainDirs(vault);
+ const buckets = new Map<string, Bucket>();
+ scanDir(dirs.inbox, true, buckets);
+ scanDir(dirs.processed, false, buckets);
+
+ const sources = [...buckets.values()]
+ .map((b) => ({
+ agent: b.agent,
+ source_type: b.source_type,
+ active: b.active,
+ processed: b.processed,
+ distinct_topics: b.topics.size,
+ }))
+ .toSorted((a, b) =>
+ a.agent !== b.agent
+ ? a.agent < b.agent
+ ? -1
+ : 1
+ : a.source_type < b.source_type
+ ? -1
+ : a.source_type > b.source_type
+ ? 1
+ : 0,
+ );
+
+ return {
+ sources,
+ total_active: sources.reduce((n, s) => n + s.active, 0),
+ total_processed: sources.reduce((n, s) => n + s.processed, 0),
+ };
+}
diff --git a/src/core/brain/sessions/import.ts b/src/core/brain/sessions/import.ts
index f3e36333..c4e9189d 100644
--- a/src/core/brain/sessions/import.ts
+++ b/src/core/brain/sessions/import.ts
@@ -70,6 +70,12 @@ export interface ImportSessionOptions {
* re-scanned per file. Internal contract; CLI does not pass it.
*/
readonly dedupIndex?: Map<string, DedupIndexEntry>;
+ /**
+ * Vault portability suite (v0.22.0). When true, session-imported
+ * signals store their raw body through the deterministic codec
+ * (`writeSignal({ rawCodec: true })`). Default off -> verbatim bodies.
+ */
+ readonly rawCodec?: boolean;
}
export interface ImportSessionResult {
@@ -179,6 +185,7 @@ export async function importSession(
dedup_hash: input.dedupHash,
session_ref: sessionRef,
...(input.note ? { raw: input.note } : {}),
+ ...(opts.rawCodec === true ? { rawCodec: true } : {}),
});
dedup.set(input.dedupHash, { id: res.id, path: res.path });
signalsCreated++;
diff --git a/src/core/brain/signal.ts b/src/core/brain/signal.ts
index 5280d2bd..8bbabf84 100644
--- a/src/core/brain/signal.ts
+++ b/src/core/brain/signal.ts
@@ -27,6 +27,7 @@
import type { FrontmatterMap } from "../types.ts";
import { sanitiseTextField } from "../redactor.ts";
import { writeFrontmatterAtomic, parseFrontmatter } from "../vault.ts";
+import { compress, expand, CODEC_VERSION } from "./portability/codec.ts";
import { allocateSlug, brainDirs, validateIsoDate } from "./paths.ts";
import {
BRAIN_SIGNAL_SIGN,
@@ -77,6 +78,13 @@ export interface WriteSignalInput {
readonly dedup_hash?: string;
/** Session coordinates `<path>#<turn-id>` (§16). */
readonly session_ref?: string;
+ /**
+ * Vault portability suite (v0.22.0). Opt-in: when true and `raw` is
+ * present, the body is stored through the deterministic codec and a
+ * `_raw_codec` marker is stamped so `parseSignal` expands it on read.
+ * Default (absent/false) writes the raw body verbatim - byte-identical.
+ */
+ readonly rawCodec?: boolean;
}
export interface WriteSignalOptions {
@@ -192,7 +200,18 @@ export function writeSignal(
metadata["session_ref"] = sanitised.session_ref.trim();
}
- const body = renderSignalBody(sanitised);
+ // Opt-in codec (v0.22.0): store the raw body compressed and stamp a
+ // `_raw_codec` marker so the reader expands it. Default path is verbatim.
+ let bodyInput = sanitised;
+ if (sanitised.rawCodec === true && sanitised.raw) {
+ // Normalise trailing whitespace first (matching renderSignalBody on the
+ // verbatim path) so the codec and verbatim paths agree byte-for-byte on
+ // read; otherwise a trailing whitespace run would survive inside a marker.
+ const normalised = sanitised.raw.replace(/\s+$/u, "");
+ bodyInput = { ...sanitised, raw: compress(normalised) };
+ metadata["_raw_codec"] = CODEC_VERSION;
+ }
+ const body = renderSignalBody(bodyInput);
writeFrontmatterAtomic(allocated.path, metadata, body, {
overwrite: false,
existsErrorKind: "signal",
@@ -293,7 +312,18 @@ export function parseSignal(path: string): BrainSignal {
source = [...(meta["source"] as ReadonlyArray<string>)];
}
- const raw = extractRawSection(body);
+ const rawSection = extractRawSection(body);
+ // Expand a codec-compressed body iff the signal carries a marker that
+ // matches the codec version we support (v0.22.0). Signals without the
+ // marker - i.e. every default-config signal - take the verbatim path
+ // unchanged. A marker with an unknown version fails fast rather than
+ // silently misdecoding a future or hand-authored payload.
+ const rawCodec = meta["_raw_codec"];
+ if (rawCodec !== undefined && rawCodec !== CODEC_VERSION) {
+ throw new Error(`signal field '_raw_codec' must be ${JSON.stringify(CODEC_VERSION)} (${path})`);
+ }
+ const raw =
+ rawSection !== undefined && rawCodec === CODEC_VERSION ? expand(rawSection) : rawSection;
// Capture-extension optional fields. Absence stays as `undefined`
// on the returned object — never coerced to a default, so callers
diff --git a/src/core/config.ts b/src/core/config.ts
index b1f497aa..4854adbf 100644
--- a/src/core/config.ts
+++ b/src/core/config.ts
@@ -13,6 +13,7 @@ import { join } from "node:path";
import { atomicWriteFileSync } from "./fs-atomic.ts";
import { isFile } from "./fs-utils.ts";
+import { resolveActiveProfileVault } from "./brain/portability/profiles.ts";
import type { ConfigDiscovery } from "./types.ts";
const SECRET_KEY_PARTS = [
@@ -163,7 +164,12 @@ export function resolveTimezone(configPath?: string): string | null {
export function resolveVault(configPath?: string): string | null {
const env = process.env["VAULT_DIR"];
if (env) return expandTilde(env);
- const cfg = discoverConfig(configPath).data["vault"];
+ // Multi-vault profiles (v0.22.0): an active named profile overrides the
+ // bare `vault` key. With no profiles registry the result is unchanged.
+ const discovery = discoverConfig(configPath);
+ const profileVault = resolveActiveProfileVault(discovery.path);
+ if (profileVault) return expandTilde(profileVault);
+ const cfg = discovery.data["vault"];
if (cfg) return expandTilde(cfg);
return null;
}
diff --git a/src/mcp/brain-tools.ts b/src/mcp/brain-tools.ts
index 9dd62259..61846022 100644
--- a/src/mcp/brain-tools.ts
+++ b/src/mcp/brain-tools.ts
@@ -52,6 +52,9 @@ import {
import { buildBacklinkIndex } from "../core/brain/backlinks.ts";
import { readPrefAudit } from "../core/brain/pref-audit.ts";
import { buildMorningBrief } from "../core/brain/morning-brief.ts";
+import { aggregateSources } from "../core/brain/portability/sources.ts";
+import { switchProfile, listProfiles } from "../core/brain/portability/profiles.ts";
+import { defaultConfigPath } from "../core/config.ts";
import { findUnlinkedMentions } from "../core/brain/link-graph/unlinked-mentions.ts";
import { buildConceptCluster } from "../core/brain/link-graph/concept-cluster.ts";
import { auditMoc, MocAuditError } from "../core/brain/link-graph/moc-audit.ts";
@@ -924,6 +927,41 @@ async function toolBrainMorningBrief(
};
}
+async function toolBrainSources(
+ ctx: ServerContext,
+ _args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ void _args;
+ const report = aggregateSources(ctx.vault);
+ return {
+ sources: report.sources,
+ total_active: report.total_active,
+ total_processed: report.total_processed,
+ };
+}
+
+async function toolBrainSwitchVault(
+ ctx: ServerContext,
+ args: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+ const name = coerceStr(args, "name", true)!;
+ const configPath = ctx.configPath ?? defaultConfigPath();
+ try {
+ switchProfile(configPath, name);
+ } catch (err) {
+ throw new Error(`brain_switch_vault: ${(err as Error).message ?? String(err)}`, {
+ cause: err,
+ });
+ }
+ // The running server keeps its already-resolved vault; the switch
+ // takes effect for the next server launch / CLI invocation.
+ return {
+ active: name,
+ profiles: listProfiles(configPath).profiles,
+ note: "active profile updated; takes effect on next server launch",
+ };
+}
+
// ----- brain_doctor --------------------------------------------------------
async function toolBrainDoctor(
@@ -2259,6 +2297,27 @@ export const BRAIN_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
},
handler: toolBrainMorningBrief,
},
+ {
+ name: "brain_sources",
+ description:
+ "Read-only dashboard of the brain's signals grouped by (agent, source_type) with active/processed and distinct-topic counts plus totals.",
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
+ handler: toolBrainSources,
+ },
+ {
+ name: "brain_switch_vault",
+ description:
+ "Activate a named vault profile (from the profiles registry). Updates the active pointer; the change takes effect on the next server launch - the running server keeps its already-resolved vault.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ name: { type: "string", description: "Profile name to activate." },
+ },
+ required: ["name"],
+ additionalProperties: false,
+ },
+ handler: toolBrainSwitchVault,
+ },
{
name: "brain_context_pack",
previewBudget: MCP_PREVIEW_BUDGET,
diff --git a/src/mcp/instructions.ts b/src/mcp/instructions.ts
index 9e1a9897..67dcc963 100644
--- a/src/mcp/instructions.ts
+++ b/src/mcp/instructions.ts
@@ -108,7 +108,11 @@ export function buildInstructions(opts: BuildInstructionsOpts | string): string
"and revision + content-hash before/after.\n" +
" - brain_morning_brief — read-only session-start summary: top " +
"confirmed preferences, recent reconcile open questions, and recent " +
- "notes, bounded by a character budget.\n\n" +
+ "notes, bounded by a character budget.\n" +
+ " - brain_sources — read-only dashboard of signals grouped by " +
+ "(agent, source_type) with active/processed and distinct-topic counts.\n" +
+ " - brain_switch_vault — activate a named vault profile; the change " +
+ "takes effect on the next server launch.\n\n" +
"Skip Brain calls for casual chat, exploration without a stated " +
"rule, read-only inspection, and trivial edits. A misrecorded " +
"signal is worse than a missed one — the dream pass surfaces " +
diff --git a/tests/cli/vault-portability-cli.test.ts b/tests/cli/vault-portability-cli.test.ts
new file mode 100644
index 00000000..a975600b
--- /dev/null
+++ b/tests/cli/vault-portability-cli.test.ts
@@ -0,0 +1,98 @@
+/**
+ * CLI surface for the Vault portability suite (v0.22.0):
+ * `o2b brain codec | sources | graph-export | graph-import` and
+ * `o2b vault profile | map`. Locks argument shape, --json, and exit
+ * codes; the underlying cores have their own unit coverage.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCli } from "../helpers/run-cli.ts";
+
+let tmp: string;
+let vault: string;
+let config: string;
+
+beforeEach(() => {
+ tmp = mkdtempSync(join(tmpdir(), "o2b-vps-cli-"));
+ vault = join(tmp, "vault");
+ config = join(tmp, "config.yaml");
+});
+afterEach(() => rmSync(tmp, { recursive: true, force: true }));
+
+async function bootstrap(): Promise<void> {
+ expect(
+ (await runCli(["init", "--vault", vault, "--name", "T"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } }))
+ .returncode,
+ ).toBe(0);
+ expect(
+ (await runCli(["brain", "init", "--vault", vault], { env: { OPEN_SECOND_BRAIN_CONFIG: config } }))
+ .returncode,
+ ).toBe(0);
+}
+
+describe("o2b brain codec", () => {
+ test("compress | expand round-trips via stdin", async () => {
+ const text = "line\n\n\n\n\nbody";
+ const c = await runCli(["brain", "codec", "--compress"], { stdin: text });
+ expect(c.returncode).toBe(0);
+ const e = await runCli(["brain", "codec", "--expand"], { stdin: c.stdout });
+ expect(e.returncode).toBe(0);
+ expect(e.stdout).toBe(text);
+ });
+});
+
+describe("o2b brain sources / graph", () => {
+ test("sources --json on a fresh vault", async () => {
+ await bootstrap();
+ const r = await runCli(["brain", "sources", "--json"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });
+ expect(r.returncode).toBe(0);
+ expect(JSON.parse(r.stdout).sources).toEqual([]);
+ });
+
+ test("graph-export then graph-import round-trips a user page", async () => {
+ await bootstrap();
+ writeFileSync(join(vault, "Note.md"), "---\ntitle: Note\n---\nlinks to [[Other]].\n");
+ const exp = await runCli(["brain", "graph-export"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });
+ expect(exp.returncode).toBe(0);
+ const graphFile = join(tmp, "graph.json");
+ writeFileSync(graphFile, exp.stdout);
+ const imp = await runCli(["brain", "graph-import", graphFile, "--mode", "skip", "--json"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(imp.returncode).toBe(0);
+ // Note already exists -> skipped (idempotent).
+ expect(JSON.parse(imp.stdout).skipped).toContain("Note.md");
+ });
+
+ test("graph-import rejects an unknown --mode", async () => {
+ await bootstrap();
+ writeFileSync(join(tmp, "g.json"), '{"version":"1","nodes":[]}');
+ const r = await runCli(["brain", "graph-import", join(tmp, "g.json"), "--mode", "bogus"], {
+ env: { OPEN_SECOND_BRAIN_CONFIG: config },
+ });
+ expect(r.returncode).not.toBe(0);
+ });
+});
+
+describe("o2b vault profile / map", () => {
+ test("profile create / switch / list", async () => {
+ await bootstrap();
+ const env = { OPEN_SECOND_BRAIN_CONFIG: config };
+ expect((await runCli(["vault", "profile", "create", "work", "/srv/v/work"], { env })).returncode).toBe(0);
+ expect((await runCli(["vault", "profile", "switch", "work"], { env })).returncode).toBe(0);
+ const list = await runCli(["vault", "profile", "list", "--json"], { env });
+ expect(list.returncode).toBe(0);
+ expect(JSON.parse(list.stdout).active).toBe("work");
+ });
+
+ test("map --json shows the default token table", async () => {
+ await bootstrap();
+ const r = await runCli(["vault", "map", "--json"], { env: { OPEN_SECOND_BRAIN_CONFIG: config } });
+ expect(r.returncode).toBe(0);
+ expect(JSON.parse(r.stdout).inbox).toBe("inbox");
+ });
+});
diff --git a/tests/core/brain.sessions.codec.test.ts b/tests/core/brain.sessions.codec.test.ts
new file mode 100644
index 00000000..81fd9050
--- /dev/null
+++ b/tests/core/brain.sessions.codec.test.ts
@@ -0,0 +1,73 @@
+/**
+ * Opt-in session codec integration (Vault portability suite, Feature 1
+ * Task 7). With `rawCodec`, writeSignal stores the raw body compressed
+ * and stamps a `_raw_codec` marker; parseSignal expands it on read.
+ * Without the flag (default) the body is verbatim and the read path is
+ * byte-identical to pre-suite.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { writeSignal, parseSignal } from "../../src/core/brain/signal.ts";
+
+let vault: string;
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-sig-codec-"));
+ mkdirSync(join(vault, "Brain", "inbox"), { recursive: true });
+});
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+// Whitespace-heavy body so the codec's body savings exceed the fixed
+// `_raw_codec` marker-line overhead, making the on-disk file shorter.
+const RAW =
+ "Observed run:\n\n```bash\ngit status\n```\n\nThen a note." +
+ "\n".repeat(60) +
+ "Tail after a long blank run.";
+
+function write(rawCodec: boolean): string {
+ return writeSignal(vault, {
+ topic: "obs",
+ signal: "positive",
+ agent: "claude",
+ principle: "capture the observation",
+ created_at: "2026-05-29T10:00:00Z",
+ date: "2026-05-29",
+ slug: "obs",
+ raw: RAW,
+ ...(rawCodec ? { rawCodec: true } : {}),
+ }).path;
+}
+
+describe("signal raw codec", () => {
+ test("with rawCodec: stamps the marker and round-trips the raw on read", () => {
+ const path = write(true);
+ const onDisk = readFileSync(path, "utf8");
+ expect(onDisk).toContain("_raw_codec");
+ expect(parseSignal(path).raw).toBe(RAW);
+ });
+
+ test("with rawCodec: the stored body is shorter than verbatim", () => {
+ const compressed = readFileSync(write(true), "utf8").length;
+ const verbatim = readFileSync(write(false), "utf8").length;
+ expect(compressed).toBeLessThan(verbatim);
+ });
+
+ test("without rawCodec (default): no marker, raw stored verbatim", () => {
+ const path = write(false);
+ const onDisk = readFileSync(path, "utf8");
+ expect(onDisk).not.toContain("_raw_codec");
+ expect(onDisk).toContain("Tail after a long blank run.");
+ expect(parseSignal(path).raw).toBe(RAW);
+ });
+
+ test("parseSignal fails fast on an unknown _raw_codec version", () => {
+ const path = write(true);
+ // Tamper the marker to an unsupported codec version.
+ const tampered = readFileSync(path, "utf8").replace(/_raw_codec: .*/u, "_raw_codec: 999");
+ writeFileSync(path, tampered, "utf8");
+ expect(() => parseSignal(path)).toThrow(/_raw_codec/);
+ });
+});
diff --git a/tests/core/brain/portability/codec.test.ts b/tests/core/brain/portability/codec.test.ts
new file mode 100644
index 00000000..6823fc98
--- /dev/null
+++ b/tests/core/brain/portability/codec.test.ts
@@ -0,0 +1,111 @@
+/**
+ * Deterministic session codec (Vault portability suite, Feature 1).
+ *
+ * A pure, lossless, language-agnostic codec: `expand(compress(x)) === x`
+ * for ALL input (brain memory must never lose data), with token savings
+ * from reversibly collapsing whitespace and blank-line runs. Fenced and
+ * inline code are protected (never altered), and structured content
+ * (URLs, paths, identifiers, version numbers) is preserved byte-for-byte
+ * by construction. No language word lists; detection is structural.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { compress, expand, CODEC_VERSION } from "../../../../src/core/brain/portability/codec.ts";
+
+const FIXTURES: ReadonlyArray<{ name: string; text: string }> = [
+ { name: "empty", text: "" },
+ { name: "whitespace only", text: " \n\n\n\t " },
+ { name: "plain prose", text: "The quick brown fox jumps over the lazy dog." },
+ {
+ name: "prose with blank-line runs",
+ text: "First paragraph.\n\n\n\nSecond paragraph after several blanks.\n\n\nEnd.",
+ },
+ {
+ name: "deep indentation",
+ text: "root\n deeply indented line with eight leading spaces\nback",
+ },
+ {
+ name: "structured content",
+ text: "See https://example.com/a/b?x=1#frag and /usr/local/lib/foo.ts plus foo_bar.BazQux and v1.2.3-rc.4.",
+ },
+ {
+ name: "fenced code block with significant indentation",
+ text: "intro\n\n```ts\nfunction f() {\n return [1, 2, 3];\n}\n```\n\noutro",
+ },
+ {
+ name: "inline code with runs",
+ text: "use `a b` and `c\td` inline, then four spaces in prose.",
+ },
+ {
+ name: "literal sentinel in input (PUA char)",
+ text: "edge  case with a private-use char and  doubled.",
+ },
+ {
+ name: "mixed agent observation",
+ text: "## Turn 3\n\nThe agent ran:\n\n```bash\ngit commit -m 'x'\n```\n\nResult: ok.\n\n\nNext step at /tmp/out.\n",
+ },
+];
+
+describe("session codec", () => {
+ test("exposes a CODEC_VERSION", () => {
+ expect(typeof CODEC_VERSION).toBe("string");
+ expect(CODEC_VERSION.length).toBeGreaterThan(0);
+ });
+
+ test("round-trips every fixture exactly (lossless)", () => {
+ for (const f of FIXTURES) {
+ expect(expand(compress(f.text))).toBe(f.text);
+ }
+ });
+
+ test("never expands the payload for sentinel-free input (compressed <= original)", () => {
+ // The codec only ever shrinks or matches, EXCEPT when the raw input
+ // already contains the private-use sentinel (never true for real text),
+ // which must be escaped (+1 char each) to keep round-trip exact.
+ const SENTINEL = String.fromCodePoint(0xe000);
+ for (const f of FIXTURES) {
+ if (f.text.includes(SENTINEL)) continue;
+ expect(compress(f.text).length).toBeLessThanOrEqual(f.text.length);
+ }
+ });
+
+ test("escaping keeps round-trip exact even when input contains the sentinel", () => {
+ const withSentinel = "before  middle  after";
+ expect(expand(compress(withSentinel))).toBe(withSentinel);
+ });
+
+ test("actually shrinks blank-line and indentation runs", () => {
+ const text = "a\n\n\n\n\n\nb"; // six newlines
+ expect(compress(text).length).toBeLessThan(text.length);
+ expect(expand(compress(text))).toBe(text);
+ });
+
+ test("preserves structured content byte-for-byte in the compressed form", () => {
+ const text = "url https://example.com/x and path /a/b/c.ts and ver 1.2.3";
+ const c = compress(text);
+ // No whitespace runs to collapse here, so the structured tokens survive verbatim.
+ expect(c).toContain("https://example.com/x");
+ expect(c).toContain("/a/b/c.ts");
+ expect(c).toContain("1.2.3");
+ });
+
+ test("does not collapse whitespace inside fenced or inline code", () => {
+ const fenced = "```\n indented code\n```";
+ expect(expand(compress(fenced))).toBe(fenced);
+ const inline = "`a b`";
+ // Inline code content is protected: round-trip exact and untouched.
+ expect(expand(compress(inline))).toBe(inline);
+ });
+
+ test("is deterministic", () => {
+ const text = FIXTURES[5]!.text;
+ expect(compress(text)).toBe(compress(text));
+ });
+
+ test("expand tolerates non-codec text (no markers) by returning it unchanged", () => {
+ expect(expand("just plain text, never compressed")).toBe(
+ "just plain text, never compressed",
+ );
+ });
+});
diff --git a/tests/core/brain/portability/graph-export.test.ts b/tests/core/brain/portability/graph-export.test.ts
new file mode 100644
index 00000000..46f12299
--- /dev/null
+++ b/tests/core/brain/portability/graph-export.test.ts
@@ -0,0 +1,68 @@
+/**
+ * Vault graph export (Vault portability suite, Feature 5).
+ *
+ * `exportVaultGraph` walks the user's vault pages (excluding the Brain
+ * machinery root and standard ignored dirs), extracting wikilinks and
+ * typed-relation frontmatter into a stable, sorted graph. Re-export is
+ * byte-identical. Pure read-only.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ exportVaultGraph,
+ GRAPH_VERSION,
+} from "../../../../src/core/brain/portability/graph.ts";
+
+let vault: string;
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-graph-export-"));
+});
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+function note(rel: string, content: string): void {
+ const p = join(vault, rel);
+ mkdirSync(join(p, ".."), { recursive: true });
+ writeFileSync(p, content, "utf8");
+}
+
+describe("exportVaultGraph", () => {
+ test("emits a versioned graph of user pages with links and relations", () => {
+ note("Notes/Alpha.md", "---\ntitle: Alpha\nrelated: [[Gamma]]\n---\nlinks to [[Beta]] here.\n");
+ note("Notes/Beta.md", "---\ntitle: Beta\n---\nleaf node.\n");
+ const graph = exportVaultGraph(vault);
+ expect(graph.version).toBe(GRAPH_VERSION);
+ const alpha = graph.nodes.find((n) => n.id === "Alpha");
+ expect(alpha).toBeDefined();
+ expect(alpha!.links).toContain("Beta");
+ expect(alpha!.relations["related"]).toContain("Gamma");
+ });
+
+ test("excludes the Brain machinery root", () => {
+ note("Notes/User.md", "---\ntitle: User\n---\nx\n");
+ note("Brain/preferences/pref-x.md", "---\nkind: brain-preference\nid: pref-x\ntitle: PrefX\n---\ny\n");
+ const ids = exportVaultGraph(vault).nodes.map((n) => n.id);
+ expect(ids).toContain("User");
+ expect(ids).not.toContain("pref-x");
+ });
+
+ test("nodes and links are sorted (stable, deterministic)", () => {
+ note("Notes/B.md", "---\ntitle: B\n---\nsee [[Z]] and [[A]].\n");
+ note("Notes/A.md", "---\ntitle: A\n---\nleaf.\n");
+ const g1 = exportVaultGraph(vault);
+ const g2 = exportVaultGraph(vault);
+ expect(JSON.stringify(g1)).toBe(JSON.stringify(g2));
+ const ids = g1.nodes.map((n) => n.id);
+ expect(ids).toEqual([...ids].toSorted());
+ const b = g1.nodes.find((n) => n.id === "B")!;
+ expect(b.links).toEqual(["A", "Z"]);
+ });
+
+ test("an empty vault yields a graph with no nodes", () => {
+ const g = exportVaultGraph(vault);
+ expect(g.nodes).toHaveLength(0);
+ });
+});
diff --git a/tests/core/brain/portability/graph-import.test.ts b/tests/core/brain/portability/graph-import.test.ts
new file mode 100644
index 00000000..39dfbce8
--- /dev/null
+++ b/tests/core/brain/portability/graph-import.test.ts
@@ -0,0 +1,119 @@
+/**
+ * Vault graph import (Vault portability suite, Feature 5, Task 4).
+ *
+ * `importVaultGraph` reconstructs page stubs (frontmatter title + single
+ * typed relations, body wikilinks) under three conflict modes - skip
+ * (default) / overwrite / merge. Writes go through the atomic writer and
+ * `ensureInsideVault`; skip is idempotent; export -> import -> export
+ * round-trips body links and single relations.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ exportVaultGraph,
+ importVaultGraph,
+} from "../../../../src/core/brain/portability/graph.ts";
+
+let vault: string;
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-graph-import-"));
+});
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+const GRAPH: {
+ version: string;
+ nodes: Array<{
+ id: string;
+ path: string;
+ title: string;
+ links: string[];
+ relations: Record<string, string[]>;
+ }>;
+} = {
+ version: "1",
+ nodes: [
+ {
+ id: "Alpha",
+ path: "Notes/Alpha.md",
+ title: "Alpha",
+ links: ["Beta"],
+ relations: { related: ["Gamma"] },
+ },
+ { id: "Beta", path: "Notes/Beta.md", title: "Beta", links: [], relations: {} },
+ ],
+};
+
+describe("importVaultGraph", () => {
+ test("creates page stubs and round-trips links + single relations", () => {
+ const res = importVaultGraph(vault, GRAPH, { mode: "skip" });
+ expect(res.created.toSorted()).toEqual(["Notes/Alpha.md", "Notes/Beta.md"]);
+ expect(existsSync(join(vault, "Notes", "Alpha.md"))).toBe(true);
+
+ const re = exportVaultGraph(vault);
+ const alpha = re.nodes.find((n) => n.id === "Alpha")!;
+ expect(alpha.links).toContain("Beta");
+ expect(alpha.relations["related"]).toContain("Gamma");
+ });
+
+ test("skip mode is idempotent and never overwrites", () => {
+ importVaultGraph(vault, GRAPH, { mode: "skip" });
+ const before = readFileSync(join(vault, "Notes", "Alpha.md"), "utf8");
+ const res = importVaultGraph(vault, GRAPH, { mode: "skip" });
+ expect(res.skipped).toContain("Notes/Alpha.md");
+ expect(res.created).toHaveLength(0);
+ expect(readFileSync(join(vault, "Notes", "Alpha.md"), "utf8")).toBe(before);
+ });
+
+ test("overwrite mode replaces an existing page", () => {
+ mkdirSync(join(vault, "Notes"), { recursive: true });
+ writeFileSync(join(vault, "Notes", "Beta.md"), "---\ntitle: Old\n---\nold body\n", "utf8");
+ const res = importVaultGraph(vault, GRAPH, { mode: "overwrite" });
+ expect(res.overwritten).toContain("Notes/Beta.md");
+ expect(readFileSync(join(vault, "Notes", "Beta.md"), "utf8")).not.toContain("old body");
+ });
+
+ test("merge mode unions wikilinks with an existing page", () => {
+ mkdirSync(join(vault, "Notes"), { recursive: true });
+ writeFileSync(
+ join(vault, "Notes", "Alpha.md"),
+ "---\ntitle: Alpha\n---\nexisting link to [[Delta]].\n",
+ "utf8",
+ );
+ const res = importVaultGraph(vault, GRAPH, { mode: "merge" });
+ expect(res.merged).toContain("Notes/Alpha.md");
+ const alpha = exportVaultGraph(vault).nodes.find((n) => n.id === "Alpha")!;
+ expect(alpha.links).toContain("Beta"); // incoming
+ expect(alpha.links).toContain("Delta"); // pre-existing
+ });
+
+ test("rejects a node path that escapes the vault", () => {
+ const evil = { version: "1", nodes: [{ id: "x", path: "../escape.md", title: "x", links: [], relations: {} }] };
+ const res = importVaultGraph(vault, evil, { mode: "overwrite" });
+ expect(res.created).toHaveLength(0);
+ expect(res.rejected).toContain("../escape.md");
+ expect(existsSync(join(vault, "..", "escape.md"))).toBe(false);
+ });
+
+ test("rejects a malformed node and continues with the valid ones", () => {
+ const mixed = {
+ version: "1",
+ nodes: [
+ { path: 42 }, // path not a string
+ { path: "Notes/BadLinks.md", links: [7] }, // links not strings
+ { path: "Notes/BadRel.md", relations: { related: "x" } }, // relations value not an array
+ { path: "Notes/Good.md", title: "Good", links: ["Beta"], relations: {} },
+ ],
+ };
+ const res = importVaultGraph(vault, mixed as never, { mode: "overwrite" });
+ expect(res.created).toEqual(["Notes/Good.md"]);
+ expect(res.rejected).toContain("Notes/BadLinks.md");
+ expect(res.rejected).toContain("Notes/BadRel.md");
+ expect(res.rejected).toContain("42");
+ expect(existsSync(join(vault, "Notes", "Good.md"))).toBe(true);
+ expect(existsSync(join(vault, "Notes", "BadLinks.md"))).toBe(false);
+ });
+});
diff --git a/tests/core/brain/portability/profiles.test.ts b/tests/core/brain/portability/profiles.test.ts
new file mode 100644
index 00000000..47adb78c
--- /dev/null
+++ b/tests/core/brain/portability/profiles.test.ts
@@ -0,0 +1,90 @@
+/**
+ * Named multi-vault profiles (Vault portability suite, Feature 4).
+ *
+ * A profile registry (name -> vault path) stored in a profiles.json
+ * beside the config, with list / create / switch. Activation is a
+ * pointer in that file (no symlinks). `resolveVault` consults the active
+ * profile before the bare config `vault` key; with no profiles it is
+ * unchanged (back-compat).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ createProfile,
+ listProfiles,
+ switchProfile,
+ resolveActiveProfileVault,
+} from "../../../../src/core/brain/portability/profiles.ts";
+import { resolveVault } from "../../../../src/core/config.ts";
+import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
+
+let home: string;
+let configPath: string;
+let previousVaultDir: string | undefined;
+
+beforeEach(() => {
+ home = mkdtempSync(join(tmpdir(), "o2b-profiles-"));
+ configPath = join(home, "config.yaml");
+ atomicWriteFileSync(configPath, `vault: ${join(home, "default-vault")}\n`);
+ previousVaultDir = process.env["VAULT_DIR"];
+ delete process.env["VAULT_DIR"];
+});
+afterEach(() => {
+ if (previousVaultDir === undefined) delete process.env["VAULT_DIR"];
+ else process.env["VAULT_DIR"] = previousVaultDir;
+ rmSync(home, { recursive: true, force: true });
+});
+
+describe("profile registry", () => {
+ test("create + list", () => {
+ createProfile(configPath, "work", "/srv/vaults/work");
+ createProfile(configPath, "personal", "/srv/vaults/personal");
+ const { profiles, active } = listProfiles(configPath);
+ expect(profiles.map((p) => p.name).toSorted()).toEqual(["personal", "work"]);
+ expect(active).toBeNull();
+ });
+
+ test("switch sets the active pointer", () => {
+ createProfile(configPath, "work", "/srv/vaults/work");
+ switchProfile(configPath, "work");
+ expect(listProfiles(configPath).active).toBe("work");
+ expect(resolveActiveProfileVault(configPath)).toBe("/srv/vaults/work");
+ });
+
+ test("switching to an unknown profile throws", () => {
+ expect(() => switchProfile(configPath, "ghost")).toThrow();
+ });
+
+ test("resolveActiveProfileVault is null with no active profile", () => {
+ expect(resolveActiveProfileVault(configPath)).toBeNull();
+ });
+
+ test("a malformed registry never clobbers stored profiles on a mutating call", () => {
+ const registry = join(home, "profiles.json");
+ atomicWriteFileSync(registry, "{ this is not valid json");
+ // Read-only callers tolerate the malformed file (treat as empty)...
+ expect(listProfiles(configPath).profiles).toHaveLength(0);
+ expect(resolveActiveProfileVault(configPath)).toBeNull();
+ // ...but a mutating call fails fast instead of saving over it.
+ expect(() => createProfile(configPath, "work", "/srv/vaults/work")).toThrow(/malformed/);
+ expect(() => switchProfile(configPath, "work")).toThrow(/malformed/);
+ // The original bytes are left untouched.
+ expect(readFileSync(registry, "utf8")).toBe("{ this is not valid json");
+ });
+});
+
+describe("resolveVault integration", () => {
+ test("returns the active profile's vault when one is active", () => {
+ createProfile(configPath, "work", "/srv/vaults/work");
+ switchProfile(configPath, "work");
+ expect(resolveVault(configPath)).toBe("/srv/vaults/work");
+ });
+
+ test("falls back to the config vault when no profile is active (back-compat)", () => {
+ expect(resolveVault(configPath)).toBe(join(home, "default-vault"));
+ });
+});
diff --git a/tests/core/brain/portability/role-tokens-wiring.test.ts b/tests/core/brain/portability/role-tokens-wiring.test.ts
new file mode 100644
index 00000000..02181b37
--- /dev/null
+++ b/tests/core/brain/portability/role-tokens-wiring.test.ts
@@ -0,0 +1,73 @@
+/**
+ * Vault-map wiring (Vault portability suite, Feature 3, Task 8).
+ *
+ * The shared role-token resolver feeds two content surfaces: graph-import
+ * target paths and scan-inline read paths. An absent map leaves both
+ * unchanged; the FIXED Brain machinery layout is never routed through it.
+ */
+
+import { afterEach, beforeEach, describe, 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 { importVaultGraph } from "../../../../src/core/brain/portability/graph.ts";
+import { scanInline } from "../../../../src/core/brain/inline-scan.ts";
+import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
+
+let vault: string;
+let configHome: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-vmap-wiring-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-vmap-wiring-cfg-"));
+ const cfg = join(configHome, "config.yaml");
+ atomicWriteFileSync(cfg, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath: cfg });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+function writeVaultMap(body: string): void {
+ writeFileSync(join(vault, "Brain", "_vault-map.yaml"), body, "utf8");
+}
+
+describe("graph import token resolution", () => {
+ test("resolves a {{role}} token in the target path via the vault-map", () => {
+ writeVaultMap("projects: Work/Projects\n");
+ const graph = {
+ version: "1",
+ nodes: [{ path: "{{projects}}/Foo.md", title: "Foo", links: [], relations: {} }],
+ };
+ const res = importVaultGraph(vault, graph, { mode: "overwrite" });
+ expect(res.created).toContain("{{projects}}/Foo.md");
+ expect(existsSync(join(vault, "Work", "Projects", "Foo.md"))).toBe(true);
+ });
+
+ test("an absent map leaves a literal token folder name in place", () => {
+ const graph = {
+ version: "1",
+ nodes: [{ path: "{{projects}}/Bar.md", title: "Bar", links: [], relations: {} }],
+ };
+ importVaultGraph(vault, graph, { mode: "overwrite" });
+ // Default token resolves to its own name "projects".
+ expect(existsSync(join(vault, "projects", "Bar.md"))).toBe(true);
+ });
+});
+
+describe("scan-inline token resolution", () => {
+ test("resolves a {{role}} read path to the mapped folder", async () => {
+ writeVaultMap("projects: Work\n");
+ mkdirSync(join(vault, "Work"), { recursive: true });
+ writeFileSync(
+ join(vault, "Work", "note.md"),
+ "@osb feedback negative topic=tokenised-read-path principle=p\n",
+ "utf8",
+ );
+ const res = await scanInline(vault, { agent: "test", paths: ["{{projects}}"] });
+ expect(res.created).toBeGreaterThanOrEqual(1);
+ });
+});
diff --git a/tests/core/brain/portability/role-tokens.test.ts b/tests/core/brain/portability/role-tokens.test.ts
new file mode 100644
index 00000000..cefea381
--- /dev/null
+++ b/tests/core/brain/portability/role-tokens.test.ts
@@ -0,0 +1,97 @@
+/**
+ * Vault-map role-token resolution (Vault portability suite, Feature 3).
+ *
+ * Resolves `{{role}}` tokens to user content folder names via an optional
+ * `Brain/_vault-map.yaml`, falling back to built-in defaults when the file
+ * or a token is absent. Mapped values that attempt path traversal are
+ * rejected (fall back to the default). The FIXED Brain machinery layout
+ * is never routed through this resolver.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+ DEFAULT_ROLE_TOKENS,
+ loadVaultMap,
+ resolveRoleToken,
+ resolveTokens,
+} from "../../../../src/core/brain/portability/role-tokens.ts";
+
+let vault: string;
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-vault-map-"));
+ mkdirSync(join(vault, "Brain"), { recursive: true });
+});
+afterEach(() => rmSync(vault, { recursive: true, force: true }));
+
+function writeMap(body: string): void {
+ writeFileSync(join(vault, "Brain", "_vault-map.yaml"), body, "utf8");
+}
+
+describe("DEFAULT_ROLE_TOKENS", () => {
+ test("covers the canonical PKM roles", () => {
+ for (const role of ["inbox", "projects", "areas", "resources", "archive"]) {
+ expect(typeof DEFAULT_ROLE_TOKENS[role]!).toBe("string");
+ }
+ });
+});
+
+describe("resolveRoleToken", () => {
+ test("returns the default when the map has no override", () => {
+ expect(resolveRoleToken({}, "inbox")).toBe(DEFAULT_ROLE_TOKENS["inbox"]!);
+ });
+ test("returns the override when present", () => {
+ expect(resolveRoleToken({ inbox: "Zettelkasten/Inbox" }, "inbox")).toBe(
+ "Zettelkasten/Inbox",
+ );
+ });
+ test("strips surrounding braces and whitespace", () => {
+ expect(resolveRoleToken({ inbox: "In" }, "{{ inbox }}")).toBe("In");
+ });
+ test("an unknown token resolves to its literal name", () => {
+ expect(resolveRoleToken({}, "{{custom}}")).toBe("custom");
+ });
+});
+
+describe("resolveTokens", () => {
+ test("replaces every token in a string", () => {
+ const map = { inbox: "In", projects: "Proj" };
+ expect(resolveTokens(map, "{{inbox}}/a and {{projects}}/b")).toBe("In/a and Proj/b");
+ });
+ test("leaves non-token text untouched", () => {
+ expect(resolveTokens({}, "plain/path")).toBe("plain/path");
+ });
+});
+
+describe("loadVaultMap", () => {
+ test("returns built-in defaults when no map file exists", () => {
+ const map = loadVaultMap(vault);
+ expect(map["inbox"]).toBe(DEFAULT_ROLE_TOKENS["inbox"]!);
+ });
+ test("merges overrides over defaults", () => {
+ writeMap("inbox: Zettelkasten/Inbox\nprojects: Work/Projects\n");
+ const map = loadVaultMap(vault);
+ expect(map["inbox"]).toBe("Zettelkasten/Inbox");
+ expect(map["projects"]).toBe("Work/Projects");
+ expect(map["areas"]).toBe(DEFAULT_ROLE_TOKENS["areas"]!);
+ });
+ test("rejects a traversal value and falls back to the default", () => {
+ writeMap("inbox: ../../etc\n");
+ expect(loadVaultMap(vault)["inbox"]).toBe(DEFAULT_ROLE_TOKENS["inbox"]!);
+ });
+ test("rejects an absolute value and falls back to the default", () => {
+ writeMap("inbox: /etc/passwd\n");
+ expect(loadVaultMap(vault)["inbox"]).toBe(DEFAULT_ROLE_TOKENS["inbox"]!);
+ });
+ test("allows a folder name containing spaces", () => {
+ writeMap("daily-notes: Daily Notes\n");
+ expect(loadVaultMap(vault)["daily-notes"]).toBe("Daily Notes");
+ });
+ test("is deterministic", () => {
+ writeMap("inbox: A\n");
+ expect(loadVaultMap(vault)).toEqual(loadVaultMap(vault));
+ });
+});
diff --git a/tests/core/brain/portability/sources.test.ts b/tests/core/brain/portability/sources.test.ts
new file mode 100644
index 00000000..1d852072
--- /dev/null
+++ b/tests/core/brain/portability/sources.test.ts
@@ -0,0 +1,94 @@
+/**
+ * Sources dashboard projection (Vault portability suite, Feature 2).
+ *
+ * `aggregateSources` is a pure read-only projection over the brain's
+ * signals (inbox + processed), grouped by (agent, source_type) with
+ * active/processed and distinct-topic counts. Deterministic ordering.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, renameSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { aggregateSources } from "../../../../src/core/brain/portability/sources.ts";
+import { writeSignal } from "../../../../src/core/brain/signal.ts";
+import { brainDirs } from "../../../../src/core/brain/paths.ts";
+import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
+import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
+
+let vault: string;
+let configHome: string;
+
+beforeEach(() => {
+ vault = mkdtempSync(join(tmpdir(), "o2b-sources-"));
+ configHome = mkdtempSync(join(tmpdir(), "o2b-sources-cfg-"));
+ const cfg = join(configHome, "config.yaml");
+ atomicWriteFileSync(cfg, `vault: ${vault}\n`);
+ bootstrapBrain(vault, { configPath: cfg });
+});
+afterEach(() => {
+ rmSync(vault, { recursive: true, force: true });
+ rmSync(configHome, { recursive: true, force: true });
+});
+
+function sig(opts: {
+ topic: string;
+ slug: string;
+ agent: string;
+ date: string;
+ source_type?: "live" | "inline" | "session";
+}): string {
+ const r = writeSignal(vault, {
+ topic: opts.topic,
+ signal: "positive",
+ agent: opts.agent,
+ principle: `Rule for ${opts.topic}`,
+ created_at: `${opts.date}T10:00:00Z`,
+ date: opts.date,
+ slug: opts.slug,
+ ...(opts.source_type ? { source_type: opts.source_type } : {}),
+ });
+ return r.path;
+}
+
+describe("aggregateSources", () => {
+ test("returns no rows for a fresh vault", () => {
+ expect(aggregateSources(vault).sources).toHaveLength(0);
+ });
+
+ test("groups signals by (agent, source_type) with active + distinct-topic counts", () => {
+ sig({ topic: "a", slug: "a1", agent: "claude", date: "2026-05-20" });
+ sig({ topic: "b", slug: "b1", agent: "claude", date: "2026-05-21" });
+ sig({ topic: "a", slug: "a2", agent: "claude", date: "2026-05-22" }); // dup topic
+ sig({ topic: "c", slug: "c1", agent: "codex", date: "2026-05-22", source_type: "session" });
+
+ const { sources } = aggregateSources(vault);
+ const claude = sources.find((s) => s.agent === "claude")!;
+ expect(claude.active).toBe(3);
+ expect(claude.distinct_topics).toBe(2);
+ expect(claude.source_type).toBe("live"); // absent source_type buckets as live
+ const codex = sources.find((s) => s.agent === "codex")!;
+ expect(codex.active).toBe(1);
+ expect(codex.source_type).toBe("session");
+ });
+
+ test("counts processed signals separately from active", () => {
+ const p = sig({ topic: "x", slug: "x1", agent: "claude", date: "2026-05-20" });
+ renameSync(p, join(brainDirs(vault).processed, "sig-2026-05-20-x1.md"));
+ sig({ topic: "y", slug: "y1", agent: "claude", date: "2026-05-21" });
+
+ const claude = aggregateSources(vault).sources.find((s) => s.agent === "claude")!;
+ expect(claude.active).toBe(1);
+ expect(claude.processed).toBe(1);
+ });
+
+ test("is deterministic and sorted by (agent, source_type)", () => {
+ sig({ topic: "a", slug: "a1", agent: "zeta", date: "2026-05-20" });
+ sig({ topic: "b", slug: "b1", agent: "alpha", date: "2026-05-20" });
+ const a = aggregateSources(vault);
+ const b = aggregateSources(vault);
+ expect(JSON.stringify(a)).toBe(JSON.stringify(b));
+ expect(a.sources.map((s) => s.agent)).toEqual(["alpha", "zeta"]);
+ });
+});
diff --git a/tests/mcp/mcp.test.ts b/tests/mcp/mcp.test.ts
index 8adcd038..288d1090 100644
--- a/tests/mcp/mcp.test.ts
+++ b/tests/mcp/mcp.test.ts
@@ -210,6 +210,9 @@ describe("tool listing", () => {
// Per-preference mutation audit + morning brief (added in v0.21.0).
"brain_audit",
"brain_morning_brief",
+ // Vault portability suite (added in v0.22.0).
+ "brain_sources",
+ "brain_switch_vault",
"brain_context_pack",
"brain_unlinked_mentions",
"brain_concept_synthesis",
@@ -474,7 +477,8 @@ describe("stdio loop", () => {
// + brain_pre_compress_pack (v0.20.0) = 42.
// + brain_audit (v0.21.0) = 43.
// + brain_morning_brief (v0.21.0) = 44.
- expect(list.result.tools.length).toBe(44);
+ // + brain_sources + brain_switch_vault (v0.22.0) = 46.
+ expect(list.result.tools.length).toBe(46);
});
test("returns parse error for invalid JSON", async () => {