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
import { existsSync, readdirSync } from "node:fs";
import { join } from "node:path";
import type { SignalLifecycle } from "../store/fold-signals.ts";
import { memoryFromStore } from "./memory-pages.ts";
import { storeRetiredRecords, storeSignalRecords } from "./memory-page-records.ts";
import { brainDirs, vaultRelative } from "./paths.ts";
import { parseRetired } from "./preference.ts";
import { parseSignal } from "./signal.ts";
import type { BrainRetired, BrainSignal } from "./types.ts";
export type RetentionAction = "keep" | "improve" | "park" | "prune";
export type RetentionArtifactType = "retired_preference" | "processed_signal";
export interface RetentionRecommendation {
readonly id: string;
readonly artifact_type: RetentionArtifactType;
readonly action: RetentionAction;
readonly reason: string;
readonly path: string;
}
export interface RetentionSummary {
readonly keep: number;
readonly improve: number;
readonly park: number;
readonly prune: number;
}
export interface RetentionReviewReport {
readonly schema_version: 1;
readonly generated_at: string;
readonly summary: RetentionSummary;
readonly recommendations: ReadonlyArray<RetentionRecommendation>;
}
export interface BuildRetentionReviewOptions {
readonly now?: Date;
}
/** The signal state a page in `inbox/processed/` stands for. */
const CONSUMED: ReadonlySet<SignalLifecycle> = new Set(["consumed"]);
const OLD_PROCESSED_SIGNAL_DAYS = 30;
const PARK_RETIRED_AFTER_DAYS = 90;
export function buildRetentionReview(
vault: string,
options: BuildRetentionReviewOptions = {},
): RetentionReviewReport {
const now = options.now ?? new Date();
const recommendations = [
...collectRetiredPreferences(vault, now),
...collectProcessedSignals(vault, now),
].toSorted((left, right) => left.id.localeCompare(right.id));
return Object.freeze({
schema_version: 1 as const,
generated_at: now.toISOString(),
summary: Object.freeze(summarizeRetention(recommendations)),
recommendations: Object.freeze(recommendations),
});
}
function collectRetiredPreferences(vault: string, now: Date): RetentionRecommendation[] {
if (memoryFromStore(vault)) {
// Store-only (task 2.10): the retired preferences of the fold.
return storeRetiredRecords(vault).records.map(({ path, retired }) =>
recommendRetired(vault, path, retired, now),
);
}
const retiredDir = brainDirs(vault).retired;
if (!existsSync(retiredDir)) return [];
const recommendations: RetentionRecommendation[] = [];
for (const name of readdirSync(retiredDir).toSorted()) {
if (!name.endsWith(".md")) continue;
const path = join(retiredDir, name);
try {
const retired = parseRetired(path);
recommendations.push(recommendRetired(vault, path, retired, now));
} catch {
continue;
}
}
return recommendations;
}
function collectProcessedSignals(vault: string, now: Date): RetentionRecommendation[] {
if (memoryFromStore(vault)) {
// Store-only: the signals the fold holds as consumed (`processed/`).
return storeSignalRecords(vault, CONSUMED).records.map(({ path, signal }) =>
recommendProcessedSignal(vault, path, signal, now),
);
}
const processedDir = brainDirs(vault).processed;
if (!existsSync(processedDir)) return [];
const recommendations: RetentionRecommendation[] = [];
for (const name of readdirSync(processedDir).toSorted()) {
if (!name.endsWith(".md")) continue;
const path = join(processedDir, name);
try {
const signal = parseSignal(path);
recommendations.push(recommendProcessedSignal(vault, path, signal, now));
} catch {
continue;
}
}
return recommendations;
}
function recommendRetired(
vault: string,
path: string,
retired: BrainRetired,
now: Date,
): RetentionRecommendation {
const applied = retired.applied_count ?? 0;
const violated = retired.violated_count ?? 0;
const ageDays = daysSince(retired.retired_at, now);
let action: RetentionAction;
let reason: string;
if (violated > applied && violated > 0) {
action = "improve";
reason = "retired rule has more violations than applications; review wording before reuse";
} else if (applied > 0 || retired.last_evidence_at !== null) {
action = "keep";
reason = "retired rule has an evidence trail worth preserving for audit";
} else if (ageDays >= PARK_RETIRED_AFTER_DAYS) {
action = "park";
reason = "old retired rule has no evidence trail; preserve inactive unless needed";
} else {
action = "improve";
reason = "recent retired rule has no evidence trail; review whether it needs clarification";
}
return Object.freeze({
id: retired.id,
artifact_type: "retired_preference" as const,
action,
reason,
path: vaultRelative(path, vault),
});
}
function recommendProcessedSignal(
vault: string,
path: string,
signal: BrainSignal,
now: Date,
): RetentionRecommendation {
const ageDays = daysSince(signal.created_at, now);
const hasSource = (signal.source?.length ?? 0) > 0;
let action: RetentionAction;
let reason: string;
if (!hasSource && ageDays >= OLD_PROCESSED_SIGNAL_DAYS) {
action = "prune";
reason =
"old processed one-off signal has no source pointers; safe candidate for manual pruning";
} else if (hasSource) {
action = "keep";
reason = "processed signal carries source pointers that preserve audit context";
} else {
action = "park";
reason = "processed signal is recent; leave it inactive until the next retention pass";
}
return Object.freeze({
id: signal.id,
artifact_type: "processed_signal" as const,
action,
reason,
path: vaultRelative(path, vault),
});
}
/**
* Count recommendations by action. Exported so a reader that keeps only
* some recommendations counts the ones it kept rather than shipping a
* summary of rows it withheld.
*/
export function summarizeRetention(
recommendations: ReadonlyArray<RetentionRecommendation>,
): RetentionSummary {
const summary = { keep: 0, improve: 0, park: 0, prune: 0 };
for (const recommendation of recommendations) {
summary[recommendation.action] += 1;
}
return summary;
}
function daysSince(iso: string, now: Date): number {
const timestamp = Date.parse(iso);
if (!Number.isFinite(timestamp)) return 0;
return Math.max(0, Math.floor((now.getTime() - timestamp) / (24 * 60 * 60 * 1000)));
}