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
/**
* Post-creation expiration mutation for signals and preferences
* (unit 3c / t_5e338af1).
*
* `expiration.ts` has had a validator, a read filter and a writer
* parameter on both artifact kinds since C5, and nothing has ever been
* able to CHANGE the field once written. The gap is the whole of this
* module: an operator who set "until 2026-07-15" and then extended the
* migration had no way to say so, and one who set nothing had no way to
* add a lifetime to a rule that turned out to be temporary.
*
* ## Why the mutation lives here and not on the note surfaces
*
* `brain_update_note` and `note_lifecycle` both run every path through
* `resolveNoteTarget`, which refuses the `Brain/` machinery root for
* every note path it is given. That refusal is load-bearing - it is what
* keeps a note-editing surface from rewriting a preference - so reaching
* signals and preferences from there would mean carving an exception
* into the one guard that makes those surfaces safe. This module
* addresses the artifacts by ID instead, exactly as `retireSignal` does,
* and never accepts a path at all.
*
* ## One chokepoint
*
* Every value written here goes through
* {@link normalizeExpirationDate}, which is also the only door
* `writeSignal` and `writePreference` use. That matters more than it
* looks: the READ side deliberately fails open on an unparseable date so
* a corrupted value surfaces rather than silently hiding a memory, and
* that tolerance is only safe while every write is validated. A second
* writer skipping the validator would turn a documented fail-open into a
* memory that never expires and nobody notices.
*
* Clearing is explicit, and it REMOVES the key rather than writing an
* empty one. An empty `expiration_date` parses to nothing, fails open on
* read, and reads on disk as a lifetime somebody meant to set.
*/
import { existsSync } from "node:fs";
import { join } from "node:path";
import type { FrontmatterMap } from "../types.ts";
import { parseFrontmatter, writeFrontmatterAtomic } from "../vault.ts";
import { regenerateActiveQuiet } from "./active.ts";
import { EXPIRATION_DATE_FIELD, normalizeExpirationDate } from "./expiration.ts";
import { appendLogEvent } from "./log.ts";
import { brainDirsForWrite, ensureInsideVault } from "./paths.ts";
import { storePreferenceMeta } from "./preference.ts";
import { routePreferencePage } from "./preference-page-write.ts";
import { preferencesStoreOnly, storePreferenceEntry } from "./preference-store.ts";
import { PREFERENCE_OPAQUE_FIELDS, SIGNAL_OPAQUE_FIELDS } from "../store/operation-privacy.ts";
import { withOperationPrivacy } from "../store/operation-scope.ts";
import { isPrivateFrontmatter } from "../store/private-page.ts";
import { rowNamesPrivatePage } from "../store/reference-privacy.ts";
import { preferencePageRel, signalPageRel } from "../store/read/memory-ids.ts";
import { routeSignalState, storeSignal } from "./signal-state.ts";
import { isoSecond } from "./time.ts";
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
/**
* The value that CLEARS an expiration.
*
* A word rather than an empty string, and that is the point: `--expires
* ""` is what a shell produces when a variable did not expand, so
* accepting it would let a broken script silently un-expire a memory.
* Clearing has to be something a caller can only type on purpose.
*/
export const EXPIRATION_CLEAR = "none";
/** The artifact kinds this surface can address. */
export const EXPIRATION_TARGET_KIND = Object.freeze({
signal: "signal",
preference: "preference",
} as const);
/** Closed union over {@link EXPIRATION_TARGET_KIND}. */
export type ExpirationTargetKind =
(typeof EXPIRATION_TARGET_KIND)[keyof typeof EXPIRATION_TARGET_KIND];
/**
* The codes the three refusals below are reported under on the MCP wire:
* each class's own name, which `brain_expire` has always sent as
* `error.data.code`. One definition, so the class names and the boundary
* registry cannot drift apart.
*/
export const EXPIRATION_REFUSAL_CODE = Object.freeze({
invalidTarget: "InvalidExpirationTargetError",
targetNotFound: "ExpirationTargetNotFoundError",
invalidValue: "ExpirationValueError",
} as const);
/** Membership list over {@link EXPIRATION_REFUSAL_CODE}. */
export const EXPIRATION_REFUSAL_CODES = Object.freeze(Object.values(EXPIRATION_REFUSAL_CODE));
/**
* An id shape that could never name an artifact, so no filesystem path is
* formed from it. The regexes also close path traversal: no separator
* survives either of them.
*/
const SIGNAL_ID_RE = /^sig-\d{4}-\d{2}-\d{2}-[A-Za-z0-9][A-Za-z0-9._-]*$/;
const PREFERENCE_ID_RE = /^(?:pref|ret)-[A-Za-z0-9][A-Za-z0-9._-]*$/;
/** The caller named something this surface cannot address. */
export class InvalidExpirationTargetError extends Error {
readonly id: string;
constructor(id: string) {
super(
`invalid expiration target ${JSON.stringify(id)} - expected sig-<date>-<slug>, ` +
"pref-<slug> or ret-<slug>",
);
this.name = EXPIRATION_REFUSAL_CODE.invalidTarget;
this.id = id;
}
}
/** The id is well-formed and no file carries it. Never a silent no-op. */
export class ExpirationTargetNotFoundError extends Error {
readonly id: string;
readonly searched: ReadonlyArray<string>;
constructor(id: string, searched: ReadonlyArray<string>) {
super(`no signal or preference with id ${JSON.stringify(id)}; searched ${searched.join(", ")}`);
this.name = EXPIRATION_REFUSAL_CODE.targetNotFound;
this.id = id;
this.searched = Object.freeze([...searched]);
}
}
/**
* The value is not a date this project can compare against a clock.
*
* A typed wrapper around {@link normalizeExpirationDate}'s message rather
* than a second validator: the surfaces branch on the class, and the
* sentence a caller reads is still the chokepoint's own.
*/
export class ExpirationValueError extends Error {
readonly value: string;
constructor(value: string, reason: string) {
super(reason);
this.name = EXPIRATION_REFUSAL_CODE.invalidValue;
this.value = value;
}
}
export interface SetExpirationResult {
readonly id: string;
readonly kind: ExpirationTargetKind;
/** Vault-relative path of the artifact that was rewritten. */
readonly path: string;
/** The normalised value now on the artifact; `null` once cleared. */
readonly expiration: string | null;
/** What the artifact carried before this call; `null` when it carried none. */
readonly previous: string | null;
/** False when the artifact already said exactly this - no bytes were written. */
readonly changed: boolean;
}
export interface SetExpirationOptions {
/** Agent stamped on the audit event; defaults to the surface's own name. */
readonly agent?: string;
/** Injected clock, so a run stays reproducible. */
readonly now?: Date;
/**
* The vault-relative paths the caller may read. A candidate file it may
* not read is passed over as if it were not there, so a record withheld
* from the caller is refused with the unknown-id error and nothing is
* written to it. Absent, every candidate counts.
*/
readonly readable?: (rel: string) => boolean;
}
/** Agent recorded when the caller names none. */
const DEFAULT_AGENT = "set_expiration";
/**
* Sentinel for a stored value the validator cannot parse. It is equal to
* nothing, so the rewrite that repairs a corrupted date always happens -
* a `null` there would collide with the clear-what-is-already-clear case
* and leave the junk on disk.
*/
const UNPARSEABLE_EXPIRATION = Symbol("unparseable-expiration");
/**
* The stored value in the form the new one is compared against.
*
* Both sides have to come through {@link normalizeExpirationDate} for
* "already says exactly this" to be a statement about the LIFETIME rather
* than about the spelling: `2026-07-15` and `2026-07-15T00:00:00Z` are
* one date, and re-setting one over the other used to rewrite the file
* and append an audit event describing no change at all.
*/
function comparableExpiration(previous: string | null): string | null | symbol {
if (previous === null) return null;
try {
return normalizeExpirationDate(previous);
} catch {
return UNPARSEABLE_EXPIRATION;
}
}
/** Where an id of each shape can live, in search order. */
function candidatePaths(vault: string, id: string): { kind: ExpirationTargetKind; dirs: string[] } {
const dirs = brainDirsForWrite(vault);
if (SIGNAL_ID_RE.test(id)) {
// A signal outlives the inbox: the dream pass moves consumed signals
// to `inbox/processed/`, archives unconsumed ones that left the
// contradiction window to `inbox/archived/`, and `retireSignal` moves
// retired ones to `Brain/retired/`. All four are still readable
// memories, so all four can carry a lifetime.
return {
kind: EXPIRATION_TARGET_KIND.signal,
dirs: [dirs.inbox, dirs.processed, dirs.archived, dirs.retired],
};
}
if (PREFERENCE_ID_RE.test(id)) {
return {
kind: EXPIRATION_TARGET_KIND.preference,
dirs: [dirs.preferences, dirs.retired],
};
}
throw new InvalidExpirationTargetError(id);
}
/** The artifact an expiration change addresses, wherever it lives. */
interface ExpirationTarget {
/** Vault-relative path, `/`-separated (nominal once switched). */
readonly relPath: string;
readonly abs: string;
readonly previous: string | null;
/** The page's frontmatter on an unswitched machine; `null` once switched. */
readonly frontmatter: Record<string, unknown> | null;
}
function previousOf(meta: Readonly<Record<string, unknown>>): string | null {
const raw = meta[EXPIRATION_DATE_FIELD];
return typeof raw === "string" && raw.length > 0 ? raw : null;
}
/** The first candidate page that exists, in search order. */
function pageTarget(
vault: string,
id: string,
dirs: ReadonlyArray<string>,
opts: SetExpirationOptions,
): ExpirationTarget {
const searched: string[] = [];
for (const dir of dirs) {
const candidate = ensureInsideVault(join(dir, `${id}.md`), vault);
const rel = candidate
.slice(vault.length + 1)
.split("\\")
.join("/");
searched.push(rel);
if (existsSync(candidate) && (opts.readable === undefined || opts.readable(rel))) {
const [meta] = parseFrontmatter(candidate);
return { relPath: rel, abs: candidate, previous: previousOf(meta), frontmatter: meta };
}
}
throw new ExpirationTargetNotFoundError(id, searched);
}
/**
* The signal or preference the store's folds hold under `id`. A signal
* in any state but rejected, and a preference active or retired, can
* carry a lifetime, as their pages could.
*/
function storeTarget(
vault: string,
kind: ExpirationTargetKind,
id: string,
opts: SetExpirationOptions,
): ExpirationTarget {
if (kind === EXPIRATION_TARGET_KIND.signal) {
const found = storeSignal(id);
// The page the signal's state places it at, never an empty path.
const rel = found === undefined ? null : signalPageRel(id, found.state);
if (
found === undefined ||
rel === null ||
found.state === "rejected" ||
!readableRel(rel, opts)
) {
throw new ExpirationTargetNotFoundError(id, [rel ?? id]);
}
return {
relPath: rel,
abs: join(vault, ...rel.split("/")),
previous: previousOf(found.frontmatter),
frontmatter: null,
};
}
const slug = preferenceSlugOf(id);
const page = storePreferenceMeta(slug);
const rel = preferencePageRel(slug, page?.retired === true);
if (page === null || page.retired !== id.startsWith("ret-") || !readableRel(rel, opts)) {
throw new ExpirationTargetNotFoundError(id, [rel]);
}
return {
relPath: rel,
abs: join(vault, ...rel.split("/")),
previous: previousOf(page.meta),
frontmatter: null,
};
}
/** The slug of a preference id, active (`pref-`) or retired (`ret-`). */
function preferenceSlugOf(id: string): string {
return id.replace(/^(pref|ret)-/, "");
}
function readableRel(rel: string, opts: SetExpirationOptions): boolean {
return opts.readable === undefined || opts.readable(rel);
}
/**
* Set, change, or clear the `expiration_date` of one signal or
* preference, addressed by id.
*
* `expires` is a date-only `YYYY-MM-DD`, a full ISO-8601 timestamp, or
* {@link EXPIRATION_CLEAR}. Every other value is refused before any file
* is opened.
*/
export function setExpiration(
vault: string,
id: string,
expires: string,
opts: SetExpirationOptions = {},
): SetExpirationResult {
// Vault-identity write guard (context-integrity-gates, Unit J).
assertVaultIdentityForWrite(vault);
const trimmed = id.trim();
const { kind, dirs } = candidatePaths(vault, trimmed);
// Validate BEFORE the walk, so a junk date cannot depend on whether the
// artifact happened to exist for whether it is reported as junk.
const clearing = expires.trim() === EXPIRATION_CLEAR;
let normalized: string | null = null;
if (!clearing) {
try {
normalized = normalizeExpirationDate(expires);
} catch (err) {
throw new ExpirationValueError(expires, (err as Error).message);
}
}
// Store-only (task 2.10): the artifact is found in the store's folds and
// the change is one record; no page is rewritten.
const storeOnly = preferencesStoreOnly(vault);
const target = storeOnly
? storeTarget(vault, kind, trimmed, opts)
: pageTarget(vault, trimmed, dirs, opts);
const { relPath, previous, frontmatter } = target;
if (comparableExpiration(previous) === normalized) {
// Byte-identical no-op, including the clear-what-is-already-clear
// case. Reporting `changed: false` rather than rewriting keeps a
// re-run out of the audit log and off the disk.
return Object.freeze({
id: trimmed,
kind,
path: relPath,
expiration: normalized,
previous,
changed: false,
});
}
const legacy = (): void => {
const [meta, body] = parseFrontmatter(target.abs);
const nextMeta: FrontmatterMap = { ...meta };
if (normalized === null) delete nextMeta[EXPIRATION_DATE_FIELD];
else nextMeta[EXPIRATION_DATE_FIELD] = normalized;
writeFrontmatterAtomic(target.abs, nextMeta, body, { overwrite: true });
};
const fields = { [EXPIRATION_DATE_FIELD]: normalized };
const slug = preferenceSlugOf(trimmed);
// One verdict for the whole operation (the state record and its log
// event): the target is private when the fold holds it private once
// switched, or when its page is private or names a private page before
// the switch. The one-field patch alone would judge nothing private.
const targetPrivate = (): boolean => {
if (storeOnly) {
return kind === EXPIRATION_TARGET_KIND.signal
? (storeSignal(trimmed)?.private ?? true)
: (storePreferenceEntry(slug)?.private ?? true);
}
if (frontmatter === null) return true;
const opaque =
kind === EXPIRATION_TARGET_KIND.signal ? SIGNAL_OPAQUE_FIELDS : PREFERENCE_OPAQUE_FIELDS;
return isPrivateFrontmatter(frontmatter) || rowNamesPrivatePage(vault, frontmatter, opaque);
};
const now = opts.now ?? new Date();
const logChange = (): void => {
appendLogEvent(vault, {
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.expirationSet,
body: {
target: `[[${trimmed}]]`,
kind,
// Both sides of the change, because "cleared" and "set to X" are
// different events and the log is where an operator reconstructs
// which one happened.
expiration: normalized ?? EXPIRATION_CLEAR,
previous: previous ?? EXPIRATION_CLEAR,
agent: opts.agent?.trim() ? opts.agent.trim() : DEFAULT_AGENT,
},
});
};
let preferenceWritten = false;
try {
withOperationPrivacy(targetPrivate, () => {
if (kind === EXPIRATION_TARGET_KIND.signal) {
routeSignalState({
vault,
id: trimmed,
fields,
...(opts.agent?.trim() ? { agent: opts.agent.trim() } : {}),
...(frontmatter !== null ? { legacyFrontmatter: frontmatter } : {}),
legacy,
});
} else {
routePreferencePage({
vault,
slug,
frontmatter: { [EXPIRATION_DATE_FIELD]: normalized ?? null } as FrontmatterMap,
legacy,
});
preferenceWritten = true;
}
logChange();
});
} finally {
// The preference write is authoritative even if its audit append throws.
if (preferenceWritten && trimmed.startsWith("pref-")) {
regenerateActiveQuiet(vault, { now, legacyOnly: true });
}
}
return Object.freeze({
id: trimmed,
kind,
path: relPath,
expiration: normalized,
previous,
changed: true,
});
}