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
/**
* Progressive disclosure (D1-D3): project a ranked result into a
* token-cheap layer-1 card, and expand a card the agent already holds
* into its fuller note (layer 2) and paginated raw chunks (layer 3).
*/
import { normalizeAgentScope } from "../graph/agent-scope.ts";
import { formatLinePointer } from "./line-numbering.ts";
import { isPathOwnerVisible, isPathReadableAtReach } from "./result-filters.ts";
import { resolvedTransportReach, type TransportReach } from "../graph/transport-reach.ts";
import { markWindow, matchOffset, toCodePointOffset, windowStartWithin } from "./snippet-window.ts";
import { Store } from "./store.ts";
import { SearchError } from "./types.ts";
import type {
BrainSearchResult,
ExpandHitInput,
ExpandHitResult,
ResolvedSearchConfig,
SearchCard,
} from "./types.ts";
/** Max chars of a layer-1 card snippet β enough to judge a hit, cheap to carry. */
const CARD_SNIPPET_CHARS = 240;
/**
* Continuation marker for a card snippet that does not cover the whole
* chunk. Three ASCII dots, not U+2026: the card grammar has shipped this
* spelling since progressive disclosure landed, and the other preview
* surfaces use the single-character form.
*/
const CARD_ELLIPSIS = "...";
/** Default layer-3 raw-chunk page size for `expandHit`. */
const DEFAULT_EXPAND_RAW_LIMIT = 10;
/**
* The merged-away duplicate locations, as `path:Lstart-Lend` pointers.
*
* A card carries POINTERS rather than the full location records the
* ranked row holds: the folded passage is byte-identical to the surviving
* one by construction, so a caller never needs to expand a copy - it needs
* to know where else the same bytes live, which is exactly what the card's
* own `pointer` grammar says. That keeps the token-cheap layer cheap and
* reuses the rendering the full transcript already uses.
*/
function duplicatePointers(result: BrainSearchResult): ReadonlyArray<string> {
return Object.freeze(
(result.duplicates ?? []).map((d) => formatLinePointer(d.path, d.startLine, d.endLine)),
);
}
/**
* Project a ranked result into a layer-1 card (progressive disclosure):
* identity + score + the same `reasons`, a whitespace-collapsed snippet
* capped at {@link CARD_SNIPPET_CHARS} and anchored on the query match,
* and a `path:Lstart-Lend` pointer (D2 grammar) over the chunk's stored
* line span. No full content.
*
* `query` is the residual query text the row was retrieved for; it
* decides where the snippet window opens. It is required rather than
* optional because a card whose snippet silently reverted to the head of
* the chunk is the defect this signature exists to prevent.
*/
export function toSearchCard(result: BrainSearchResult, query: string): SearchCard {
return Object.freeze({
chunkId: result.chunkId,
documentId: result.documentId,
path: result.path,
title: result.title,
score: result.score,
reasons: result.reasons,
snippet: cardSnippet(result.content, query),
pointer: formatLinePointer(result.path, result.startLine, result.endLine),
...(result.origin !== undefined ? { origin: result.origin } : {}),
// Exact-duplicate merge (task D): the locations this row was folded
// from, so cards mode reports them instead of silently dropping a
// value the pipeline already computed. Absent, never null and never
// empty, when nothing was merged.
...(result.duplicates !== undefined && result.duplicates.length > 0
? { duplicatePointers: duplicatePointers(result) }
: {}),
});
}
/**
* The card snippet: whitespace-collapsed content, windowed on the first
* significant `query` term it contains, capped at
* {@link CARD_SNIPPET_CHARS} code points.
*
* `query` defaults to the empty string, which has no significant terms
* and is therefore the defined no-match case β the head of the chunk,
* byte-identical to the pre-anchoring snippet. That default exists for
* callers that hold content without a query at all; the ranked path
* always passes one through {@link toSearchCard}.
*
* The cap bounds the BODY; each {@link CARD_ELLIPSIS} sits outside it, so
* a window cut at both ends reaches `CARD_SNIPPET_CHARS + 2 *
* CARD_ELLIPSIS.length` code points. Shrinking the body to hold a fixed
* total would make an anchored card show LESS evidence than a
* head-anchored one, which is the opposite of what anchoring is for; the
* markers are continuation decoration, not content.
*/
export function cardSnippet(content: string, query = ""): string {
const collapsed = content.replace(/\s+/g, " ").trim();
// Window and truncate on code points, not UTF-16 units: a raw `.slice`
// can cut an astral character (emoji, rare CJK) mid-surrogate-pair,
// shipping a lone surrogate that renders as U+FFFD. Spreading into an
// array iterates by code point, so neither edge splits a character β
// and an index into that array is always a code-point boundary, which
// is why this surface needs no start alignment.
const points = [...collapsed];
const start = windowStartWithin(
toCodePointOffset(collapsed, matchOffset(collapsed, query)),
CARD_SNIPPET_CHARS,
points.length,
);
const end = start + CARD_SNIPPET_CHARS;
return markWindow(points.slice(start, end).join(""), start, end < points.length, CARD_ELLIPSIS);
}
/**
* Progressive disclosure (D3): layers 2 and 3 of a hit the agent already
* holds as a layer-1 card. Given the card's `chunkId`, reconstruct the
* fuller note (layer 2) from the document's stored chunks and return a
* paginated slice of those raw chunks (layer 3), mirroring
* `expandSessionRecall`'s cursor contract.
*
* Read-only by construction: it opens the index in read mode and never
* self-heals β a card can only exist because a prior search built the
* index, and a rebuild would WRITE it. The layer-2/3 data is pure store
* reads (`hydrateChunks` + `getChunksByDocument`), never a new index.
*
* ## Ownership (context-integrity-gates, Unit A)
*
* `chunkId` is a SEQUENTIAL INTEGER, so without a check this is an
* enumeration surface for whole note bodies: walking the integers
* returns every document in the vault, ranking and query filters
* bypassed entirely. Under an `agentScope` the resolved path's owner is
* checked with the same {@link isPathOwnerVisible} rule the ranked filter
* uses, and a refusal is {@link notFound} β byte-for-byte the error an
* absent chunk produces. A distinguishable refusal would still leak: it
* would confirm that the chunk exists and belongs to someone else,
* which is exactly what enumeration is looking for.
*
* An omitted or blank scope filters nothing, so an unscoped call is
* byte-identical.
*/
export async function expandHit(
config: ResolvedSearchConfig,
input: ExpandHitInput,
): Promise<ExpandHitResult> {
if (!Number.isInteger(input.chunkId) || input.chunkId < 1) {
throw new SearchError("INVALID_INPUT", "chunkId must be a positive integer");
}
const agentScope = normalizeAgentScope(input.agentScope);
const reach = resolvedTransportReach(input.transportReach);
const store = await Store.open(config, { mode: "read" });
try {
const hit = store.hydrateChunks([input.chunkId]).get(input.chunkId);
if (hit === undefined) {
throw notFound(input.chunkId);
}
if (agentScope !== null && !ownerVisible(config, hit.path, agentScope)) {
throw notFound(input.chunkId);
}
if (!reachReadable(config, store, hit.path, reach)) {
throw notFound(input.chunkId);
}
// Document chunks in `chunkIndex` order: the fuller note (layer 2) is
// their concatenation; the raw transcript (layer 3) is the same rows.
const chunks = store.getChunksByDocument(hit.documentId);
const lineStart = chunks.length > 0 ? chunks[0]!.startLine : hit.startLine;
const lineEnd = chunks.length > 0 ? chunks[chunks.length - 1]!.endLine : hit.endLine;
const note = Object.freeze({
documentId: hit.documentId,
path: hit.path,
title: hit.title,
lineStart,
lineEnd,
pointer: formatLinePointer(hit.path, lineStart, lineEnd),
content: chunks.map((c) => c.content).join("\n"),
});
const offset = Math.max(0, Number.parseInt(input.cursor ?? "0", 10) || 0);
const rawLimit = Math.max(1, input.rawLimit ?? DEFAULT_EXPAND_RAW_LIMIT);
const page = chunks.slice(offset, offset + rawLimit).map((c) =>
Object.freeze({
chunkId: c.id,
chunkIndex: c.chunkIndex,
startLine: c.startLine,
endLine: c.endLine,
pointer: formatLinePointer(hit.path, c.startLine, c.endLine),
content: c.content,
}),
);
const nextOffset = offset + rawLimit;
return Object.freeze({
chunkId: input.chunkId,
note,
raw_content: Object.freeze(page),
next_cursor: nextOffset < chunks.length ? String(nextOffset) : null,
});
} finally {
await store.close();
}
}
/**
* The single construction of the drill-down's not-found error. Both the
* absent-chunk branch and the ownership refusal call it, so the two
* cannot drift into distinguishable messages.
*/
function notFound(chunkId: number): SearchError {
return new SearchError("INVALID_INPUT", `chunk not found: ${chunkId}`);
}
/**
* May a caller at `reach` read the note at `path`? Fails CLOSED on an
* unreadable page, exactly as the ranked filter decides it.
*
* Delegates to {@link isPathReadableAtReach} rather than restating the
* rule, so the drill-down and the ranked pipeline cannot drift on what
* "reserved" means. Unlike the ownership check above, this one is asked
* on EVERY call rather than only when the caller supplied an argument -
* the reach is never a caller argument, and a boundary a caller opts into
* is not a boundary.
*
* The drill-down serves the INDEXED chunks, so what the index measured of
* the page's visibility is honoured beside the file's - see
* {@link isPathReadableAtReach}.
*/
function reachReadable(
config: ResolvedSearchConfig,
store: Store,
path: string,
reach: TransportReach,
): boolean {
const indexed = store.indexedVisibilityByPaths([path]).get(path);
return isPathReadableAtReach(config.vault, path, reach, new Map(), indexed);
}
/**
* Is the note at `path` reachable under `scope`? Fails CLOSED on an
* unreadable page, matching `applyAgentScope` on the ranked path: an
* owner that cannot be determined is treated as somebody else's rather
* than as shared.
*
* Delegates to {@link isPathOwnerVisible} rather than restating the rule,
* so the drill-down and the ranked filter cannot drift on what "closed"
* means β including the unreadable-file verdict, which an empty
* frontmatter map cannot express.
*/
function ownerVisible(config: ResolvedSearchConfig, path: string, scope: string): boolean {
// One hit, so the cache is a formality β it exists because the shared
// reader takes one, and reusing it keeps this check on exactly the
// same parse semantics as the ranked filter.
return isPathOwnerVisible(config.vault, path, scope, new Map());
}