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
/**
* `o2b search "<query>"` — the default verb: flags to `SearchOptions`,
* one call into the core search (or the cross-vault union), and the
* rendered outcome.
*/
import {
indexVault,
parseStructuredRecallQueryDocument,
search,
structuredRecallQueryText,
SEARCH_LIMIT_MIN,
SEARCH_LIMIT_MAX,
} from "../../../core/search/index.ts";
import { searchAcrossVaults } from "../../../core/search/cross-vault.ts";
import type { SearchLaneTiming } from "../../../core/search/index.ts";
import { SEARCH_OPTION_ROWS } from "../../../core/search/search-options-descriptor.ts";
import {
parseDegreePredicate,
type DegreePredicate,
} from "../../../core/search/property-filter.ts";
import { jsonForOutcome, renderOutcomeHuman } from "../outcome-render.ts";
import {
CliError,
flagBoolean,
flagString,
isIntegerWithin,
parseFlags,
resolveConfig,
resolveConfigPath,
VAULT_FLAGS,
requireSearchVault,
} from "../helpers.ts";
import { CLI_TRANSPORT_REACH } from "../../transport-reach.ts";
import { FTS_MATCH_MODES, isFtsMatchMode } from "../../../core/search/fts-match-mode.ts";
import { SEARCH_KINDS, isSearchKind } from "../../../core/search/property-pushdown.ts";
import { SEARCH_SOURCES, isSearchSource } from "../../../core/search/brain-store/constants.ts";
import {
DISCLOSURE_MODE,
DISCLOSURE_MODES,
isDisclosureMode,
} from "../../../core/search/disclosure-mode.ts";
/** Both malformed `--property` shapes report the same way. */
function propertyFormatError(entry: string): CliError {
return new CliError(`--property must be KEY=VALUE, got: ${entry}`);
}
/** The flags that belong to this verb's output and refresh behavior, not to the search language. */
const VERB_LOCAL_FLAGS: Readonly<Record<string, QueryFlagSpec>> = Object.freeze({
"auto-refresh": { type: "boolean" },
json: { type: "boolean" },
verbose: { type: "boolean" },
});
/** The parser spec one flag carries - the verb's local spell of `FlagSpec`. */
interface QueryFlagSpec {
readonly type: "string" | "boolean" | "string-array";
readonly default?: string;
}
/**
* The query verb's flag table, DERIVED from the search-options descriptor
* (t_50c81d5c): one entry per cli-visible row, keyed by the row's declared
* CLI spelling (`path_prefix` spells `--path`, `query_document` spells
* `--query-doc`, `properties` the repeatable `--property`,
* `record_access` its `cliNegates` inverse `--no-record-access`), with the
* row's CLI parse kind. The served schema and this table are now two
* projections of one table, so a flag cannot appear on one surface and
* silently vanish from the other.
*
* Per-surface bounds stay where they are: the CLI limit keeps its
* `SEARCH_LIMIT_MIN..SEARCH_LIMIT_MAX` bind at the read site (the MCP
* schema's `MCP_LIMIT_MAX` is a different, deliberate edge), the query
* stays uncapped here, and `semantic` stays the documented tri-state
* asymmetry (the verb body passes `undefined` when no lane flag is given).
* A row whose documented default is a bare integer carries it as the
* parser default (`limit` -> "10"); prose defaults mean absent.
*/
export const SEARCH_QUERY_FLAGS: Readonly<Record<string, QueryFlagSpec>> = Object.freeze(
(() => {
const derived: Record<string, QueryFlagSpec> = {};
for (const row of SEARCH_OPTION_ROWS) {
if (!row.surfaces.includes("cli") || row.cliFlag === null) continue;
// A pure-integer documented default is a parse default; prose ("absent:
// ...", "false", "all") stays absent, exactly as the literal table did.
derived[row.cliFlag] = /^\d+$/.test(row.default)
? { type: row.cliKind, default: row.default }
: { type: row.cliKind };
}
return { ...VAULT_FLAGS, ...derived, ...VERB_LOCAL_FLAGS };
})(),
);
export async function cmdSearchQuery(argv: ReadonlyArray<string>): Promise<number> {
const { flags, positional } = parseFlags(argv, SEARCH_QUERY_FLAGS);
const rawQueryDocument = flagString(flags, "query-doc");
const structuredQuery =
rawQueryDocument !== undefined
? parseStructuredRecallQueryDocument(rawQueryDocument)
: undefined;
if (positional.length === 0 && structuredQuery === undefined) {
throw new CliError("query string is required");
}
if (flagBoolean(flags, "semantic") && flagBoolean(flags, "keyword-only")) {
throw new CliError("--semantic and --keyword-only are mutually exclusive");
}
const query =
positional.length > 0 ? positional.join(" ") : structuredRecallQueryText(structuredQuery!);
if (query.trim().length === 0) {
throw new CliError("query string is required when --query-doc has no searchable lanes");
}
const limitNum = Number(flags["limit"] ?? "10");
if (!isIntegerWithin(limitNum, { min: SEARCH_LIMIT_MIN, max: SEARCH_LIMIT_MAX })) {
throw new CliError(`--limit must be an integer in ${SEARCH_LIMIT_MIN}..${SEARCH_LIMIT_MAX}`);
}
const disclosureRaw = flagString(flags, "disclosure");
if (disclosureRaw !== undefined && !isDisclosureMode(disclosureRaw)) {
throw new CliError(`--disclosure must be one of ${DISCLOSURE_MODES.join(", ")}`);
}
const matchModeRaw = flagString(flags, "match-mode");
if (matchModeRaw !== undefined && !isFtsMatchMode(matchModeRaw)) {
throw new CliError(`--match-mode must be one of ${FTS_MATCH_MODES.join(", ")}`);
}
const matchMode = matchModeRaw;
const kindRaw = flagString(flags, "kind");
if (kindRaw !== undefined && !isSearchKind(kindRaw)) {
throw new CliError(`--kind must be one of ${SEARCH_KINDS.join(", ")}`);
}
const kind = kindRaw;
const sourceRaw = flagString(flags, "source");
if (sourceRaw !== undefined && !isSearchSource(sourceRaw)) {
throw new CliError(`--source must be one of ${SEARCH_SOURCES.join(", ")}`);
}
const source = sourceRaw;
const cfg = resolveConfig(flags);
// `--global` needs the vault: refused before the refresh or any search.
const globalVault = flagBoolean(flags, "global")
? requireSearchVault(cfg, "search query --global")
: null;
if (flagBoolean(flags, "auto-refresh")) {
try {
await indexVault(cfg);
} catch (e) {
const msg = e instanceof Error ? e.message : String(e);
process.stderr.write(`auto-refresh failed: ${msg}\n`);
}
}
// Pass `undefined` when no explicit flag is set so `search()` falls back
// to the config default. Passing `null` works by accident today but blurs
// the implicit/explicit policy boundary in §7 of the search design.
const semanticOverride: boolean | undefined = flagBoolean(flags, "semantic")
? true
: flagBoolean(flags, "keyword-only")
? false
: undefined;
const properties = parsePropertyFlags(flags["property"] as string[] | undefined);
const degreeFilters = parseDegreeFlags(flags["degree"] as string[] | undefined);
const visibility = flags["visibility"] as string[] | undefined;
const agentScope = flagString(flags, "agent-scope");
const profile = flagString(flags, "profile");
const since = flagString(flags, "since");
const until = flagString(flags, "until");
const isGlobal = flagBoolean(flags, "global");
// Overlapped-lane timing (recall-lane-latency): captured only when
// --explain asks and only on the single-vault path - a cross-vault
// union merges one search per origin and no honest single figure
// exists for it. Omitted, the pipeline records nothing and every
// projection stays byte-identical.
const captureTiming = flagBoolean(flags, "explain") && !isGlobal;
let laneTiming: SearchLaneTiming | undefined;
const searchOpts = {
query,
limit: limitNum,
semantic: semanticOverride,
keywordOnly: flagBoolean(flags, "keyword-only"),
pathPrefix: flagString(flags, "path"),
...(kind !== undefined ? { kind } : {}),
...(source !== undefined ? { source } : {}),
...(matchMode !== undefined ? { matchMode } : {}),
...(properties !== undefined ? { properties } : {}),
...(degreeFilters !== undefined ? { degreeFilters } : {}),
...(visibility !== undefined && visibility.length > 0 ? { visibility } : {}),
// The operator's own shell against the operator's own vault; carried
// into the cross-vault union below on the same options object, so a
// federated CLI query is bound by the same rule.
transportReach: CLI_TRANSPORT_REACH,
// Owner-scope isolation (context-integrity-gates, Unit A): an
// owner-private page is returned only to its own scope. Omitting the
// flag applies no ownership filtering at all.
...(agentScope !== undefined ? { agentScope } : {}),
...(structuredQuery !== undefined ? { structuredQuery } : {}),
...(flagBoolean(flags, "expand") ? { expand: true } : {}),
...(disclosureRaw === DISCLOSURE_MODE.cards ? { disclosure: disclosureRaw } : {}),
...(profile !== undefined ? { profile } : {}),
...(flagBoolean(flags, "evidence-pack") ? { evidencePack: true } : {}),
...(flagBoolean(flags, "include-superseded") ? { includeSuperseded: true } : {}),
...(since !== undefined ? { since } : {}),
...(until !== undefined ? { until } : {}),
// Access recording (Time-Aware Recall & Activation Suite): the CLI
// surface opts in by default; --no-record-access suppresses it, and
// cross-vault union never records (results span foreign vaults).
...(!isGlobal && !flagBoolean(flags, "no-record-access") ? { recordAccess: true } : {}),
...(captureTiming
? { laneTiming: (timing: SearchLaneTiming) => void (laneTiming = timing) }
: {}),
};
// Cross-vault union (t_72a22658): explicit per-call opt-in fans the
// query out over profiles and read-only sources with origin labels.
const outcome =
globalVault !== null
? await searchAcrossVaults(resolveConfigPath(flags), globalVault, searchOpts, cfg)
: await search(cfg, searchOpts);
// Retrieval receipts (what-the-index-already-knew, task F): --explain
// appends the decision trace and the trust assessment the search
// already built. Omitted, both projections are byte-identical to the
// pre-flag ones.
const explainOptions = {
explain: flagBoolean(flags, "explain"),
crossVault: isGlobal,
// Engaged means the resolved mode is not off - the legacy boolean
// alone cannot answer that (an explicit search_trust_gate_mode runs
// the gate with the boolean left false).
trustGateEnabled: cfg.recall.searchTrustGateMode !== undefined,
};
if (flagBoolean(flags, "json")) {
process.stdout.write(
JSON.stringify(jsonForOutcome(outcome, explainOptions, laneTiming)) + "\n",
);
return 0;
}
process.stdout.write(
renderOutcomeHuman(outcome, flagBoolean(flags, "verbose"), query, explainOptions, laneTiming),
);
return 0;
}
/**
* Parse the repeatable `--property KEY=VALUE` flag into the
* `properties` map shape that `search()` consumes. Multiple
* `--property KEY=...` entries for the same KEY accumulate (OR).
* Different KEYs accumulate as separate entries (AND).
*/
function parsePropertyFlags(
raw: ReadonlyArray<string> | undefined,
): ReadonlyMap<string, ReadonlyArray<string>> | undefined {
if (!raw || raw.length === 0) return undefined;
const acc = new Map<string, string[]>();
for (const entry of raw) {
const eq = entry.indexOf("=");
if (eq <= 0) {
throw propertyFormatError(entry);
}
const key = entry.slice(0, eq).trim();
const value = entry.slice(eq + 1).trim();
if (key.length === 0 || value.length === 0) {
throw propertyFormatError(entry);
}
const arr = acc.get(key) ?? [];
arr.push(value);
acc.set(key, arr);
}
const frozen = new Map<string, ReadonlyArray<string>>();
for (const [k, v] of acc) frozen.set(k, Object.freeze(v));
return frozen;
}
/**
* Parse the repeatable `--degree <field><op><count>` flag into the
* `degreeFilters` predicate list that `search()` consumes, e.g.
* `--degree backlinks=0` (orphans) or `--degree outlinks>=5` (hubs).
* Invalid syntax throws a typed `SearchError` from
* {@link parseDegreePredicate}, surfaced by the search verb's error
* handler as exit 2.
*/
function parseDegreeFlags(raw: ReadonlyArray<string> | undefined): DegreePredicate[] | undefined {
if (!raw || raw.length === 0) return undefined;
return raw.map((entry) => parseDegreePredicate(entry));
}