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
/**
* The ask-once batching layer over the undistilled backlog
* (session-mining-economy, t_0358af42).
*
* Vault-wide cross-session dedup already ships at WRITE time
* (`buildDedupIndex` plus the commit-time gate): a recurring fact is
* written once, whatever number of sessions raised it. What shipped
* nowhere was dedup of the ASK - the operator was still asked about the
* same material once per session that raised it, because suppression
* happened only after the proposal reached the write gate.
*
* `buildBacklogProposals` is the pure core that moves dedup before the
* ask. It takes the pending distill candidates raised by undistilled
* sessions plus a `loadDedupIndex` result, drops every candidate whose
* `computeDedupHash` already exists in the vault (naming each drop), and
* collapses the remainder to ONE proposal per distinct hash across
* sessions, naming every contributing session. The output is one batched
* envelope for the calling agent to present; the kernel stays LLM-free
* and runs no interactive loop - it groups, it does not ask.
*
* A session whose every candidate was already known appears in
* `reportOnlySessions` and in no proposal: the report says "known,
* nothing new" about it, which is a different statement from proposing
* its material again.
*/
import { computeDedupHash, type DedupIndexEntry } from "../dedup-hash.ts";
/** One pending distill candidate raised by an undistilled backlog session. */
export interface BacklogCandidate {
/** The portable session identity that raised the candidate. */
readonly sessionId: string;
readonly topic: string;
readonly signal: "positive" | "negative";
readonly principle: string;
readonly scope?: string;
}
/** One candidate suppressed from the ask because the vault already holds it. */
export interface BacklogProposalDrop {
readonly sessionId: string;
readonly topic: string;
readonly dedupHash: string;
}
/** One ask-once proposal: everything the vault does not yet hold, per hash. */
export interface BacklogProposal {
readonly dedupHash: string;
/**
* The representative form of the hash class: the candidate whose
* (topic, signal, principle, scope) tuple sorts first within the class,
* so the proposal text cannot depend on the caller's input order. The
* dedup hash normalizes case and width, so one class can hold
* candidates whose raw fields differ.
*/
readonly topic: string;
readonly signal: "positive" | "negative";
readonly principle: string;
readonly scope?: string;
/** Every session that raised this hash, sorted, unique. */
readonly sessions: ReadonlyArray<string>;
}
/** The batched envelope: what to ask, what was suppressed, who raised nothing new. */
export interface BacklogProposals {
readonly proposals: ReadonlyArray<BacklogProposal>;
readonly dropped: ReadonlyArray<BacklogProposalDrop>;
/** Sessions whose every candidate was already known. Sorted. */
readonly reportOnlySessions: ReadonlyArray<string>;
}
/**
* Batch the pending candidates ask-once. Empty input is an explicit empty
* envelope, not silence. Deterministic: proposals sort by dedup hash, each
* proposal's representative fields are the content-stable pick within its
* hash class, drops sort by session then topic, so two runs over the same
* backlog agree byte for byte regardless of the input order.
*/
export function buildBacklogProposals(
pending: ReadonlyArray<BacklogCandidate>,
dedupIndex: ReadonlyMap<string, DedupIndexEntry>,
): BacklogProposals {
const dropped: BacklogProposalDrop[] = [];
const sessionsByHash = new Map<string, Set<string>>();
const representativeByHash = new Map<string, BacklogCandidate>();
const sessionsWithProposals = new Set<string>();
for (const candidate of pending) {
const hash = computeDedupHash({
topic: candidate.topic,
signal: candidate.signal,
principle: candidate.principle,
scope: candidate.scope,
});
if (dedupIndex.has(hash)) {
dropped.push({ sessionId: candidate.sessionId, topic: candidate.topic, dedupHash: hash });
continue;
}
let sessions = sessionsByHash.get(hash);
if (sessions === undefined) {
sessions = new Set();
sessionsByHash.set(hash, sessions);
}
const current = representativeByHash.get(hash);
if (current === undefined || precedes(candidate, current)) {
representativeByHash.set(hash, candidate);
}
sessions.add(candidate.sessionId);
sessionsWithProposals.add(candidate.sessionId);
}
const raised = new Set(pending.map((candidate) => candidate.sessionId));
const reportOnlySessions = [...raised]
.filter((sessionId) => !sessionsWithProposals.has(sessionId))
.toSorted();
const proposals: BacklogProposal[] = [...sessionsByHash.keys()].toSorted().map((hash) => {
const representative = representativeByHash.get(hash)!;
return {
dedupHash: hash,
topic: representative.topic,
signal: representative.signal,
principle: representative.principle,
// The hash unifies a missing scope with an empty one, so the
// representative's raw empty string is dropped too: a proposal that
// carried it or not depending on which candidate won the class
// would not be byte-for-byte deterministic.
...(representative.scope ? { scope: representative.scope } : {}),
sessions: [...sessionsByHash.get(hash)!].toSorted(),
};
});
dropped.sort(compareDrops);
return { proposals, dropped, reportOnlySessions };
}
/** Drops in (session, topic, dedup hash) order. */
function compareDrops(a: BacklogProposalDrop, b: BacklogProposalDrop): number {
if (a.sessionId !== b.sessionId) return a.sessionId.localeCompare(b.sessionId);
if (a.topic !== b.topic) return a.topic.localeCompare(b.topic);
return a.dedupHash.localeCompare(b.dedupHash);
}
/**
* Whether `a`'s (topic, signal, principle, scope) tuple sorts before `b`'s,
* field by field in code-unit order. The missing and the empty scope
* compare equal, mirroring the dedup hash's own unification, so a class
* whose members differ only there still picks one representative whatever
* the input order.
*/
function precedes(a: BacklogCandidate, b: BacklogCandidate): boolean {
if (a.topic !== b.topic) return a.topic < b.topic;
if (a.signal !== b.signal) return a.signal < b.signal;
if (a.principle !== b.principle) return a.principle < b.principle;
const aScope = a.scope ?? "";
const bScope = b.scope ?? "";
return aScope < bScope;
}