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
/**
* Read-only query helpers over Brain state (design doc §9.2).
*
* Three callable shapes, all returning frozen result objects so the
* surfaces consuming them (CLI `o2b brain query`, MCP `brain_query`,
* future agent introspection) cannot accidentally mutate vault state:
*
* - {@link queryByPreference} — one preference (active or retired)
* plus every `apply-evidence` log entry that references it.
*
* - {@link queryByRuleTopic} — every signal under a topic (active +
* processed), the current preference for that topic (active or
* retired), and every log entry mentioning the preference.
*
* - {@link queryByLogSince} — every log entry across all days whose
* `timestamp >= since`. Cron / digest / debugging entry point.
*
* All three are pure reads. They do not touch the inbox `processed/`
* holding area, the snapshots/, or the `_brain.yaml` config — those are
* dream's job.
*
* Wikilink resolution rule: a preference is "referenced" by a log entry
* when the entry's `preference` payload contains either the bare id or
* the `[[id]]` wikilink form. We strip both forms so a hand-typed entry
* (`preference: pref-foo`) and a properly-rendered entry
* (`preference: [[pref-foo]]`) both match.
*/
import { filterExpired, isExpired } from "./expiration.ts";
import type { BrainLogEntry } from "./log.ts";
import { memoryFolderPages, memoryPageNamed, type MemoryFolder } from "./memory-pages.ts";
import { logDayReader } from "./log-days.ts";
import { parsePreferenceMeta, parseRetiredMeta } from "./preference.ts";
import { ownerScopeView } from "./owner-scope-view.ts";
import { everyArtifactRefView, type ArtifactRefView } from "./artifact-ref-view.ts";
import { reachView } from "./reach-view.ts";
import { resolvedTransportReach, type TransportReach } from "../graph/transport-reach.ts";
import { parseSignalPage } from "./signal.ts";
import {
SUPERSEDED_BY_KEY,
buildChainLookup,
isTombstoned,
resolveChainTip,
type ChainLookup,
} from "./lifecycle/tombstone-read.ts";
import { chainVerdict } from "../search/correction-coupling.ts";
import { vaultRelative } from "../path-safety.ts";
import { normaliseWikilinkTarget } from "./wikilink.ts";
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";
import type { BrainPreference, BrainRetired, BrainSignal } from "./types.ts";
// ----- Errors ---------------------------------------------------------------
/**
* Raised when {@link queryByPreference} is asked for a `pref-` id (or
* `ret-` id) that resolves to no file in either `preferences/` or
* `retired/`. The CLI translates this to exit code `2` per design doc
* §9.2 "not an error condition".
*/
export class BrainNotFoundError extends Error {
readonly id: string;
constructor(id: string) {
super(`brain query: no preference or retired entry found for id '${id}'`);
this.name = "BrainNotFoundError";
this.id = id;
}
}
// ----- Result shapes --------------------------------------------------------
export interface QueryByPreferenceResult {
/** The active preference (`preferences/`) or retired one (`retired/`). */
readonly preference: BrainPreference | BrainRetired;
/**
* Every `apply-evidence` log entry referencing this preference,
* sorted ascending by `timestamp`. Empty when the preference exists
* but has never been applied (common for freshly-promoted
* unconfirmed entries).
*/
readonly evidence: ReadonlyArray<BrainLogEntry>;
}
export interface QueryByTopicResult {
/**
* All signals for the topic — active (`inbox/sig-*.md`) and processed
* (`inbox/processed/sig-*.md`). Sorted by `created_at` ascending so
* the caller sees a chronological trail.
*/
readonly signals: ReadonlyArray<BrainSignal>;
/**
* The current state of the topic's rule:
* - active preference if one exists in `preferences/`
* - retired preference if one exists in `retired/`
* - null if the topic has signals but never reached promotion
*
* A topic can plausibly have *both* an active and a retired entry
* (the active rule supersedes a prior retired one). In that case we
* return the active version — it is the current truth — and the
* caller can find the historical retired one via `queryByPreference`
* by id.
*/
readonly preference: BrainPreference | BrainRetired | null;
/**
* Every log entry mentioning the topic's preference id. Sorted by
* `timestamp` ascending. Includes `apply-evidence`, `promote`,
* `retire`, `pin` / `unpin`, etc. — anything whose `preference`
* payload field resolves to the same id.
*/
readonly all_log_events: ReadonlyArray<BrainLogEntry>;
}
/**
* Read-path options for the list surfaces (C5 / t_a82b674e). Default
* behaviour drops any signal / preference past its `expiration_date`;
* `showExpired` re-includes them for audit / recall of lapsed memories.
*/
export interface QueryByTopicOptions {
/** When true, expired memories are kept in the result. Default false. */
readonly showExpired?: boolean;
/** Wall clock the expiration is compared against. Defaults to `new Date()`. */
readonly now?: Date;
/**
* Owner scope the topic's CURRENT RULE is selected under
* (a-label-is-not-a-boundary, U3). Absent / `null` selects as before.
*
* It has to reach the selection rather than filter the result,
* because a topic resolves to exactly one preference - the first
* match by filename - and several preferences may carry the topic.
* Filtering afterwards would drop the row and report the topic as
* having no rule at all, so one owner's private preference sorting
* ahead of the shared one would HIDE the shared one from everybody
* else. Skipping the invisible candidates during the walk returns the
* rule this caller actually has.
*/
readonly ownerScope?: string | null;
/**
* Transport reach the topic's CURRENT RULE is selected under
* (private-is-not-a-suggestion, unit 5). Absent resolves to the
* narrowest.
*
* It reaches the SELECTION for the same reason the owner scope above
* does: a topic resolves to exactly one preference, so filtering the
* result afterwards would report the topic as having no rule at all
* whenever a reserved preference happened to sort ahead of a readable
* one - hiding the readable rule from every caller.
*/
readonly transportReach?: TransportReach;
}
// ----- Public API -----------------------------------------------------------
/**
* Look up one preference (active or retired) and its evidence trail.
*
* Resolution rules:
* - A `pref-...` id is searched in `preferences/`. If absent, we also
* accept a fallback to `retired/ret-<slug>` (same slug stem) so an
* agent that asked for the active id of a now-retired preference
* still gets a useful answer.
* - A `ret-...` id is searched in `retired/` only.
* - Any other prefix raises {@link BrainNotFoundError} immediately.
*/
export function queryByPreference(vault: string, pref_id: string): QueryByPreferenceResult {
const id = pref_id.trim();
if (!id) {
throw new BrainNotFoundError(pref_id);
}
// Slug shape is the same alphabet validateSlug() enforces; rejecting
// here before forming any filesystem path closes a path-traversal
// vector (`pref-../../etc/passwd`) — even though `validateSlug` would
// catch it later, we never want `join(dirs.preferences, ...)` to
// resolve outside the intended directory under any operator error.
const SLUG_RE = /^[A-Za-z0-9._-]+$/;
let preference: BrainPreference | BrainRetired | null = null;
if (id.startsWith("pref-")) {
const slug = id.slice("pref-".length);
if (!SLUG_RE.test(slug)) {
throw new BrainNotFoundError(pref_id);
}
const active = memoryPageNamed(vault, "preferences", `${id}.md`);
if (active !== null) {
preference = parsePreferenceMeta(active.read()[0], active.path);
} else {
// Fallback to the retired version with the same slug stem.
const retired = memoryPageNamed(vault, "retired", `ret-${slug}.md`);
if (retired !== null) {
preference = parseRetiredMeta(retired.read()[0], retired.path);
}
}
} else if (id.startsWith("ret-")) {
const slug = id.slice("ret-".length);
if (!SLUG_RE.test(slug)) {
throw new BrainNotFoundError(pref_id);
}
const retired = memoryPageNamed(vault, "retired", `${id}.md`);
if (retired !== null) {
preference = parseRetiredMeta(retired.read()[0], retired.path);
}
} else {
throw new BrainNotFoundError(pref_id);
}
if (!preference) {
throw new BrainNotFoundError(pref_id);
}
// The evidence trail is keyed off the active id (`pref-<slug>`) — the
// log records `preference: [[pref-<slug>]]` even after retirement.
const slug = preference.id.startsWith("pref-")
? preference.id.slice("pref-".length)
: preference.id.slice("ret-".length);
const matchIds = new Set<string>([`pref-${slug}`, `ret-${slug}`]);
const all = readAllLogEntries(vault);
const evidence = all
.filter(
(e) =>
e.eventType === BRAIN_LOG_EVENT_KIND.applyEvidence &&
matchPreferencePayload(e.body["preference"], matchIds),
)
.toSorted(byTimestampAsc);
return Object.freeze({
preference,
evidence: Object.freeze(evidence),
});
}
/**
* Aggregate every artifact under a topic. Includes signals across both
* `inbox/` and `inbox/processed/`, the current rule (active or
* retired), and every log entry mentioning the preference id (active
* or retired form). Unknown topic → empty result with `preference: null`.
*/
export function queryByRuleTopic(
vault: string,
topic: string,
options: QueryByTopicOptions = {},
): QueryByTopicResult {
const want = topic.trim();
if (!want) {
return Object.freeze({
signals: Object.freeze([]),
preference: null,
all_log_events: Object.freeze([]),
});
}
const now = options.now ?? new Date();
const showExpired = options.showExpired ?? false;
let signals: BrainSignal[] = [];
// Collect signals from inbox/, inbox/processed/ and inbox/archived/.
// We do not recurse — those two are the only allowed sub-folders of
// `inbox/` and `readdirSync` with `withFileTypes` lets us pick file
// vs directory entries deterministically.
collectSignals(vault, "inbox", want, signals);
collectSignals(vault, "processed", want, signals);
collectSignals(vault, "archived", want, signals);
signals.sort((a, b) => a.created_at.localeCompare(b.created_at));
// Expiration filter (C5): drop signals past their expiration_date
// unless the caller opts into showExpired. The files stay on disk —
// this is a read-path filter, orthogonal to dream retirement.
signals = filterExpired(signals, { now, showExpired });
// Current rule — prefer the active preference; fall back to retired.
// Both selection rules, ANDed. They are independent questions and
// neither is folded into the other; a candidate survives the walk only
// when both keep it.
const view = everyArtifactRefView(
ownerScopeView(vault, options.ownerScope ?? null),
reachView(vault, resolvedTransportReach(options.transportReach)),
);
let preference: BrainPreference | BrainRetired | null = null;
preference = findPreferenceForTopic(vault, "preferences", want, "preference", view);
if (!preference) {
preference = findPreferenceForTopic(vault, "retired", want, "retired", view);
}
// Expiration filter (C5): an active preference past its expiration_date
// is dropped from the default result (surfaced only under showExpired).
// A retired preference carries no live expiration and is never filtered
// here — it is already out of the loop.
if (
!showExpired &&
preference !== null &&
preference.kind === "brain-preference" &&
preference.expiration_date !== undefined &&
isExpired(preference.expiration_date, now)
) {
preference = null;
}
// All log events whose `preference` payload resolves to the topic's
// pref id (both `pref-` and `ret-` forms, since the slug stem is
// shared after retirement).
let all_log_events: ReadonlyArray<BrainLogEntry> = Object.freeze([]);
if (preference) {
const slug = preference.id.startsWith("pref-")
? preference.id.slice("pref-".length)
: preference.id.slice("ret-".length);
const matchIds = new Set<string>([`pref-${slug}`, `ret-${slug}`]);
const all = readAllLogEntries(vault);
all_log_events = Object.freeze(
all
.filter((e) => matchPreferencePayload(e.body["preference"], matchIds))
.toSorted(byTimestampAsc),
);
}
return Object.freeze({
signals: Object.freeze(signals),
preference,
all_log_events,
});
}
/**
* Return every log entry across `Brain/log/*.md` whose `timestamp` is
* `>= since` (inclusive lower bound — same semantics as the digest's
* window). Entries are returned in chronological order. Malformed log
* entries are silently skipped (their warnings are the doctor's
* concern, not this surface's).
*/
export function queryByLogSince(vault: string, since: Date): ReadonlyArray<BrainLogEntry> {
if (!(since instanceof Date) || Number.isNaN(since.getTime())) {
throw new TypeError("queryByLogSince: `since` must be a valid Date");
}
const sinceIso = since.toISOString();
const entries = readAllLogEntries(vault).filter((e) => e.timestamp >= sinceIso);
entries.sort(byTimestampAsc);
return Object.freeze(entries);
}
// ----- Internals ------------------------------------------------------------
/**
* Read every log file under `Brain/log/`, parse it via {@link parseLogDay},
* and concatenate the entries in chronological order (each file is
* already in-order; we glue them by date prefix). Missing log directory
* → empty array.
*/
export function readAllLogEntries(vault: string): BrainLogEntry[] {
// Shard-aware (Memory Integrity Suite): dates from the single
// discovery helper, entries merged across device shards.
const out: BrainLogEntry[] = [];
const log = logDayReader(vault);
for (const date of log.dates) {
const { entries } = log.day(date);
for (const e of entries) out.push(e);
}
return out;
}
function collectSignals(
vault: string,
folder: MemoryFolder,
topic: string,
out: BrainSignal[],
): void {
for (const entry of memoryFolderPages(vault, folder, { regularFilesOnly: true })) {
if (!entry.name.startsWith("sig-") || !entry.name.endsWith(".md")) {
continue;
}
const path = entry.path;
// Belief lifecycle suite (t_7d5a3589): a tombstoned signal is
// excluded from recall.
const [meta, body] = entry.read();
if (isTombstoned(meta)) continue;
let sig: BrainSignal;
try {
sig = parseSignalPage(meta, body, path);
} catch {
// Unit F, deliberately NOT converted: this catch does not swallow a
// frontmatter read. `parseSignal` is the typed validator and its
// throw is a real, reachable signal (missing required field, bad
// status/folder pairing) that `o2b brain doctor` already reports as
// an ERROR against this exact path. Emitting a degradation notice
// here would duplicate an existing finding at a lower severity.
// The line-level drops underneath it are reported by the doctor's
// Brain sweep - see src/core/vault.ts.
continue;
}
if (sig.topic === topic) out.push(sig);
}
}
/**
* Matches on RAW topic bytes, deliberately and not yet reconciled with the
* consolidation path: the dream pass resolves a topic through the folded
* `topicKey`, so a caller asking for `Api-Key` finds nothing here while the
* pass would treat it as the rule on `api-key`. Folding this lookup changes
* which record a read returns - a recall-path behaviour change with its own
* blast radius - so it is named rather than smuggled into a fix. The
* condition is findable meanwhile: `o2b brain doctor` reports
* `topic-key-collision` for preferences whose topics fold together.
*/
function findPreferenceForTopic(
vault: string,
folder: MemoryFolder,
topic: string,
kind: "preference" | "retired",
view: ArtifactRefView,
): BrainPreference | BrainRetired | null {
const prefix = kind === "preference" ? "pref-" : "ret-";
// Sort by filename so the "first match" is deterministic across runs
// and filesystems. `readdirSync` order is platform-dependent (it is
// explicitly unspecified by POSIX and by Node) — without an explicit
// sort, two preferences with the same topic could be returned in
// different orders on different machines.
const entries = memoryFolderPages(vault, folder, { regularFilesOnly: true }).toSorted((a, b) =>
a.name.localeCompare(b.name),
);
// The serve-with-correction chain index, built on the first
// pointer-bearing record and reused for the rest of the walk: a vault
// whose records carry no pointer never pays for it.
let chainLookup: ChainLookup | null = null;
for (const entry of entries) {
if (!entry.name.startsWith(prefix) || !entry.name.endsWith(".md")) {
continue;
}
const path = entry.path;
// Belief lifecycle suite (t_7d5a3589): a tombstoned entry is excluded
// from recall while remaining on disk for audit.
const [meta] = entry.read();
if (isTombstoned(meta)) continue;
try {
const parsed =
kind === "preference" ? parsePreferenceMeta(meta, path) : parseRetiredMeta(meta, path);
// Skipped, not returned-then-dropped: see `ownerScope` on
// {@link QueryByTopicOptions}.
if (parsed.topic === topic && view.visible(parsed.id)) {
// Serve-with-correction coupling (truth-correctable-time-aware,
// contract item 3): a record whose frontmatter declares a
// successor but which survived the tombstone filter - the
// serveable-retired regime the correct verb's validity-close
// writes - is recallable by topic only beside its resolved,
// readable chain-tip correction, and is skipped fail-closed
// otherwise. A record with no pointer is not in the predicate's
// regime and keeps today's behavior.
const pointer = meta[SUPERSEDED_BY_KEY];
if (typeof pointer === "string" && pointer.trim() !== "") {
chainLookup ??= buildChainLookup(vault, (rel) => view.visible(rel));
const verdict = chainVerdict(
vaultRelative(path, vault),
resolveChainTip(pointer, chainLookup),
);
if (verdict.action === "drop") continue;
}
return parsed;
}
} catch {
// Unit F, deliberately NOT converted - same reasoning as
// collectSignals above: `parsePreference` / `parseRetired` throw on
// typed validation, which the doctor already reports as an error
// against this path. Not a swallowed frontmatter read.
continue;
}
}
return null;
}
/**
* The `preference` payload field of an `apply-evidence` (or `promote`,
* `retire`, …) log entry is typically a wikilink (`[[pref-foo]]`) but
* we tolerate the bare id form and even a sub-path/alias suffix. Strip
* brackets, drop everything after `|` or `#`, then compare against the
* caller's set of allowed ids.
*/
function matchPreferencePayload(
payload: string | ReadonlyArray<string> | undefined,
matchIds: ReadonlySet<string>,
): boolean {
if (payload === undefined) return false;
const values = Array.isArray(payload) ? payload : [payload as string];
for (const v of values) {
const id = normaliseWikilinkTarget(v);
if (id && matchIds.has(id)) return true;
}
return false;
}
function byTimestampAsc(a: BrainLogEntry, b: BrainLogEntry): number {
return a.timestamp.localeCompare(b.timestamp);
}