Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

feat(validity): parse valid_until / superseded_by; add validity overlay

Ronalds Palacis197180199e46
diff --git a/lib/vault/authority.ts b/lib/vault/authority.ts
index 074e447..23041de 100644
--- a/lib/vault/authority.ts
+++ b/lib/vault/authority.ts
@@ -63,6 +63,50 @@ export function weightOf(a: Authority): number {
return WEIGHT[a];
}
+/** Base authority overlaid with temporal validity, plus a human-readable reason when retired. */
+export interface EffectiveAuthority {
+ authority: Authority;
+ /** Why the note is retired, e.g. "superseded by price-live" or "expired 2026-06-01". */
+ reason?: string;
+ /** True when the note must not be treated as current fact (superseded, expired, or archived). */
+ retired: boolean;
+}
+
+/**
+ * Overlay temporal validity onto an already-known base authority.
+ *
+ * `authorityOf` is text-only and timeless, so a `locked` note stays authoritative forever. This
+ * demotes a note that was explicitly superseded (`superseded_by`) or has passed its `valid_until`
+ * to `superseded`, regardless of how authoritative its text claims to be — and returns a reason.
+ * Precedence: archived → superseded (explicit) → expired.
+ *
+ * Kept separate from `effectiveAuthority` so the search path, which only has the pre-computed base
+ * authority in the index (not status/tags), can overlay without re-classifying.
+ */
+export function overlayValidity(
+ base: Authority,
+ validUntil: number | null | undefined,
+ supersededBy: string | null | undefined,
+ now: number = Date.now(),
+): EffectiveAuthority {
+ if (base === "archived") return { authority: "archived", reason: "archived", retired: true };
+ if (supersededBy) return { authority: "superseded", reason: `superseded by ${supersededBy}`, retired: true };
+ if (base === "superseded") return { authority: "superseded", reason: "marked superseded", retired: true };
+ if (validUntil != null && validUntil < now) {
+ const on = new Date(validUntil).toISOString().slice(0, 10);
+ return { authority: "superseded", reason: `expired ${on} (no replacement)`, retired: true };
+ }
+ return { authority: base, retired: false };
+}
+
+/** The effective authority of a note: its text-based class, overlaid with validity. For live reads. */
+export function effectiveAuthority(
+ meta: { path: string; status?: string; tags?: string[]; validUntil?: number; supersededBy?: string },
+ now: number = Date.now(),
+): EffectiveAuthority {
+ return overlayValidity(authorityOf(meta), meta.validUntil, meta.supersededBy, now);
+}
+
/**
* The live ranking contract, returned by brain_schema so an agent working against a vault
* it has never seen can discover the rules instead of guessing them.
diff --git a/lib/vault/parse.ts b/lib/vault/parse.ts
index e6527f9..2e0ffb0 100644
--- a/lib/vault/parse.ts
+++ b/lib/vault/parse.ts
@@ -97,6 +97,37 @@ export interface ParsedNote {
rawLinks: RawLink[];
}
+/**
+ * Parse a `valid_until` frontmatter value to an epoch-ms deadline, inclusive through the end of
+ * that day. gray-matter/js-yaml turns a bare `valid_until: 2026-06-01` into a JS `Date`; a quoted
+ * or odd value stays a string. A date-only value (midnight UTC) expires at 23:59:59.999 of that
+ * day, not 00:00, so a note doesn't go stale mid-business-day. Returns undefined when unparseable.
+ */
+export function parseValidUntil(v: unknown): number | undefined {
+ if (v == null) return undefined;
+ let d: Date;
+ if (v instanceof Date) {
+ d = v;
+ } else {
+ const ms = Date.parse(String(v).trim());
+ if (Number.isNaN(ms)) return undefined;
+ d = new Date(ms);
+ }
+ const t = d.getTime();
+ if (Number.isNaN(t)) return undefined;
+ const midnightUTC =
+ d.getUTCHours() === 0 && d.getUTCMinutes() === 0 && d.getUTCSeconds() === 0 && d.getUTCMilliseconds() === 0;
+ return midnightUTC ? t + 24 * 60 * 60 * 1000 - 1 : t;
+}
+
+/** Normalize a `superseded_by` value (may be `[[wikilink]]`, alias, or path) to a bare stem. */
+function supersededStem(v: unknown): string | undefined {
+ if (v == null) return undefined;
+ const inner = String(v).replace(/^\s*\[\[/, "").replace(/\]\]\s*$/, "");
+ const stem = stemOf(inner);
+ return stem || undefined;
+}
+
export function parseNote(relPath: string, raw: string): ParsedNote {
let data: Record<string, unknown> = {};
let body = raw;
@@ -133,6 +164,8 @@ export function parseNote(relPath: string, raw: string): ParsedNote {
created: data.created != null ? String(data.created) : undefined,
updated:
data.updated != null ? String(data.updated) : data.date != null ? String(data.date) : undefined,
+ validUntil: parseValidUntil(data.valid_until),
+ supersededBy: supersededStem(data.superseded_by),
frontmatter: data,
frontmatterError,
};
diff --git a/lib/vault/types.ts b/lib/vault/types.ts
index b6faccb..1d13fd1 100644
--- a/lib/vault/types.ts
+++ b/lib/vault/types.ts
@@ -13,6 +13,10 @@ export interface NoteMeta {
status?: string;
created?: string;
updated?: string;
+ /** From `valid_until:` — epoch ms, inclusive through end of that day. Past it, the note is stale. */
+ validUntil?: number;
+ /** From `superseded_by:` — the stem of the note that replaced this one. Marks this note retired. */
+ supersededBy?: string;
frontmatter: Record<string, unknown>;
/**
* Set when the note opens with `---` but its YAML could not be parsed. The frontmatter is