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
/**
* The event log: its shard structure and the artifact references its
* apply-evidence events carry.
*
* One reason to change: the log format. A malformed header is a defect
* in the file itself; a malformed or unresolvable artifact reference is
* a defect in what an event points at.
*/
import type { DegradationNotice } from "../../integrity/degradation.ts";
import { listVaultBasenames } from "../../vault.ts";
import { withoutPrivateEntries } from "../log-events-at-reach.ts";
import { listLogMarkdownFiles } from "../log-jsonl.ts";
import { parseLogDayFile, type BrainLogEntry } from "../log.ts";
import { brainDirs } from "../paths.ts";
import { BRAIN_LOG_EVENT_KIND } from "../types.ts";
import { parseArtifactRef } from "../wikilink.ts";
import type { DoctorCheck, DoctorCheckContext } from "./check.ts";
import type { DoctorUncertainEntry } from "./report.ts";
import { forwardSweepNotices, reportSweptFailure, SWEEP_ORIGIN } from "./unreadable-path.ts";
/** Subsystem name the shard discovery reports an unreadable path under. */
const LOG_SHARD_SITE = "brain.doctor.logShard";
/**
* 7. Log header parsing — surface warnings from every markdown shard.
*/
export const logShardCheck: DoctorCheck = {
failSoft: false,
run({ vault }, { issues, uncertain }) {
// Per-device shards (Memory Integrity Suite): lint every markdown
// log file - legacy `<date>.md` and sharded `<date>.<deviceId>.md` -
// so warnings keep their exact file paths and line numbers.
//
// The discovery itself is behind a shared helper: a `Brain/log` that
// is a regular file arrives as a throw, and this check does not fail
// soft, so it took the whole pass down with it. The read is now
// classified like every other; a parse failure below still throws,
// because a log the doctor mis-parses leaves the report wrong rather
// than incomplete.
for (const { date, path } of listShards(vault, uncertain)) {
const { warnings } = parseLogDayFile(vault, date, path);
for (const w of warnings) {
issues.push({
severity: "warning",
code: "log-malformed",
path: w.path,
message: `line ${w.lineNumber}: ${w.message}`,
});
}
}
},
};
/** The markdown log shards, or none plus the reason there are none to lint. */
function listShards(
vault: string,
uncertain: DoctorUncertainEntry[],
): ReadonlyArray<{ date: string; path: string }> {
try {
return listLogMarkdownFiles(vault);
} catch (err) {
reportSweptFailure(
brainDirs(vault).log,
"log shard discovery failed",
err,
{
site: LOG_SHARD_SITE,
consequence:
"no log shard under it was linted, so a malformed header in this vault's history is " +
"missing from this report",
uncertain,
},
SWEEP_ORIGIN.root,
);
return [];
}
}
/**
* The preference an `apply-evidence` event was logged against, as the
* finding's `sources`. The message names only the evidence artifact, so
* without it a reader filtering findings by what they name could not
* tell that the finding is about a preference the caller may not read.
*/
function evidencePreferenceSources(e: BrainLogEntry): { readonly sources?: ReadonlyArray<string> } {
const preference = e.body["preference"];
if (typeof preference !== "string") return {};
const target = parseArtifactRef(preference).target;
return target ? { sources: [target] } : {};
}
/**
* The `apply-evidence` events an evidence lint may quote: every one for
* the operator's own shell, and none of the store's `private` partition
* for a caller that withholds it. Both lints below put the event's
* timestamp and artifact name into their message, so a private event
* quoted to a remote caller would disclose private activity. Neither
* lint has a fixer, so leaving a private event out hides a finding from
* that caller only and changes no repair.
*/
function quotableEvidence(
logs: DoctorCheckContext["logs"],
withholdsPrivate: boolean | undefined,
): BrainLogEntry[] {
const out: BrainLogEntry[] = [];
for (const { entries } of logs) {
for (const e of withoutPrivateEntries(entries, withholdsPrivate === true)) {
if (e.eventType === BRAIN_LOG_EVENT_KIND.applyEvidence) out.push(e);
}
}
return out;
}
/**
* `malformed-evidence-range`: walks every `apply-evidence` event,
* runs the artifact wikilink through {@link parseArtifactRef}, and
* flags any malformed range suffix (`:abc-def`, `:120-100`, etc.).
* The event itself remains valid — only the range is malformed.
*/
export const evidenceRangeCheck: DoctorCheck = {
failSoft: true,
run({ logs, withholdsPrivate }, { issues }) {
for (const e of quotableEvidence(logs, withholdsPrivate)) {
const artifact = e.body["artifact"];
if (typeof artifact !== "string") continue;
const parsed = parseArtifactRef(artifact);
if (parsed.malformedRange) {
issues.push({
severity: "warning",
code: "malformed-evidence-range",
...evidencePreferenceSources(e),
message:
`apply-evidence at ${e.timestamp} references artifact ${parsed.raw}` +
` with malformed range '${parsed.rangeText}'.` +
" Use `[[file:N-N]]` (inclusive, 1-based) or `[[file:N]]`.",
});
}
}
},
};
/** Subsystem name the basename sweep reports an unreadable path under. */
const ORPHAN_EVIDENCE_SITE = "brain.doctor.orphanEvidence";
/**
* `orphan-evidence`: walks every `apply-evidence` event and verifies
* the artifact wikilink resolves to some file in the vault. Obsidian
* wikilinks resolve by basename; we use the cheap basename-only
* walker from `vault.ts` (no frontmatter parse).
*
* This is the only doctor lint that walks the entire vault (not just
* `Brain/`). It's an on-demand check; doctor isn't called per-turn.
*
* The walker is fail-soft over a directory it cannot list, so an
* unreadable subtree silently shrank the universe every reference here
* is resolved against - and a reference into that subtree then reads as
* orphaned. Those directories now arrive on the walker's notice sink and
* are reported as uncertainty; the findings below are unchanged.
*/
export const orphanEvidenceCheck: DoctorCheck = {
failSoft: true,
run({ vault, logs, withholdsPrivate }, { issues, uncertain }) {
const notices: DegradationNotice[] = [];
const basenames: ReadonlySet<string> = listVaultBasenames(vault, {
notices,
site: ORPHAN_EVIDENCE_SITE,
});
forwardSweepNotices(notices, {
site: ORPHAN_EVIDENCE_SITE,
consequence:
"its pages are absent from the basename universe this lint resolves artifact " +
"references against, so a reference that resolves under it reads as orphaned here",
uncertain,
});
for (const e of quotableEvidence(logs, withholdsPrivate)) {
const artifact = e.body["artifact"];
if (typeof artifact !== "string") continue;
const target = parseArtifactRef(artifact).target;
if (!target) continue;
if (basenames.has(target)) continue;
issues.push({
severity: "warning",
code: "orphan-evidence",
...evidencePreferenceSources(e),
message:
`apply-evidence at ${e.timestamp} references artifact [[${target}]]` +
" but no file with that basename exists in the vault.",
});
}
},
};