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
/**
* Composite scope keys and source-identity keys (seam 1, t_37c05a34).
*
* The ONE module owning both:
* - the owner / session / project scope vocabulary that makes dedup
* per-scope and lets search opt into scope filters (t_37c05a34); and
* - the source-identity key that RRF/dedup uses so federated results from
* different origins never collide, plus the canonical source-set key the
* query cache scopes by (t_09b7ccea federation hardening).
*
* A single implementation is deliberate: a key mismatch silently collapses
* distinct results or fails to collapse duplicates, so the scope key and the
* source-identity key live here and nowhere else.
*
* Language-agnostic: every axis is an opaque identifier normalized purely
* structurally (NFC / case / slug), never matched against any word list. The
* owner axis reuses the v1.6 agent-scope normalization; session and project
* reuse the session-scope slug rule.
*/
import { normalizeAgentScope, pageOwner } from "./graph/agent-scope.ts";
import { resolveSessionScope } from "./brain/session-scope.ts";
import type { FrontmatterMap } from "./types.ts";
/** The ordered scope axes. Owner is the pre-existing v1.6 isolation axis. */
export const SCOPE_AXES = Object.freeze(["owner", "session", "project"] as const);
export type ScopeAxis = (typeof SCOPE_AXES)[number];
/** A page's or a request's normalized composite scope; null = axis absent. */
export interface CompositeScope {
readonly owner: string | null;
readonly session: string | null;
readonly project: string | null;
}
/**
* Normalize a session/project axis value into a slug, or null when blank
* or separator-only. Tolerant by design (frontmatter is untrusted input):
* an unusable value contributes no scope rather than throwing.
*/
function normalizeSlugAxis(value: unknown): string | null {
if (typeof value !== "string") return null;
const trimmed = value.trim();
if (trimmed.length === 0) return null;
try {
return resolveSessionScope(trimmed);
} catch {
return null;
}
}
/** The composite scope a page declares in its frontmatter. */
export function scopeFromFrontmatter(
meta: FrontmatterMap | Record<string, unknown>,
): CompositeScope {
return Object.freeze({
owner: pageOwner(meta as FrontmatterMap),
session: normalizeSlugAxis((meta as Record<string, unknown>)["session"]),
project: normalizeSlugAxis((meta as Record<string, unknown>)["project"]),
});
}
/**
* Normalize a caller-supplied scope filter. Owner uses the agent-scope
* normalization; session/project use the slug rule. Any axis left undefined
* or blank resolves to null (no filtering on that axis).
*/
export function normalizeScopeFilter(input: {
readonly owner?: string;
readonly session?: string;
readonly project?: string;
}): CompositeScope {
return Object.freeze({
owner: normalizeAgentScope(input.owner),
session: normalizeSlugAxis(input.session),
project: normalizeSlugAxis(input.project),
});
}
/**
* Canonical dedup-key contribution for a scope. Empty string when every
* axis is absent, so a scopeless page keys byte-identically to the
* pre-scope world (additive keying, no destructive migration). Axis labels
* are folded in so the same slug on different axes never collides.
*/
export function compositeScopeKey(scope: CompositeScope): string {
const parts: string[] = [];
for (const axis of SCOPE_AXES) {
const value = scope[axis];
if (value !== null) parts.push(`${axis}=${value}`);
}
return parts.join("\0");
}
/**
* Is a page with axis value `pageValue` reachable by a request for
* `requested` on that axis? A null request does not filter (reaches every
* page); an unscoped page (null value) is shared and always reachable; a
* scoped page is reachable only by its own scope. Mirrors the owner-axis
* opt-in isolation so a request that scopes nothing is byte-identical.
*/
export function scopeAxisReachable(pageValue: string | null, requested: string | null): boolean {
if (requested === null) return true;
if (pageValue === null) return true;
return pageValue === requested;
}
// ----- Source identity for federated RRF / dedup (t_09b7ccea) --------------
/** The identity of a single retrieved result across federated origins. */
export interface ResultIdentity {
/** Origin label (cross-vault), or null for the single active vault. */
readonly origin: string | null;
/** Vault-relative path of the source document. */
readonly path: string;
/** Chunk id within its origin's index. */
readonly chunkId: number;
}
/**
* Canonical RRF/dedup key carrying source identity. Two results with the
* same chunk id from different origins map to distinct keys, so federated
* fusion never collapses them; the same origin + chunk id is one identity.
*/
export function rrfKey(id: ResultIdentity): string {
return `${id.origin ?? ""}\0${id.path}\0${id.chunkId}`;
}
/**
* Order-independent, duplicate-collapsing key for the SET of origins a
* federated query drew from. The query cache scopes by this so a cache row
* computed over one origin set is never served for a different set.
*/
export function canonicalSourceSetKey(origins: ReadonlyArray<string | null>): string {
const unique = [...new Set(origins.map((o) => o ?? ""))].toSorted((a, b) =>
a < b ? -1 : a > b ? 1 : 0,
);
return unique.join("\0");
}