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.jsonindex 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.jsonindex 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.mdindex 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-29Brain 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.0diff --git a/README.md b/README.mdindex 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 reviewo2b brain monthly --month 2026-05 --json # Month-level Brain synthesiso2b brain audit pref-foo --json # Full mutation trail for one preferenceo2b 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 profileo2b brain agent-query --agent claude --json # Source-agent provenance queryo2b brain agent-diff --mode diff --agent claude --agent codexo2b search "<query>" # FTS5 over the vaultdiff --git a/docs/brainstorm/vault-portability-suite/cli-output/claude.md b/docs/brainstorm/vault-portability-suite/cli-output/claude.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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-10diff --git a/docs/brainstorm/vault-portability-suite/variants.md b/docs/brainstorm/vault-portability-suite/variants.mdnew file mode 100644index 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.mdindex 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): contradicto2b 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 trailo2b 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 writeso2b brain backlinks List inbound references to a Brain artifact ido2b 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.```texto2b vault status Walks the vault under the active policy; reports include / exclude counts and which rules firedo2b 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.mdindex 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 staysbyte-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 formulaConfidence is computed for every active preference on every dreamdiff --git a/docs/mcp.md b/docs/mcp.mdindex 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 theoperator-facing core, agent-source, health, and Pay Memory tools; the fullsurface also includes Brain writer, review, query, temporal, link-graph, andsearch 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.jsonindex 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.jsonindex 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.yamlindex 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: standalonediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.yamlindex 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: standalonediff --git a/pyproject.toml b/pyproject.tomlindex 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.tsindex 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.tsindex 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 timelineaudit Render a preference's full mutation audit trailmorning-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 idmcp-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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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>): Promisreturn 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.tsindex 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 thematched 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 callersdiff --git a/src/core/config.ts b/src/core/config.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 () => {