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
/**
* Open-loops live scan (today-operator-surface, Task 2).
*
* An open loop is an `@osb loop <free text>` marker jotted into note
* prose. It stays in the prose forever and is never consumed; it counts
* as open until a structural close token `@osb loop close id=<id>`
* referencing its id appears anywhere in the scanned note space. There
* is no store - the open set is re-derived on every call, so a hand
* edit that deletes the marker silently closes the loop (accepted, per
* design.md).
*
* This module is strictly read-only: it walks the configured note paths
* via {@link walkMarkdownFiles}, discovers markers with
* {@link discoverMarkers} (fence-aware, consumed-sentinel-skipping), and
* computes the open set. It never writes a signal, rewrites a file, or
* annotates a marker. Feedback and `set` markers in the same files are
* ignored - only `kind === "loop"` markers are read here.
*
* Determinism: files are scanned in sorted vault-relative-path order and
* markers within a file in document order, so "first occurrence in walk
* order" (used to collapse duplicate ids) is stable across runs. No wall
* clock is read; the returned envelope is deeply frozen.
*
* Loop id: an explicit `id=` on the marker wins; otherwise the id is the
* first 8 hex chars of the SHA-256 of the normalized loop text
* (trim + collapse whitespace runs to single spaces, byte-exact
* otherwise - no case folding, so it is language-agnostic). Editing the
* text therefore changes the id and reopens the loop, which is the
* honest reading of "the intention changed".
*/
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { discoverMarkers, type ParsedMarker } from "./inline.ts";
import {
buildNoteWalkRules,
resolveNoteRoots,
walkMarkdownFiles,
type NoteWalkFile,
} from "./notes/note-walk.ts";
/** Same 1 MiB per-file cap `scanInline` applies. */
const MAX_FILE_SIZE_BYTES = 1_048_576;
/** One open loop in the derived open set. */
export interface OpenLoop {
/** Explicit `id=` value, or the derived short hash of the loop text. */
readonly id: string;
/** The loop's free text (whitespace-collapsed by the parser). */
readonly text: string;
/** Vault-relative POSIX path of the note the marker sits in. */
readonly path: string;
/** 1-based line where the marker starts. */
readonly line: number;
}
/**
* A second-or-later open marker sharing an id already claimed by an
* earlier marker in walk order. The earlier marker is the canonical
* open loop; these extras are reported so the operator can see the
* collision rather than have it silently dropped.
*/
export interface DuplicateOpenLoop {
readonly id: string;
readonly text: string;
readonly path: string;
readonly line: number;
}
/**
* A `@osb loop close id=<id>` token whose id matches no open marker
* anywhere in the scanned space. Not an error - the open marker may have
* been hand-deleted (design.md accepts prose edits as loop closure) - so
* it is surfaced for visibility instead of failing the scan.
*/
export interface OrphanClose {
readonly id: string;
readonly path: string;
readonly line: number;
}
export interface OpenLoopCounts {
/** Distinct open loops still open (equals `openLoops.length`). */
readonly openCount: number;
/** Distinct open-loop ids that have a matching close token. */
readonly closedCount: number;
/** Number of note files actually read during the scan. */
readonly scannedFiles: number;
}
/** Frozen result envelope of {@link scanOpenLoops}. */
export interface OpenLoopScan {
readonly openLoops: ReadonlyArray<OpenLoop>;
readonly counts: OpenLoopCounts;
readonly duplicates: ReadonlyArray<DuplicateOpenLoop>;
readonly orphanCloses: ReadonlyArray<OrphanClose>;
}
export interface ScanOpenLoopsOptions {
/** Explicit vault-relative roots; overrides `notes.read_paths`. */
readonly paths?: ReadonlyArray<string>;
/** Extra vault-relative exclude prefixes. */
readonly exclude?: ReadonlyArray<string>;
/** Per-file byte cap. Defaults to the 1 MiB `scanInline` cap. */
readonly maxFileSizeBytes?: number;
/**
* Whether the caller may read a vault-relative path. Tested before the
* file is read, so a page it rejects is neither read nor counted in
* `scannedFiles`. Omitted, every walked file is read (the operator's
* own shell).
*/
readonly readable?: (rel: string) => boolean;
}
/**
* Collapse a loop text to its id-normal form: trim, then collapse every
* run of whitespace to a single space. No case folding - the hash must
* be byte-exact so non-Latin scripts are handled identically.
*/
function normaliseLoopText(text: string): string {
return text.trim().replace(/\s+/g, " ");
}
/** Derive the deterministic short id from a loop's normalized text. */
function deriveLoopId(text: string): string {
return createHash("sha256").update(normaliseLoopText(text), "utf8").digest("hex").slice(0, 8);
}
/** Explicit `id=` wins; otherwise derive from the loop text. */
function resolveLoopId(marker: ParsedMarker): string {
if (typeof marker.id === "string" && marker.id.length > 0) return marker.id;
return deriveLoopId(marker.text ?? "");
}
interface OpenRecord {
readonly id: string;
readonly text: string;
readonly path: string;
readonly line: number;
}
interface CloseRecord {
readonly id: string;
readonly path: string;
readonly line: number;
}
/**
* Scan the configured note space and compute the open-loop set.
*
* Read-only and deterministic. Returns a frozen {@link OpenLoopScan}.
* When no note paths are configured the scan is a well-formed empty
* result rather than an error - there is simply nothing to walk.
*/
export function scanOpenLoops(vault: string, opts: ScanOpenLoopsOptions = {}): OpenLoopScan {
const roots = resolveNoteRoots(vault, opts.paths);
if (roots.length === 0) return emptyScan();
const rules = buildNoteWalkRules(vault, opts.exclude);
const cap = opts.maxFileSizeBytes ?? MAX_FILE_SIZE_BYTES;
// Collect every file first so we can scan in a deterministic
// vault-relative-path order independent of the walker's internal
// traversal order. This is what makes "first occurrence in walk
// order" (duplicate collapse) stable across runs.
const files: NoteWalkFile[] = [
...walkMarkdownFiles(vault, roots, rules, { maxFileSizeBytes: cap }),
];
files.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
const opens: OpenRecord[] = [];
const closes: CloseRecord[] = [];
let scannedFiles = 0;
for (const file of files) {
if (opts.readable !== undefined && !opts.readable(file.relPath)) continue;
let content: string;
try {
content = readFileSync(file.absPath, "utf8");
} catch {
continue; // races a delete - skip, do not count
}
scannedFiles++;
for (const marker of discoverMarkers(content)) {
if (marker.kind !== "loop") continue; // feedback / set ignored
if (marker.loop === "close") {
if (typeof marker.id === "string" && marker.id.length > 0) {
closes.push({ id: marker.id, path: file.relPath, line: marker.originLine });
}
continue;
}
if (marker.loop === "open") {
opens.push({
id: resolveLoopId(marker),
text: marker.text ?? "",
path: file.relPath,
line: marker.originLine,
});
}
}
}
const closeIds = new Set(closes.map((c) => c.id));
const openIds = new Set(opens.map((o) => o.id));
// First open marker per id (in walk order) is canonical; the rest are
// duplicates. Iterating `opens` in order preserves first occurrence.
const canonical = new Map<string, OpenRecord>();
const duplicates: DuplicateOpenLoop[] = [];
for (const rec of opens) {
if (canonical.has(rec.id)) {
duplicates.push({ id: rec.id, text: rec.text, path: rec.path, line: rec.line });
continue;
}
canonical.set(rec.id, rec);
}
const openLoops: OpenLoop[] = [];
let closedCount = 0;
for (const rec of canonical.values()) {
if (closeIds.has(rec.id)) {
closedCount++;
continue;
}
openLoops.push({ id: rec.id, text: rec.text, path: rec.path, line: rec.line });
}
const orphanCloses: OrphanClose[] = closes
.filter((c) => !openIds.has(c.id))
.map((c) => ({ id: c.id, path: c.path, line: c.line }));
return Object.freeze({
openLoops: Object.freeze(openLoops),
counts: Object.freeze({ openCount: openLoops.length, closedCount, scannedFiles }),
duplicates: Object.freeze(duplicates),
orphanCloses: Object.freeze(orphanCloses),
});
}
function emptyScan(): OpenLoopScan {
return Object.freeze({
openLoops: Object.freeze([]) as ReadonlyArray<OpenLoop>,
counts: Object.freeze({ openCount: 0, closedCount: 0, scannedFiles: 0 }),
duplicates: Object.freeze([]) as ReadonlyArray<DuplicateOpenLoop>,
orphanCloses: Object.freeze([]) as ReadonlyArray<OrphanClose>,
});
}