om-memory-system 5.2.0 → 5.4.0

package/dist/core/recall-summary.d.ts

@@ -0,0 +1,32 @@
+/** One memory a recall injected, reduced to what a fold row shows. A restored memory has no relevance. */
+export type RecallItem = {
+    relevance: number | null;
+    id?: string;
+    headline: string;
+};
+/**
+ * One recall as OMMS made it: a prompt search, the opening search with the configured query, a
+ * restored session after compaction or resume, or the recent memories a session opens with.
+ */
+export type RecallSummary = {
+    mode: "search" | "recent" | "opening" | "restore";
+    query: string | null;
+    items: RecallItem[];
+    /** Per-session counter the v2 reporter sets when it stores the summary; the TUI keys rows by it. */
+    seq?: number;
+};
+/** Query on one line, cut to `max` characters. */
+export declare function queryLine(query: string, max?: number): string;
+/** One line that names a memory: the first line under `## Request`, else the first line. */
+export declare function headline(body: string): string;
+/**
+ * Summarise a formatted retrieval section for a host to show. Returns null when the section holds
+ * no memory (a profile-only section included), so the host draws nothing. A `restore` summary
+ * reads the restored-session entries, with no relevance. A `restore` or `recent` recall has no
+ * query, whatever the caller passes.
+ */
+export declare function buildRecallSummary(section: string, mode: RecallSummary["mode"], query: string | null): RecallSummary | null;
+/** `memory [mode=search, query="...", limit=4]`: the call's name and arguments, as a tool row shows them. */
+export declare function callTitle(summary: RecallSummary): string;
+/** Body of an unfolded row, one string per line, without indentation (the host indents). */
+export declare function unfoldLines(summary: RecallSummary): string[];

package/dist/core/recall-summary.js

@@ -0,0 +1,77 @@
+const QUERY_CUT = 60;
+const UNFOLDED_QUERY_CUT = 300;
+const HEADLINE_CUT = 140;
+/** Query on one line, cut to `max` characters. */
+export function queryLine(query, max = QUERY_CUT) {
+    const line = query.replace(/\s+/g, " ").trim();
+    return line.length > max ? `${line.slice(0, max - 3)}...` : line;
+}
+// Entry shape comes from `formatContextForPrompt`: `<memory id="..." relevance="N%">`, with the
+// id missing when the result had none. A body ends at its own `</memory>` when another entry, a
+// section close or the end of the text follows it. The Claude Code hook can cut a block short and
+// leave tags open, so a body also ends at a section close or at the end of the text. An opening
+// tag inside the text, even at the start of a line, does not end it: a memory can quote the tag.
+const SECTION_CLOSE = String.raw `<\/project_knowledge>|<\/memory_context>|<\/omms-retrieval>`;
+const MEMORY_ENTRY = new RegExp(String.raw `<memory(?:\s+id="([^"]*)")?\s+relevance="(\d+)%">([\s\S]*?)` +
+    String.raw `(?=<\/memory>\s*(?:<memory\s|${SECTION_CLOSE}|$)|${SECTION_CLOSE}|$)`, "g");
+// A restored-session section from `formatMemoriesForCompaction`: `### Memory N (id)`, no relevance.
+// Same rule as the Claude Code parser (`hooks/omms-recall-parse.js`).
+const RESTORED_ENTRY = /### Memory \d+(?: \(([^)\n]+)\))?\n([\s\S]*?)(?=### Memory \d+|<\/omms-retrieval>|$)/g;
+/** One line that names a memory: the first line under `## Request`, else the first line. */
+export function headline(body) {
+    const lines = body
+        .replace(/<\/memory>\s*$/, "")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const heading = lines.findIndex((line) => /^##\s*request\s*$/i.test(line));
+    const line = (heading >= 0 ? lines[heading + 1] : lines[0]) ?? "";
+    return line.length > HEADLINE_CUT ? `${line.slice(0, HEADLINE_CUT - 3)}...` : line;
+}
+/**
+ * Summarise a formatted retrieval section for a host to show. Returns null when the section holds
+ * no memory (a profile-only section included), so the host draws nothing. A `restore` summary
+ * reads the restored-session entries, with no relevance. A `restore` or `recent` recall has no
+ * query, whatever the caller passes.
+ */
+export function buildRecallSummary(section, mode, query) {
+    const items = [];
+    const restore = mode === "restore";
+    for (const match of section.matchAll(restore ? RESTORED_ENTRY : MEMORY_ENTRY)) {
+        const text = headline((restore ? match[2] : match[3]) ?? "");
+        if (!text)
+            continue;
+        const item = { relevance: restore ? null : Number(match[2]), headline: text };
+        if (match[1])
+            item.id = match[1];
+        items.push(item);
+    }
+    if (items.length === 0)
+        return null;
+    return { mode, query: restore || mode === "recent" ? null : query, items };
+}
+/** Escape backslashes and double quotes so the quoted value in the title reads as one string. */
+function escapeQuoted(text) {
+    return text.replace(/[\\"]/g, "\\$&");
+}
+/** `memory [mode=search, query="...", limit=4]`: the call's name and arguments, as a tool row shows them. */
+export function callTitle(summary) {
+    const args = [`mode=${summary.mode}`];
+    if (summary.query)
+        args.push(`query="${escapeQuoted(queryLine(summary.query))}"`);
+    args.push(`limit=${summary.items.length}`);
+    return `memory [${args.join(", ")}]`;
+}
+/** Body of an unfolded row, one string per line, without indentation (the host indents). */
+export function unfoldLines(summary) {
+    const lines = [`mode: ${summary.mode}`];
+    if (summary.query)
+        lines.push(`query: ${queryLine(summary.query, UNFOLDED_QUERY_CUT)}`);
+    lines.push(`limit: ${summary.items.length}`);
+    summary.items.forEach((item, index) => {
+        const relevance = item.relevance === null ? "" : `${item.relevance}%`;
+        const id = item.id ? `id=${item.id}` : "";
+        lines.push(`${index + 1}. ${[relevance, id, item.headline].filter(Boolean).join(" ")}`);
+    });
+    return lines;
+}

package/dist/core/retrieval.d.ts

@@ -1,5 +1,21 @@
 import { type ContextBudgetOptions } from "./context-budget.js";
 export declare const RETRIEVAL_SECTION_TAG = "omms-retrieval";
+/**
+ * The search step of every query-driven section (`buildRetrievalSection` and
+ * the opening search in `opening-context.ts`), so they share one rule set: the
+ * store applies the result limit and the relevance threshold, then memories
+ * from the current session are dropped when `chatMessage.excludeCurrentSession`
+ * is on. Returns null when the search failed.
+ */
+export declare function searchSectionMemories(query: string, projectTag: string, sessionId: string): Promise<{
+    results: any[];
+    queryVector?: ArrayLike<number>;
+} | null>;
+/**
+ * The prompt text that may reach a search: `<private>` regions removed. Null when nothing is
+ * left, so a fully private prompt runs no search and nothing of it reaches an embedding provider.
+ */
+export declare function searchablePrompt(prompt: string): string | null;
 /**
  * Prompt-aware semantic retrieval shared by every host (Pi `before_agent_start`,
  * OpenCode v2 `prompt`/`context` hooks): search the shared project memory with

package/dist/core/retrieval.js

@@ -2,31 +2,53 @@ import { CONFIG } from "../config.js";
 import { formatContextForPrompt } from "../services/context.js";
 import { memoryClient } from "../services/client.js";
 import { getTags } from "../services/tags.js";
+import { isFullyPrivate, stripPrivateContent } from "../services/privacy.js";
 import { utf8ByteLength } from "../utils/context-limit.js";
 import { packContextSection } from "./context-budget.js";
 export const RETRIEVAL_SECTION_TAG = "omms-retrieval";
 /**
- * Prompt-aware semantic retrieval shared by every host (Pi `before_agent_start`,
- * OpenCode v2 `prompt`/`context` hooks): search the shared project memory with
- * the incoming prompt and format a bounded context section (memory + user
- * profile). Returns null when nothing relevant is found.
+ * The search step of every query-driven section (`buildRetrievalSection` and
+ * the opening search in `opening-context.ts`), so they share one rule set: the
+ * store applies the result limit and the relevance threshold, then memories
+ * from the current session are dropped when `chatMessage.excludeCurrentSession`
+ * is on. Returns null when the search failed.
  */
-export async function buildRetrievalSection(prompt, directory, sessionId, budget) {
-    if (!prompt.trim())
-        return null;
+export async function searchSectionMemories(query, projectTag, sessionId) {
     // Snapshot before the async search: an excludeCurrentSession edit during
     // the search must not change this operation's filtering.
     const excludeCurrentSession = CONFIG.chatMessage.excludeCurrentSession;
-    const tags = getTags(directory);
-    const search = await memoryClient.searchMemories(prompt, tags.project.tag);
+    const search = await memoryClient.searchMemories(query, projectTag);
     if (!search.success)
         return null;
     const results = excludeCurrentSession
         ? search.results.filter((result) => result.metadata?.sessionID !== sessionId)
         : search.results;
-    if (results.length === 0)
+    return { results, queryVector: search.queryVector };
+}
+/**
+ * The prompt text that may reach a search: `<private>` regions removed. Null when nothing is
+ * left, so a fully private prompt runs no search and nothing of it reaches an embedding provider.
+ */
+export function searchablePrompt(prompt) {
+    if (isFullyPrivate(prompt))
+        return null;
+    return stripPrivateContent(prompt).trim() || null;
+}
+/**
+ * Prompt-aware semantic retrieval shared by every host (Pi `before_agent_start`,
+ * OpenCode v2 `prompt`/`context` hooks): search the shared project memory with
+ * the incoming prompt and format a bounded context section (memory + user
+ * profile). Returns null when nothing relevant is found.
+ */
+export async function buildRetrievalSection(prompt, directory, sessionId, budget) {
+    const query = searchablePrompt(prompt);
+    if (!query)
+        return null;
+    const tags = getTags(directory);
+    const search = await searchSectionMemories(query, tags.project.tag, sessionId);
+    if (!search || search.results.length === 0)
         return null;
-    const memoryContext = await formatContextForPrompt(tags.user.userEmail || null, { results }, budget, search.queryVector);
+    const memoryContext = await formatContextForPrompt(tags.user.userEmail || null, { results: search.results }, budget, search.queryVector);
     return memoryContext || null;
 }
 /**

package/dist/importer/claude-hook-api.d.ts

@@ -15,10 +15,11 @@ export declare class ClaudeHookRequestError extends Error {
     constructor(message: string);
 }
 /**
- * `POST /api/claude/retrieve`: recent project memories for a fresh session,
- * the session's own memories after compaction or resume, or the retrieval
- * section for a prompt. Every text is wrapped in the retrieval tag; an empty
- * string means nothing to add.
+ * `POST /api/claude/retrieve`: the retrieval section for a prompt (and the
+ * opening section on a session's first prompt, when on), the memories for a
+ * starting subagent's task, or the session's own memories after compaction or
+ * resume. A fresh or cleared session adds nothing. Every text is wrapped in the
+ * retrieval tag; an empty string means nothing to add.
  */
 export declare function handleClaudeRetrieve(body: unknown, deps?: ClaudeHookDeps): Promise<{
     additionalContext: string;

package/dist/importer/claude-hook-api.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { CONFIG, refreshConfigIfChanged } from "../config.js";
 import { classifyCaptureFailure, quickRetryDelayMs } from "../core/capture-retry-policy.js";
-import { buildRecentMemoriesSection, buildRetrievalSection, formatMemoriesForCompaction, retrievalWrapperBytes, wrapRetrievalSection, } from "../core/retrieval.js";
+import { formatMemoriesForCompaction } from "../core/retrieval.js";
 import { handleFinishedTurn } from "../core/turn-outputs.js";
 import { DEFAULT_RETRIEVAL_MAX_TOKENS, tokensToByteCeiling } from "../core/context-budget.js";
 import { resolveClaudeCodeLiveModel } from "../services/ai/live-model-choice.js";
@@ -11,15 +11,15 @@ import { captureFailureOf, drainCaptureRetries, queueFailedCapture, registerCapt
 import { readClaudeCaptureCursor, writeClaudeCaptureCursor, } from "../services/claude-capture-cursor.js";
 import { memoryClient } from "../services/client.js";
 import { log } from "../services/logger.js";
-import { isFullyPrivate, stripPrivateContent } from "../services/privacy.js";
 import { skillTurnRecorder } from "../services/skill-learning/settings-for.js";
 import { getTags } from "../services/tags.js";
 import { parseClaudeTranscript } from "./claude-conversation.js";
+import { markSessionSeen, promptContext, sectionBudget, sectionLimits, subagentContext, wrapSection, } from "./claude-hook-context.js";
 import { learnClaudeProfile } from "./claude-profile-learning.js";
 import { claudeWindowsToCapture, recordClaudeSkillTurns, sessionDirectory, skillUnitOf, workUnitOf, } from "./claude-turn-units.js";
 import { defaultClaudeProjectsRoot } from "./claude-reader.js";
 // The web app's side of the Claude Code hooks (design decisions 4, 6, 7):
-// retrieval for SessionStart and UserPromptSubmit, a one-worker capture queue
+// retrieval for SessionStart, UserPromptSubmit and SubagentStart, a one-worker capture queue
 // for Stop, profile learning, and the once-per-process backfill start. Logs
 // carry event names, session ids, counts, sizes, and codes; never text.
 const HOST = "claude-code";
@@ -31,6 +31,7 @@ export class ClaudeHookRequestError extends Error {
         this.name = "ClaudeHookRequestError";
     }
 }
+const RETRIEVE_EVENTS = ["session-start", "user-prompt-submit", "subagent-start"];
 function objectBody(body) {
     if (!body || typeof body !== "object" || Array.isArray(body)) {
         throw new ClaudeHookRequestError("A JSON object is required");
@@ -57,14 +58,17 @@ function optionalString(body, key) {
 }
 function parseRetrieveRequest(body) {
     const input = objectBody(body);
-    if (input.event !== "session-start" && input.event !== "user-prompt-submit") {
-        throw new ClaudeHookRequestError("event must be session-start or user-prompt-submit");
+    const event = RETRIEVE_EVENTS.find((name) => name === input.event);
+    if (!event) {
+        throw new ClaudeHookRequestError(`event must be one of ${RETRIEVE_EVENTS.join(", ")}`);
     }
     return {
-        event: input.event,
+        event,
         ...sessionAndCwd(input),
         source: optionalString(input, "source"),
         prompt: optionalString(input, "prompt"),
+        transcriptPath: optionalString(input, "transcript_path"),
+        agentType: optionalString(input, "agent_type"),
     };
 }
 /**
@@ -140,44 +144,58 @@ function maybeStartBackfill(deps) {
         .startBackfill()
         .catch((error) => log("Claude Code backfill start failed", { code: errorCode(error) }, "error"));
 }
-async function retrievalSection(request, budgetBytes) {
-    // Every section this api returns is wrapped in the retrieval tag, so each
-    // packed section reserves the wrapper bytes.
-    const budget = { maxBytes: budgetBytes, wrapperBytes: retrievalWrapperBytes() };
+/** The checked transcript path of the request, or undefined when it has none or fails the check. */
+function requestTranscript(request) {
+    if (!request.transcriptPath)
+        return undefined;
+    try {
+        return checkedTranscriptPath(request.transcriptPath, request.sessionId);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The text to add for one request, already wrapped in the retrieval tag. Empty means nothing. */
+async function retrievalText(request, budgetBytes) {
+    const limits = sectionLimits(budgetBytes);
     if (request.event === "user-prompt-submit") {
-        const prompt = stripPrivateContent(request.prompt ?? "").trim();
-        if (!CONFIG.chatMessage.enabled || !prompt || isFullyPrivate(request.prompt ?? "")) {
-            return null;
-        }
-        return buildRetrievalSection(prompt, request.cwd, request.sessionId, budget);
+        return promptContext({
+            prompt: request.prompt ?? "",
+            cwd: request.cwd,
+            sessionId: request.sessionId,
+            transcriptPath: requestTranscript(request),
+        }, limits);
     }
-    const tags = getTags(request.cwd);
-    if (request.source === "compact" || request.source === "resume") {
-        if (!CONFIG.compaction.enabled)
-            return null;
-        const result = await memoryClient.searchMemoriesBySessionID(request.sessionId, tags.project.tag, CONFIG.compaction.memoryLimit);
-        const own = result.success
-            ? result.results.filter((memory) => memory.metadata?.host === HOST)
-            : [];
-        return own.length > 0 ? formatMemoriesForCompaction(own, budget) : null;
+    if (request.event === "subagent-start") {
+        return subagentContext({
+            cwd: request.cwd,
+            sessionId: request.sessionId,
+            transcriptPath: requestTranscript(request),
+            agentType: request.agentType,
+        }, budgetBytes);
     }
-    if (!CONFIG.chatMessage.enabled)
-        return null;
-    return buildRecentMemoriesSection({
-        projectTag: tags.project.tag,
-        userEmail: tags.user.userEmail,
-        sessionId: request.sessionId,
-        maxMemories: CONFIG.chatMessage.maxMemories,
-        excludeCurrentSession: CONFIG.chatMessage.excludeCurrentSession,
-        maxAgeDays: CONFIG.chatMessage.maxAgeDays,
-        budget,
-    });
+    // A fresh or cleared session adds nothing; the opening section waits for the first prompt.
+    if (request.source !== "compact" && request.source !== "resume")
+        return "";
+    // A compacted or resumed session already has history, so it never gets an opening section.
+    markSessionSeen(request.sessionId);
+    if (!CONFIG.compaction.enabled)
+        return "";
+    const tags = getTags(request.cwd);
+    const result = await memoryClient.searchMemoriesBySessionID(request.sessionId, tags.project.tag, CONFIG.compaction.memoryLimit);
+    const own = result.success
+        ? result.results.filter((memory) => memory.metadata?.host === HOST)
+        : [];
+    return own.length > 0
+        ? wrapSection(formatMemoriesForCompaction(own, sectionBudget(limits)), limits)
+        : "";
 }
 /**
- * `POST /api/claude/retrieve`: recent project memories for a fresh session,
- * the session's own memories after compaction or resume, or the retrieval
- * section for a prompt. Every text is wrapped in the retrieval tag; an empty
- * string means nothing to add.
+ * `POST /api/claude/retrieve`: the retrieval section for a prompt (and the
+ * opening section on a session's first prompt, when on), the memories for a
+ * starting subagent's task, or the session's own memories after compaction or
+ * resume. A fresh or cleared session adds nothing. Every text is wrapped in the
+ * retrieval tag; an empty string means nothing to add.
  */
 export async function handleClaudeRetrieve(body, deps = {}) {
     const request = parseRetrieveRequest(body);
@@ -189,8 +207,7 @@ export async function handleClaudeRetrieve(body, deps = {}) {
     if (request.event === "session-start")
         maybeStartBackfill(deps);
     try {
-        const section = await retrievalSection(request, budgetBytes);
-        return { additionalContext: section ? wrapRetrievalSection(section) : "" };
+        return { additionalContext: await retrievalText(request, budgetBytes) };
     }
     catch (error) {
         log("Claude Code retrieval failed", {

package/dist/importer/claude-hook-context.d.ts

@@ -0,0 +1,49 @@
+import type { ContextBudgetOptions } from "../core/context-budget.js";
+/** Tells the recall rows to draw nothing for this section. 21 bytes, newline included. */
+export declare const ROWS_OFF_MARKER = "<!--omms:rows-off-->\n";
+/** The byte budget of one request and whether recall rows are off for it. */
+export interface SectionLimits {
+    budgetBytes: number;
+    rowsOff: boolean;
+}
+/** Read `visibleRecall` once per request, after the config refresh. */
+export declare function sectionLimits(budgetBytes: number): SectionLimits;
+/** The budget for one packed section: the retrieval tag, and the rows-off marker when set, are reserved. */
+export declare function sectionBudget(limits: SectionLimits): ContextBudgetOptions;
+/** Put a marker line right after the opening tag of a wrapped section. */
+export declare function insertMarker(wrapped: string, marker: string): string;
+/** Wrap a packed section, with the rows-off marker when rows are off. */
+export declare function wrapSection(section: string, limits: SectionLimits): string;
+/**
+ * The opening marker. The query goes on one line, with `"`, `<` and `>`
+ * removed, `--` folded to `-` and 300 characters at most, so it cannot end the
+ * comment early.
+ */
+export declare function openingMarker(query: string): string;
+/** Remember a session, so a later prompt in this process is never first. Oldest ids drop out. */
+export declare function markSessionSeen(sessionId: string): void;
+export interface PromptContextInput {
+    prompt: string;
+    cwd: string;
+    sessionId: string;
+    /** The checked transcript path, or undefined when the request had none or it failed the check. */
+    transcriptPath: string | undefined;
+}
+/**
+ * The added context for a prompt: its retrieval section, and on the first
+ * prompt of a session, with `openingContext` on, the opening section after it.
+ * Empty string when there is nothing to add.
+ */
+export declare function promptContext(input: PromptContextInput, limits: SectionLimits): Promise<string>;
+export interface SubagentContextInput {
+    cwd: string;
+    sessionId: string;
+    transcriptPath: string | undefined;
+    agentType: string | undefined;
+}
+/**
+ * The added context for a starting subagent: the retrieval section for its
+ * task prompt, read from the parent transcript. Every subagent section carries
+ * the rows-off marker. Any problem gives an empty string.
+ */
+export declare function subagentContext(input: SubagentContextInput, budgetBytes: number): Promise<string>;