Skip to content

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
14.7 KB
Raw Blame
/**
 * Topic pages of the human view (design D7, D8; spec `topics` "Topic
 * page"; task 3.2): one folder per topic, `topics/<YYYY-MM-DD>-<slug>/`,
 * holding `topic.md` and, when the page budget overflows or questions are
 * resolved, the companion `archive.md`. Pure: the pages are a function of
 * the topic fold (`../topics/fold.ts`) and the view language.
 *
 * `topic.md`, in a fixed section order: the title, the one-line
 * description, the status line, the goal, milestones, decisions, open
 * questions, the log (newest first) and the related section. The goal,
 * milestones, decisions, open questions and log are left out when empty;
 * the title, description, status and related section are always there
 * (related names at least the topic's scope).
 *
 *  - Milestones: open ones in the order they were recorded, then done
 *    ones, newest done first. A completion proposed without standing (a
 *    decision model, an agent with no evidence) shows as "looks done,
 *    confirm" and the milestone stays open.
 *  - Decisions: newest first, each with the milestones it serves.
 *  - Open questions: unresolved questions, then the goal proposals that
 *    lost to the user's goal, attributed to their agent.
 *  - Log: earned entries only (`TOPIC_EARNED_LOG_CLASSES`), newest first.
 *  - Related: the scope, linked topics as relative links, topics merged
 *    into this one, and the archive link.
 *
 * Page budget (`TOPIC_PAGE_BUDGET`): the oldest done milestones, decisions
 * and log entries over their section's budget move to `archive.md`, with
 * the resolved questions. Open milestones and open questions never move.
 *
 * The folder is the UTC day of the topic's creation and a slug of its
 * current title, so a rename moves the page (the renderer retires the old
 * folder). Two topics that take the same folder are told apart by the
 * tail of their id. Every line carries a key `t:<topic id>:...` naming
 * what it shows, so an edit maps back to a topic record (`topic-edits.ts`).
 */

import { compareCodeUnits } from "../store/compare.ts";
import {
  TOPIC_EARNED_LOG_CLASSES,
  TOPIC_PAGE_BUDGET,
  TOPIC_PERSONAL_SCOPE,
  TOPIC_PROJECT_SCOPE_PREFIX,
} from "../topics/constants.ts";
import type { TopicFold, TopicItem, TopicState } from "../topics/fold.ts";
import { VIEW_TOPIC_ARCHIVE_PAGE, VIEW_TOPIC_PAGE, VIEW_TOPICS_DIR } from "./constants.ts";
import type { EarnedLogClass, ViewStrings } from "./i18n.ts";
import { ID_LINE_KEY, plainText, type PageLine, type PageModel } from "./pages.ts";

/** Longest slug of a topic folder, in code points. */
const SLUG_MAX = 48;

const BLANK: PageLine = { key: null, text: "" };

/** The slug of a title: lowercase letters and digits of any script, joined by hyphens. */
export function topicSlug(title: string): string {
  const words = title
    .normalize("NFC")
    .toLowerCase()
    .split(/[^\p{L}\p{N}]+/u)
    .filter(Boolean);
  const slug = [...words.join("-")].slice(0, SLUG_MAX).join("").replace(/-+$/, "");
  return slug === "" ? "topic" : slug;
}

function dayOf(ms: number): string {
  return new Date(ms).toISOString().slice(0, 10);
}

/** What a render may show beyond the view's own rule. */
export interface TopicPageOptions {
  /**
   * Show private topics and items too: for a local caller's read of one
   * topic (the topic tool, `osb://topic/{id}`), never for the view.
   */
  readonly includePrivate?: boolean;
}

/** The topics a page is rendered for: existing, not merged away, not private. */
export function renderedTopics(fold: TopicFold, options: TopicPageOptions = {}): TopicState[] {
  return [...fold.topics.values()]
    .filter((t) => t.mergedInto === null && (options.includePrivate === true || !t.private))
    .toSorted((a, b) => a.createdAt - b.createdAt || compareCodeUnits(a.id, b.id));
}

/** The view folder of each rendered topic, relative to the view: `topics/<day>-<slug>`. */
export function topicFolders(fold: TopicFold, options: TopicPageOptions = {}): Map<string, string> {
  const out = new Map<string, string>();
  const taken = new Set<string>();
  for (const topic of renderedTopics(fold, options)) {
    const base = `${VIEW_TOPICS_DIR}/${dayOf(topic.createdAt)}-${topicSlug(topic.title)}`;
    // The base, else the base and the tail of the id, else a counter on
    // that: a folder another topic holds (a title that already ends in such
    // a tail) is never shared.
    let folder = taken.has(base) ? `${base}-${topic.id.slice(-6).toLowerCase()}` : base;
    for (let n = 2; taken.has(folder); n++)
      folder = `${base}-${topic.id.slice(-6).toLowerCase()}-${n}`;
    taken.add(folder);
    out.set(topic.id, folder);
  }
  return out;
}

/** The id comment line of a topic page: the store, the page and the topic. */
function topicIdLine(storeId: string, page: string, topic: string): PageLine {
  return {
    key: ID_LINE_KEY,
    text: `<!-- open-second-brain-view store=${storeId} page=${page} topic=${topic} -->`,
  };
}

/** The topic id an id comment line names, or `null`. */
export function topicOfIdLine(line: string): string | null {
  const match = /^<!-- open-second-brain-view .*\btopic=([0-9A-HJKMNP-TV-Z]{26})\b/.exec(line);
  return match === null ? null : match[1]!;
}

interface Sections {
  readonly milestonesOpen: TopicItem[];
  readonly milestonesDone: TopicItem[];
  readonly milestonesArchived: TopicItem[];
  readonly decisions: TopicItem[];
  readonly decisionsArchived: TopicItem[];
  readonly questions: TopicItem[];
  readonly resolved: TopicItem[];
  readonly log: TopicItem[];
  readonly logArchived: TopicItem[];
}

const newestFirst = (a: TopicItem, b: TopicItem): number => b.createdAt - a.createdAt;

function sections(topic: TopicState, includePrivate: boolean): Sections {
  const shown = topic.items.filter((i) => includePrivate || !i.private);
  const milestones = shown.filter((i) => i.kind === "milestone");
  const done = milestones
    .filter((i) => i.done !== undefined)
    .toSorted((a, b) => b.done!.at - a.done!.at);
  const decisions = shown
    .filter((i) => i.kind === "decision")
    .toReversed()
    .toSorted(newestFirst);
  const questions = shown.filter((i) => i.kind === "open-question");
  const log = shown
    .filter((i) => i.kind === "log-entry" && TOPIC_EARNED_LOG_CLASSES.has(i.logClass!))
    .toReversed()
    .toSorted(newestFirst);
  return {
    milestonesOpen: milestones.filter((i) => i.done === undefined),
    milestonesDone: done.slice(0, TOPIC_PAGE_BUDGET.doneMilestones),
    milestonesArchived: done.slice(TOPIC_PAGE_BUDGET.doneMilestones),
    decisions: decisions.slice(0, TOPIC_PAGE_BUDGET.decisions),
    decisionsArchived: decisions.slice(TOPIC_PAGE_BUDGET.decisions),
    questions: questions.filter((i) => i.resolved === undefined),
    resolved: questions
      .filter((i) => i.resolved !== undefined)
      .toSorted((a, b) => b.resolved!.at - a.resolved!.at),
    log: log.slice(0, TOPIC_PAGE_BUDGET.log),
    logArchived: log.slice(TOPIC_PAGE_BUDGET.log),
  };
}

function hasArchive(s: Sections): boolean {
  return (
    s.milestonesArchived.length +
      s.decisionsArchived.length +
      s.resolved.length +
      s.logArchived.length >
    0
  );
}

interface LineContext {
  readonly includePrivate: boolean;
  readonly topic: TopicState;
  readonly strings: ViewStrings;
  readonly key: (rest: string) => string;
}

/**
 * The key of an item line: under the topic that owns the item, not the
 * page's topic, since an item id is its owner's own and a merged topic's
 * items show on the page it merged into (an edit lands on the owner).
 */
function itemKey(item: TopicItem, rest: string): string {
  return `t:${item.owner}:${rest}`;
}

function milestoneLine(c: LineContext, item: TopicItem): PageLine {
  const text = plainText(item.text);
  const line =
    item.done !== undefined
      ? `- [x] ${text} (${c.strings.milestoneDone(dayOf(item.done.at))})`
      : item.doneProposed !== undefined
        ? `- [ ] ${text} (${c.strings.milestoneLooksDone})`
        : `- [ ] ${text}`;
  // A done milestone's key names the record that completed it, so
  // unticking the line can undo exactly that record.
  const key = item.done !== undefined ? `mx:${item.done.record}:${item.id}` : `m:${item.id}`;
  return { key: itemKey(item, key), text: line };
}

function decisionLine(c: LineContext, item: TopicItem): PageLine {
  const served = (item.serves ?? []).flatMap((id) => {
    const milestone = c.topic.items.find(
      (i) => i.id === id && i.kind === "milestone" && !i.private,
    );
    return milestone === undefined ? [] : [plainText(milestone.text)];
  });
  const serves = served.length > 0 ? ` (${c.strings.serves(served.join("; "))})` : "";
  return { key: itemKey(item, `d:${item.id}`), text: `- ${plainText(item.text)}${serves}` };
}

function questionLine(c: LineContext, item: TopicItem): PageLine {
  const text = plainText(item.text);
  if (item.resolved !== undefined) {
    const answer = item.resolved.answer;
    const tail = answer === null ? "" : ` (${c.strings.questionAnswer(plainText(answer))})`;
    return { key: itemKey(item, `q:${item.id}`), text: `- ${text}${tail}` };
  }
  const tail = item.resolveProposed !== undefined ? ` (${c.strings.questionLooksAnswered})` : "";
  return { key: itemKey(item, `q:${item.id}`), text: `- ${text}${tail}` };
}

function logLine(c: LineContext, item: TopicItem): PageLine {
  const cls = item.logClass as EarnedLogClass;
  const reason = item.reason !== undefined ? `, ${c.strings.because(plainText(item.reason))}` : "";
  return {
    key: itemKey(item, `l:${cls}:${item.id}`),
    text: `- ${dayOf(item.createdAt)}, ${c.strings.logClass[cls]}: ${plainText(item.text)}${reason}`,
  };
}

function section(
  lines: PageLine[],
  key: string,
  heading: string,
  body: ReadonlyArray<PageLine>,
): void {
  if (body.length === 0) return;
  lines.push(BLANK, { key, text: `## ${heading}` }, BLANK, ...body);
}

function relatedLines(
  c: LineContext,
  fold: TopicFold,
  folders: ReadonlyMap<string, string>,
  archive: boolean,
): PageLine[] {
  const { topic, strings } = c;
  const scope =
    topic.scope === TOPIC_PERSONAL_SCOPE
      ? strings.scopePersonal
      : strings.scopeProject(plainText(topic.scope.slice(TOPIC_PROJECT_SCOPE_PREFIX.length)));
  const out: PageLine[] = [{ key: c.key("scope"), text: `- ${scope}` }];
  const linked = new Set(topic.links.map((id) => fold.canonical(id)).filter((id) => id !== null));
  linked.delete(topic.id);
  for (const id of [...linked].toSorted()) {
    const folder = folders.get(id!);
    const other = fold.topics.get(id!);
    if (folder === undefined || other === undefined) continue;
    out.push({
      key: c.key(`link:${id}`),
      text: `- [${plainText(other.title)}](../${folder.split("/").at(-1)}/${VIEW_TOPIC_PAGE})`,
    });
  }
  for (const merged of [...fold.topics.values()]
    .filter((t) => t.mergedInto === topic.id && (c.includePrivate || !t.private))
    .toSorted((a, b) => compareCodeUnits(a.id, b.id))) {
    out.push({
      key: c.key(`merged:${merged.id}`),
      text: `- ${strings.mergedFrom(plainText(merged.title))}`,
    });
  }
  if (archive) {
    out.push({
      key: c.key("archive"),
      text: `- [${strings.archiveLink}](${VIEW_TOPIC_ARCHIVE_PAGE})`,
    });
  }
  return out;
}

function topicPage(
  storeId: string,
  fold: TopicFold,
  topic: TopicState,
  folders: ReadonlyMap<string, string>,
  strings: ViewStrings,
  includePrivate: boolean,
): PageModel[] {
  const folder = folders.get(topic.id)!;
  const page = `${folder}/${VIEW_TOPIC_PAGE}`;
  const c: LineContext = { includePrivate, topic, strings, key: (rest) => `t:${topic.id}:${rest}` };
  const s = sections(topic, includePrivate);
  const archive = hasArchive(s);
  const lines: PageLine[] = [topicIdLine(storeId, page, topic.id), BLANK];
  lines.push({ key: c.key("title"), text: `# ${plainText(topic.title)}` }, BLANK);
  const description = topic.description === null ? "" : plainText(topic.description);
  lines.push({
    key: c.key("desc"),
    text: description === "" ? strings.topicNoDescription : description,
  });
  lines.push(BLANK, {
    key: c.key("status"),
    text: strings.statusLine(
      strings.topicStatus[topic.status],
      topic.status === "done" ? topic.resolved : null,
    ),
  });
  const goal = topic.goal === null ? "" : plainText(topic.goal);
  section(
    lines,
    c.key("h:goal"),
    strings.topicGoal,
    goal === "" ? [] : [{ key: c.key("goal"), text: goal }],
  );
  section(lines, c.key("h:milestones"), strings.topicMilestones, [
    ...s.milestonesOpen.map((i) => milestoneLine(c, i)),
    ...s.milestonesDone.map((i) => milestoneLine(c, i)),
  ]);
  section(
    lines,
    c.key("h:decisions"),
    strings.topicDecisions,
    s.decisions.map((i) => decisionLine(c, i)),
  );
  section(lines, c.key("h:questions"), strings.topicQuestions, [
    ...s.questions.map((i) => questionLine(c, i)),
    ...topic.goalProposals.map((p) => ({
      key: c.key(`gp:${p.record}`),
      text: `- ${strings.goalProposal(plainText(p.agent), plainText(p.goal))}`,
    })),
  ]);
  section(
    lines,
    c.key("h:log"),
    strings.topicLog,
    s.log.map((i) => logLine(c, i)),
  );
  section(lines, c.key("h:related"), strings.topicRelated, relatedLines(c, fold, folders, archive));
  const pages: PageModel[] = [{ page, lines, topic: topic.id }];
  if (archive) pages.push(archivePage(storeId, folder, c, s));
  return pages;
}

function archivePage(storeId: string, folder: string, c: LineContext, s: Sections): PageModel {
  const page = `${folder}/${VIEW_TOPIC_ARCHIVE_PAGE}`;
  const { strings, topic } = c;
  const lines: PageLine[] = [topicIdLine(storeId, page, topic.id), BLANK];
  lines.push({ key: c.key("a:title"), text: `# ${strings.archiveTitle(plainText(topic.title))}` });
  lines.push(BLANK, { key: c.key("a:intro"), text: strings.archiveIntro });
  lines.push(BLANK, { key: c.key("a:back"), text: `[${strings.archiveBack}](${VIEW_TOPIC_PAGE})` });
  section(
    lines,
    c.key("a:h:milestones"),
    strings.topicMilestones,
    s.milestonesArchived.map((i) => milestoneLine(c, i)),
  );
  section(
    lines,
    c.key("a:h:decisions"),
    strings.topicDecisions,
    s.decisionsArchived.map((i) => decisionLine(c, i)),
  );
  section(
    lines,
    c.key("a:h:resolved"),
    strings.topicResolvedQuestions,
    s.resolved.map((i) => questionLine(c, i)),
  );
  section(
    lines,
    c.key("a:h:log"),
    strings.topicLog,
    s.logArchived.map((i) => logLine(c, i)),
  );
  return { page, lines, topic: topic.id };
}

/** Every topic page and archive the fold renders to. */
export function topicPages(
  storeId: string,
  fold: TopicFold,
  strings: ViewStrings,
  options: TopicPageOptions = {},
): PageModel[] {
  const folders = topicFolders(fold, options);
  const includePrivate = options.includePrivate === true;
  return renderedTopics(fold, options).flatMap((topic) =>
    topicPage(storeId, fold, topic, folders, strings, includePrivate),
  );
}