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
/**
* Repo-scoped ADR candidate reader for the architecture notes
* (salience-lifecycle-enrichment, unit 6 / t_041c571f).
*
* `Brain/decisions/candidates/` is a VAULT-GLOBAL store: the commit miner
* (`git/decisions.ts`) writes one candidate per decision-shaped commit of
* every repository the vault has ingested, and stamps each one with the
* `repo_key` it came from. The architect derives the same key from the
* project it is scanning, so the join is exact - and it is the only thing
* that keeps one repository's key-decisions note from listing another
* repository's drafts.
*
* Read-only and deterministic: candidates are ordered by filename in
* codepoint order, never by directory order (which no filesystem
* promises) and never by a locale collator. A candidate whose frontmatter
* is missing a field is REPORTED with that field named as unrecorded, not
* skipped - a hand-edited draft that lost its sha is exactly the note an
* operator needs to see in the list.
*/
import { join } from "node:path";
import { compareStable } from "./scan.ts";
import { lanePageExists, listLaneFiles, parseLanePage } from "../../store/lane-pages.ts";
/** Where the commit miner puts its drafts, relative to the vault root. */
export const DECISION_CANDIDATES_DIR = ["Brain", "decisions", "candidates"] as const;
/** One ADR candidate, as the key-decisions note needs it. */
export interface DecisionCandidateFact {
/** Absolute path of the candidate note. */
readonly path: string;
/** Vault-relative, extension-less path - the wikilink target. */
readonly link: string;
/** The candidate's own heading, or its filename when it has none. */
readonly title: string;
/** The commit sha the candidate is identified by, when it records one. */
readonly sha: string | null;
/** Deterministic signal ids that made the commit decision-shaped. */
readonly signals: ReadonlyArray<string>;
}
/** The first ATX heading of a candidate body, without its marker. */
function headingOf(body: string): string | null {
for (const line of body.split("\n")) {
if (line.startsWith("# ")) return line.slice(2).trim();
}
return null;
}
/** A frontmatter value read as a non-empty string, or null. */
function stringField(value: unknown): string | null {
return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
}
/** A frontmatter value read as a string list. */
function listField(value: unknown): ReadonlyArray<string> {
if (Array.isArray(value)) return value.filter((item): item is string => typeof item === "string");
const single = stringField(value);
return single === null ? [] : [single];
}
/**
* Every ADR candidate in the vault whose `repo_key` is `repoKey`, in a
* stable order. A vault with no candidate directory yields an empty list;
* that is an ordinary state, not a failure.
*/
export function listRepoDecisionCandidates(
vault: string,
repoKey: string,
): ReadonlyArray<DecisionCandidateFact> {
const dir = join(vault, ...DECISION_CANDIDATES_DIR);
if (!lanePageExists(vault, dir)) return Object.freeze([]);
const facts: DecisionCandidateFact[] = [];
for (const name of listLaneFiles(vault, dir).toSorted(compareStable)) {
const path = join(dir, name);
const [metadata, body] = parseLanePage(vault, path);
if (stringField(metadata["repo_key"]) !== repoKey) continue;
const stem = name.slice(0, -".md".length);
facts.push(
Object.freeze({
path,
link: `${DECISION_CANDIDATES_DIR.join("/")}/${stem}`,
title: headingOf(body) ?? stem,
sha: stringField(metadata["sha"]),
signals: Object.freeze(listField(metadata["signals"])),
}),
);
}
return Object.freeze(facts);
}