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
/**
* `second_brain_wiring` - what this install is wired into.
*
* Two questions of one class, and both were answerable only from a
* shell. `linkedProjectsStatus` reports every registered project link
* with its pointer state and had one consumer, `o2b brain project
* status`; the per-adapter `verify()` aggregate behind `o2b install
* --check` reports whether the hosts this install wrote registrations
* into can still be reached, and had none outside the CLI. An agent on
* the MCP surface could not ask either.
*
* Nothing here computes health. Both views are a seam onto a reader
* that already exists, which is why they ship as one tool: a second
* implementation of connector health would be a second answer to a
* question that already has one.
*
* ## Why one tool with a required `view`
*
* The house idiom for a consolidated read is a `view` parameter -
* `brain_brief`, `brain_analytics` and `schema_inspect` all take one,
* and `brain/landscape-tools.ts` names the reason: schema tokens are
* paid by every client on every request. There is deliberately no
* aggregate member. Every payload stays bounded, and an operator who
* wants the hosts view does not pay for two host probes to read a
* project registry.
*
* ## Paths
*
* The project registry is keyed on absolute host paths and an MCP
* response lands in model context, so every path-valued FIELD here goes
* through {@link hostPathReference} - the same `expose_host_paths`
* contract `vault_path` obeys, generalised to a second path rather than
* reimplemented for one.
*
* The hosts view also carries free-form adapter prose, and `verify()`
* composes those sentences from `InstallEnv.home`. A store reference
* cannot render them - it keys the vault, not a third party's config
* file - so they go through {@link foldHostHome}, which folds the one
* home prefix this run resolved. The two mechanisms answer the same
* question, `expose_host_paths`, off the same config.
*/
import {
linkedProjectsStatus,
type LinkedProjectStatus,
} from "../core/brain/portability/pointer.ts";
import { defaultConfigPath } from "../core/config.ts";
import { VAULT_NOT_CONFIGURED_REASON, buildInstallEnv } from "../core/install/env.ts";
import { defaultRegistry } from "../core/install/registry.ts";
// The canonical adapter set registers itself into `defaultRegistry` at
// module-load time through this barrel, exactly as the CLI verb does.
import "../core/install/adapters/all.ts";
import type { VerifyResult } from "../core/install/types.ts";
import { dispatchByView } from "./brain/shared.ts";
import { INVALID_PARAMS, MCPError } from "./protocol.ts";
import type { ServerContext, ToolDefinition } from "./tool-contract.ts";
import {
VAULT_PATH_OUTPUT_SCHEMA,
type HostPathPolicySource,
foldHostHome,
hostPathReference,
vaultPathField,
} from "./vault-path-field.ts";
/** The tool name, shared with the tests and the registry guard. */
export const WIRING_TOOL_NAME = "second_brain_wiring";
/** The view this tool answers about linked projects. */
const PROJECTS_VIEW = "projects";
/** The view this tool answers about the hosts this install wrote into. */
const HOSTS_VIEW = "hosts";
/** Membership list of the accepted `view` values, in schema order. */
export const WIRING_VIEWS: ReadonlyArray<string> = Object.freeze([PROJECTS_VIEW, HOSTS_VIEW]);
/**
* Most project links `view=projects` carries inline.
*
* The hosts view is bounded by construction - one entry per adapter in
* a registry this build closes - and the projects view is not. Nothing
* caps `projects.json`: every `o2b brain project link` appends to it,
* so the registry grows with the operator's habits and the serialized
* result grows with it. That is the one thing this tool's
* preview-budget exemption claims cannot happen, and the claim has to
* be made true by the payload rather than by hope.
*
* Capped rather than budgeted because the budget is per TOOL, not per
* view: the shared `MCP_PREVIEW_BUDGET` is ~2000 characters and the
* hosts view already renders around 1700 with nothing installed, so a
* tool-wide budget would park an operator's connector diagnostic in an
* artifact on almost every call. The cap here bounds the view that
* needs bounding and leaves the other one alone.
*
* Matches `PAGE_LINT_MAX_FINDINGS` at twenty-five, and the list
* declares its own truncation the same way that report does, so a
* capped answer can never be read as a complete one.
*/
export const WIRING_MAX_PROJECTS = 25;
/** One registered project link, rendered under the path policy. */
function projectEntry(status: LinkedProjectStatus, ctx: ServerContext): Record<string, unknown> {
return {
project_ref: hostPathReference(status.path, ctx),
vault_ref: hostPathReference(status.vault, ctx),
pointer: status.pointer,
vault_exists: status.vaultExists,
};
}
/**
* Every project registered against THIS install's config.
*
* A server started without a config path falls back to the machine
* default, exactly as {@link viewHosts} does and exactly as the CLI verb
* this view mirrors (`o2b brain project status`) always has. It used to
* answer the empty list instead, which reported "nothing is linked" for
* a box whose registry was full - and disagreed with the sibling view in
* the same payload family about what an unnamed config means.
*
* The registry itself is read tolerantly (`listLinkedProjects` passes
* `tolerateParseError`), so a damaged `projects.json` reads as no links
* on this surface as it does on the CLI. That is core's contract, not
* this view's: a tool that refused where the verb tolerates would be the
* second answer this file exists to avoid.
*
* The list is capped at {@link WIRING_MAX_PROJECTS} and carries `total`,
* `returned` and `truncated` beside it, so what an unbounded registry
* costs this payload is bounded and a capped answer cannot be read as a
* complete one. The CLI verb is uncapped and stays so: it renders to a
* terminal, not into model context.
*/
function viewProjects(ctx: ServerContext): Record<string, unknown> {
const links = linkedProjectsStatus(ctx.configPath ?? defaultConfigPath());
const returned = links.slice(0, WIRING_MAX_PROJECTS);
return {
vault_path: vaultPathField(ctx),
view: PROJECTS_VIEW,
projects: returned.map((status) => projectEntry(status, ctx)),
total: links.length,
returned: returned.length,
truncated: links.length > returned.length,
};
}
/**
* One adapter's verify answer, as the payload carries it.
*
* `details` and `fix_hint` are the adapter's own sentences and name the
* files it looked at, so they are folded against the home this run
* verified rather than copied through; see {@link foldHostHome}.
*
* Exported for the test that drives a named probe SKIP through it. That
* branch is only reachable from an installed target verified against a
* specific host home, and `os.homedir()` in this runtime does not follow
* a later `process.env.HOME`, so an in-process test cannot redirect the
* home {@link viewHosts} resolves. It builds the `InstallEnv` by hand -
* exactly as the adapter suites do - and asserts this mapping over the
* real `verify()` answer instead of over a synthetic one.
*/
export function hostWiringEntry(
result: VerifyResult,
home: string,
policy: HostPathPolicySource,
): Record<string, unknown> {
return {
target: result.target,
status: result.status,
details: result.details.map((line) => foldHostHome(line, home, policy)),
fix_hint: result.fix_hint === null ? null : foldHostHome(result.fix_hint, home, policy),
};
}
/**
* Every registered install target, verified.
*
* The same `verify()` call per adapter that `o2b install --check`
* makes, over the same registry and the same `InstallEnv`. Reusing it
* means one implementation of connector health rather than a second one
* that can come to disagree with the first.
*
* The vault is refused rather than defaulted. `verify()` reads the
* per-vault sidecar manifest, so an unset vault makes every adapter
* report `not-installed` off a bogus path - ten runtimes reported
* absent when the real condition is that nothing was configured. The
* refusal carries the sentence `runCheck` gives, from the one constant
* both surfaces read.
*/
function viewHosts(ctx: ServerContext): Record<string, unknown> {
if (ctx.vault.trim() === "") throw new MCPError(INVALID_PARAMS, VAULT_NOT_CONFIGURED_REASON);
const env = buildInstallEnv({
vault: ctx.vault,
configPath: ctx.configPath ?? defaultConfigPath(),
});
return {
vault_path: vaultPathField(ctx),
view: HOSTS_VIEW,
hosts: defaultRegistry
.list()
.map((adapter) => hostWiringEntry(adapter.verify(env), env.home, ctx)),
};
}
const WIRING_VIEW_HANDLERS: Readonly<
Record<string, (ctx: ServerContext) => Record<string, unknown>>
> = Object.freeze({
[PROJECTS_VIEW]: viewProjects,
[HOSTS_VIEW]: viewHosts,
});
function toolWiring(ctx: ServerContext, args: Record<string, unknown>): unknown {
return dispatchByView(WIRING_VIEW_HANDLERS, ctx, args);
}
export const WIRING_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: WIRING_TOOL_NAME,
kind: "read",
// Under the 300-character registry cap: the path policy and the
// per-view field tables are long-form guidance, and `registry-guard.ts`
// states that those belong in docs/mcp.md rather than in a schema every
// client pays for on every request.
description:
"Report what this Open Second Brain install is wired into. view=projects lists each registered project link with its pointer state and whether its vault still exists; view=hosts verifies every install target as `o2b install --check` does, and may ask host CLIs under a bounded wait. Read-only.",
inputSchema: {
type: "object",
properties: {
view: {
type: "string",
enum: [...WIRING_VIEWS],
description:
"Which wiring to report. Required; there is no aggregate view, so a projects read never pays for a host probe.",
},
},
required: ["view"],
additionalProperties: false,
},
outputSchema: {
type: "object",
required: ["vault_path", "view"],
properties: {
vault_path: VAULT_PATH_OUTPUT_SCHEMA,
view: { type: "string", description: "The view this payload answers." },
total: {
type: "number",
description: "view=projects: registered project links found, the cap included.",
},
returned: {
type: "number",
description: "view=projects: entries actually carried in `projects`.",
},
truncated: {
type: "boolean",
description: "view=projects: true iff `total` exceeds `returned`.",
},
projects: {
type: "array",
description:
"view=projects: one entry per registered project link, capped; " +
"read `total`, `returned` and `truncated` beside it.",
items: {
type: "object",
required: ["project_ref", "vault_ref", "pointer", "vault_exists"],
properties: {
project_ref: VAULT_PATH_OUTPUT_SCHEMA,
vault_ref: VAULT_PATH_OUTPUT_SCHEMA,
pointer: {
type: "string",
description: "Pointer-file state: ok, missing, malformed, or mismatch.",
},
vault_exists: {
type: "boolean",
description: "Whether the vault directory the link names is still present.",
},
},
},
},
hosts: {
type: "array",
description: "view=hosts: one entry per registered install target.",
items: {
type: "object",
required: ["target", "status", "details", "fix_hint"],
properties: {
target: { type: "string", description: "The install target id." },
status: {
type: "string",
description: "Verify status: ok, drift, not-installed, or mcp-unreachable.",
},
details: {
type: "array",
description:
"What the adapter observed, one line per finding. Host paths in these " +
"sentences are folded to `~` unless `expose_host_paths` is set.",
items: { type: "string" },
},
// Nullable, and the descriptor language has no union form;
// see VAULT_PATH_OUTPUT_SCHEMA for why empty is the honest
// shape. Folded against the host home exactly as `details` is.
fix_hint: {},
},
},
},
},
},
handler: toolWiring,
},
]);