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
/**
* File-context recall (Recall & Working-Memory Quality Suite,
* t_4f420aca).
*
* Before an agent reads a file, it is useful to surface what the vault
* already knows about that file - prior decisions, bug notes, refactor
* history. This module answers that by querying the EXISTING search
* index with terms derived structurally from the file path (basename,
* stem, parent directory); no LLM, no natural-language processing. A
* file-size gate skips trivial files, mirroring the mem0 source's
* >= 1500-byte threshold, and returns an explicit reason rather than a
* fabricated empty hit.
*
* Read-only: this never writes to the vault or the index.
*/
import { statSync } from "node:fs";
import { search } from "../search/search.ts";
import type { BrainSearchResult, ResolvedSearchConfig } from "../search/types.ts";
import type { TransportReach } from "../graph/transport-reach.ts";
const DEFAULT_LIMIT = 5;
const DEFAULT_MIN_BYTES = 1500;
export interface FileContextOptions {
/** Path of the file the caller is about to read (absolute or relative). */
readonly filePath: string;
/** Maximum prior-work hits to return. Default 5. */
readonly limit?: number;
/** Skip files smaller than this many bytes. Default 1500. */
readonly minBytes?: number;
/**
* Owner-scope isolation (context-integrity-gates, Unit A). Threaded
* straight into `SearchOptions.agentScope`, so an owner-private page
* is returned only to its own scope and an ownerless page always is.
* Omitted / blank applies no ownership filtering, which keeps an
* unscoped call byte-identical.
*/
readonly agentScope?: string;
/**
* How far this caller reached, minted by the transport
* (`src/core/graph/transport-reach.ts`) and threaded straight into
* {@link SearchOptions.transportReach}, so a page reserved against
* remote reads is withheld here on exactly the same terms it is
* withheld from a direct search. Omitted resolves to the narrowest,
* which is what a lane that established nothing should get.
*/
readonly transportReach?: TransportReach;
}
export interface FileContextResult {
readonly filePath: string;
/** True when the gate (or an empty query) suppressed the search. */
readonly skipped: boolean;
/** Why the search was suppressed, or null when it ran. */
readonly reason: string | null;
/** The query terms derived from the path. */
readonly query: string;
readonly results: ReadonlyArray<BrainSearchResult>;
}
/**
* Derive search terms from a file path, structurally: the basename and
* its extensionless stem, de-duplicated and space-joined. Separator- and
* language-agnostic, no word list. The parent directory is deliberately
* excluded: keyword retrieval ANDs terms, so a directory name a note
* does not mention would suppress an otherwise-relevant hit. The
* basename is the canonical "this exact file" signal.
*/
export function deriveFileQuery(filePath: string): string {
const normalized = filePath.replaceAll("\\", "/").normalize("NFC").trim();
const segments = normalized.split("/").filter((s) => s.length > 0);
if (segments.length === 0) return "";
const base = segments[segments.length - 1]!;
const dot = base.lastIndexOf(".");
const stem = dot > 0 ? base.slice(0, dot) : base;
const unique: string[] = [];
for (const term of [base, stem]) {
if (term.length > 0 && !unique.includes(term)) unique.push(term);
}
return unique.join(" ");
}
/**
* Surface prior vault work that mentions `filePath`. Returns an explicit
* skip (with a reason) when the file is below the size gate or the path
* yields no query terms; otherwise runs a read-only search and returns
* its hits.
*/
export async function fileContextRecall(
config: ResolvedSearchConfig,
opts: FileContextOptions,
): Promise<FileContextResult> {
const limit = Math.max(1, Math.min(100, opts.limit ?? DEFAULT_LIMIT));
const minBytes = Math.max(0, opts.minBytes ?? DEFAULT_MIN_BYTES);
const query = deriveFileQuery(opts.filePath);
if (query.length === 0) {
return frozenResult(opts.filePath, true, "no_query_terms", query, []);
}
// Size gate: skip trivial files. Only applies when the file exists and
// can be measured; a missing path (e.g. an external reference) still
// searches, since the query is the path itself.
const size = fileSize(opts.filePath);
if (size !== null && size < minBytes) {
return frozenResult(opts.filePath, true, "below_size_gate", query, []);
}
const outcome = await search(config, {
query,
limit,
...(opts.agentScope !== undefined ? { agentScope: opts.agentScope } : {}),
...(opts.transportReach !== undefined ? { transportReach: opts.transportReach } : {}),
});
return frozenResult(opts.filePath, false, null, query, outcome.results);
}
function fileSize(filePath: string): number | null {
try {
const stat = statSync(filePath);
return stat.isFile() ? stat.size : null;
} catch {
return null;
}
}
function frozenResult(
filePath: string,
skipped: boolean,
reason: string | null,
query: string,
results: ReadonlyArray<BrainSearchResult>,
): FileContextResult {
return Object.freeze({
filePath,
skipped,
reason,
query,
results: Object.freeze([...results]),
});
}