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.
TypeScript agent-memoryai-agentsanthropicclaude-codecursorgitknowledge-baseknowledge-graphllmmarkdownmcpmcp-servermodel-context-protocolnote-takingobsidianpkmragsecond-brainself-hostedzettelkasten
feat(validity): parse valid_until / superseded_by; add validity overlay
Ronalds Palacis197180199e46
diff --git a/lib/vault/authority.ts b/lib/vault/authority.tsindex 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.tsindex 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.tsindex 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