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 topic heads of the session start digest (task 4.2, design D10
* `head_select`): the active topics of the session's project scope, one
* line each, cut whole. Pure: no store, no model, no vault - the hook
* glue (`hooks/lib/agent-context-blocks.ts`) reads and decides, this
* module selects, orders, renders and cuts.
*
* Which topics (design D20): scope `project:<P>`, statuses active,
* waiting and blocked, not merged. Personal topics are never injected at
* session start; with no project no topic block is emitted at all.
*/
import { scopedRuleKey } from "../brain/scoped-rules.ts";
import { TOPIC_PROJECT_SCOPE_PREFIX } from "../topics/constants.ts";
import type { TopicFold, TopicState } from "../topics/fold.ts";
import { fenceUntrustedContent, neutralizeSingleLine } from "../brain/untrusted-source.ts";
/** The statuses whose topics are live work an agent should know about. */
export const HEAD_TOPIC_STATUSES = Object.freeze(["active", "waiting", "blocked"] as const);
/** Most characters one head line may carry before it is cut. */
export const HEAD_LINE_MAX_CHARS = 300;
/** Most characters a goal may carry inside a head line. */
export const HEAD_GOAL_MAX_CHARS = 160;
/**
* Whether a topic scope names this session's project (section 3.7 item
* 2): the topic's scope key was slug-normalised when the record was
* written (`scopeFromFrontmatter`), the session's project is the
* scoped-rule key of the workspace directory. Both sides go through one
* normalisation here, so the two rules cannot drift apart.
*/
export function topicScopeMatchesProject(scope: string, project: string): boolean {
if (!scope.startsWith(TOPIC_PROJECT_SCOPE_PREFIX)) return false;
const segment = scope.slice(TOPIC_PROJECT_SCOPE_PREFIX.length);
const left = scopedRuleKey(segment);
const right = scopedRuleKey(project);
return left !== null && left === right;
}
/** The topic heads eligible for the digest, in the deterministic order. */
export function candidateTopicHeads(fold: TopicFold, project: string): TopicState[] {
return [...fold.topics.values()]
.filter(
(topic) =>
topic.mergedInto === null &&
topicScopeMatchesProject(topic.scope, project) &&
(HEAD_TOPIC_STATUSES as ReadonlyArray<string>).includes(topic.status),
)
.toSorted((a, b) => b.updatedAt - a.updatedAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
}
/** One head line, its parts neutralised and cut (task 4.2 item 5). */
export function renderHeadLine(topic: TopicState): string {
const status = `[${topic.status}]`;
const parts = [`- ${neutralizeSingleLine(topic.title)} ${status} (${topic.id})`];
const description = topic.description === null ? "" : neutralizeSingleLine(topic.description);
if (description !== "") parts.push(`: ${description}`);
let line = parts.join("");
line = line.endsWith(".") || line.endsWith(")") ? line : `${line}.`;
if (topic.goal !== null && topic.goal !== "") {
const goal = neutralizeSingleLine(topic.goal);
const cut =
[...goal].length > HEAD_GOAL_MAX_CHARS
? `${[...goal].slice(0, HEAD_GOAL_MAX_CHARS - 3).join("")}...`
: goal;
line = `${line} Goal: ${cut}`;
}
return [...line].length > HEAD_LINE_MAX_CHARS
? `${[...line].slice(0, HEAD_LINE_MAX_CHARS - 3).join("")}...`
: line;
}
export interface HeadsBlock {
/** The fenced block (heading, head lines, cut line), "" when not even one head fits. */
readonly text: string;
/** How many candidate topics are not shown, whatever the reason. */
readonly dropped: number;
/** The heads shown, in the order they appear (the decision use reorders them). */
readonly shown: ReadonlyArray<TopicState>;
}
export const TOPIC_HEADS_HEADING = "## Topics in this project";
/** The untrusted-fence origin of the heads block: agents wrote the topic text. */
export const TOPIC_HEADS_ORIGIN = "topic-heads";
/**
* Select, order, render and cut the head lines (task 4.2 item 6). Heads
* are cut whole, lowest-ranked first, never mid-line; the dropped count
* is the number of candidate topics not shown, whatever the reason
* (count cap, character cap, or a `head_select` drop - pass that order
* in as `ordered`). The whole fenced block - heading, fence and cut line
* included - fits `maxChars`. A block always shows at least one head:
* when not even one fits beside the cut line, the short cut line is
* tried, and when none fits beside that either there is no block.
*/
export function buildHeadsBlock(input: {
readonly heads: ReadonlyArray<TopicState>;
readonly max: number;
readonly maxChars: number;
readonly cutLine: (dropped: number) => string;
/** The cut line without its pointers, for a block too small for the full one. */
readonly shortCutLine?: (dropped: number) => string;
}): HeadsBlock {
const all = [...input.heads];
const lines = all.slice(0, Math.max(0, input.max)).map(renderHeadLine);
const render = (n: number, cutLine: (dropped: number) => string): string => {
const cut = cutLine(all.length - n);
const body = [TOPIC_HEADS_HEADING, "", ...lines.slice(0, n), ...(cut !== "" ? ["", cut] : [])];
return fenceUntrustedContent(body.join("\n"), TOPIC_HEADS_ORIGIN);
};
// The most heads that fit, in rank order: the lowest-ranked go first.
for (const cutLine of [input.cutLine, ...(input.shortCutLine ? [input.shortCutLine] : [])]) {
for (let n = lines.length; n >= 1; n--) {
const text = render(n, cutLine);
if (text.length <= input.maxChars) {
return { text, dropped: all.length - n, shown: all.slice(0, n) };
}
}
}
return { text: "", dropped: all.length, shown: [] };
}