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
/**
* Derived-fact synthesis with premise provenance (Knowledge Provenance suite).
*
* A derived fact is a second-order conclusion ("because A and B, therefore C")
* the calling agent reasons out from existing premise preferences. OSB is
* provider-agnostic and runs no model: the agent supplies the conclusion and
* names its premises; OSB owns the deterministic half - it validates that each
* premise preference exists, then commits the derived fact as an unconfirmed
* preference carrying a `deduced`/`inferred` provenance level and premise
* wikilinks in `evidenced_by`.
*
* Recall trusts an operator-stated rule above a machine-derived one; the
* provenance level is what makes that ordering possible (see
* provenance/provenance.ts and the recall trust-ordering helper).
*/
import { vaultRelative } from "../path-safety.ts";
import { loadBrainConfig, DEFAULT_BRAIN_CONFIG } from "./policy.ts";
import { memoryPageExists } from "./memory-pages.ts";
import { preferencePath } from "./paths.ts";
import { writePreference } from "./preference.ts";
import { DERIVED_FACT_SHAPE, DERIVED_FACT_SURFACE, assertResponseShape } from "./response-shape.ts";
import { isoSecond } from "./time.ts";
import { asProvenanceLevel, type ProvenanceLevel } from "./provenance/provenance.ts";
export interface DeriveFactInput {
readonly slug: string;
readonly topic: string;
readonly principle: string;
/** Premise preference ids (`pref-<slug>` or bare `<slug>`), at least one. */
readonly premises: readonly string[];
/** Trust level of the derivation: `deduced` (entailed) or `inferred` (pattern). */
readonly level: ProvenanceLevel;
}
export interface DeriveFactOptions {
readonly now: Date;
/**
* Plugin config the writing agent's identity is resolved from when the
* ownership gate stamps the new preference. Absent falls back to the
* default config discovery; a surface running against a non-default
* config passes its own.
*/
readonly configPath?: string;
/**
* The vault-relative paths the caller may read. A premise preference it
* may not read is refused exactly as a missing one is, before anything
* is written. Absent, every preference counts.
*/
readonly readable?: (rel: string) => boolean;
}
export interface DeriveFactResult {
readonly id: string;
}
/** A derived-fact request failed validation; nothing was written. */
export class DeriveFactError extends Error {
constructor(message: string) {
super(message);
this.name = "DeriveFactError";
}
}
/**
* Narrow an agent-supplied level to a derivation level. Shared by the payload
* ingress and {@link deriveFact} so the rejection reads identically wherever
* an unusable level arrives.
*/
function requireDerivationLevel(raw: unknown): ProvenanceLevel {
const level = asProvenanceLevel(raw);
if (level === null || level === "stated") {
throw new DeriveFactError(
`a derived fact must be 'deduced' or 'inferred', not ${JSON.stringify(raw)}`,
);
}
return level;
}
/**
* Ingress of the agent-authored derived-fact payload. The payload is checked
* against the frozen derived-fact shape BEFORE any field is read, so a
* structurally wrong premise list is refused by path rather than silently
* stringified. A violation throws `ResponseShapeError` and nothing is written.
*/
export function parseDeriveFactInput(payload: unknown): DeriveFactInput {
assertResponseShape(DERIVED_FACT_SURFACE, DERIVED_FACT_SHAPE, payload);
const rec = payload as Record<string, unknown>;
return {
slug: rec["slug"] as string,
topic: rec["topic"] as string,
principle: rec["principle"] as string,
premises: Object.freeze([...(rec["premises"] as ReadonlyArray<string>)]),
level: requireDerivationLevel(rec["level"]),
};
}
/** Strip a leading `pref-` so a premise can be given as an id or a bare slug. */
function premiseSlug(premise: string): string {
const trimmed = premise.trim();
return trimmed.startsWith("pref-") ? trimmed.slice("pref-".length) : trimmed;
}
function addDays(date: Date, days: number): Date {
const next = new Date(date.getTime());
next.setUTCDate(next.getUTCDate() + days);
return next;
}
function unconfirmedWindowDays(vault: string): number {
try {
return loadBrainConfig(vault).dream.unconfirmed_window_days;
} catch {
return DEFAULT_BRAIN_CONFIG.dream.unconfirmed_window_days;
}
}
/**
* Commit a derived fact. Validates the level is a derivation (not `stated`)
* and that every premise preference exists, then writes an unconfirmed
* preference with the provenance level and premise wikilinks. Throws
* {@link DeriveFactError} with no write on any validation failure.
*/
export function deriveFact(
vault: string,
input: DeriveFactInput,
opts: DeriveFactOptions,
): DeriveFactResult {
const level = requireDerivationLevel(input.level);
if (!input.slug.trim()) throw new DeriveFactError("derived fact missing slug");
if (!input.topic.trim()) throw new DeriveFactError("derived fact missing topic");
if (!input.principle.trim()) throw new DeriveFactError("derived fact missing principle");
if (input.premises.length === 0) {
throw new DeriveFactError("a derived fact must cite at least one premise");
}
const evidencedBy: string[] = [];
for (const premise of input.premises) {
const slug = premiseSlug(premise);
if (!slug) throw new DeriveFactError("premise id must not be empty");
const premisePath = preferencePath(vault, slug);
if (
!memoryPageExists(vault, vaultRelative(premisePath, vault)) ||
(opts.readable !== undefined && !opts.readable(vaultRelative(premisePath, vault)))
) {
throw new DeriveFactError(`premise preference not found: ${JSON.stringify(premise)}`);
}
evidencedBy.push(`[[pref-${slug}]]`);
}
const now = opts.now;
writePreference(
vault,
{
slug: input.slug,
topic: input.topic,
principle: input.principle,
created_at: isoSecond(now),
unconfirmed_until: isoSecond(addDays(now, unconfirmedWindowDays(vault))),
status: "unconfirmed",
evidenced_by: evidencedBy,
provenance: level,
},
opts.configPath !== undefined ? { configPath: opts.configPath } : {},
);
return { id: `pref-${input.slug.trim()}` };
}