om-memory-system 5.9.0 → 5.10.1

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 import { isPlaceholderApiKey } from "./services/ai/api-key-placeholder.js";
 import { type KeywordMode } from "./utils/keyword-boost.js";
 import { type ActiveSpace } from "./services/spaces/active-space.js";
+import * as memorisation from "./core/memorisation-settings.js";
 interface OmmsConfig {
     storagePath?: string;
     userEmailOverride?: string;
@@ -28,6 +29,10 @@ interface OmmsConfig {
     keywordMode?: KeywordMode;
     /** Shared budget for automatic memory context in approximate tokens (ceil(UTF-8 bytes / 4)). */
     retrievalMaxTokens?: number;
+    /** Memorisation size and repeat behaviour. Global config only. */
+    memorisationMaxSize?: number;
+    memorisationSizeUnit?: memorisation.MemorisationSettings["memorisationSizeUnit"];
+    memorisationRepeat?: memorisation.MemorisationSettings["memorisationRepeat"];
     maxProfileItems?: number;
     injectProfile?: boolean;
     containerTagPrefix?: string;
@@ -196,26 +201,6 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     skillLearning: boolean;
     skillLearningRedact: boolean;
     skillFolders: string[] | undefined;
-    storagePath: string;
-    /** The global `storagePath` when a project moved `storagePath`; `skills.db` stays there. */
-    skillStoragePath: string | undefined;
-    userEmailOverride: string | undefined;
-    userNameOverride: string | undefined;
-    embeddingModel: string;
-    embeddingDimensions: number;
-    embeddingUseTaskPrefixes: boolean;
-    embeddingApiUrl: string | undefined;
-    embeddingApiKey: string | undefined;
-    similarityThreshold: number;
-    rerankerEnabled: boolean;
-    rerankerApiUrl: string | undefined;
-    rerankerModel: string | undefined;
-    rerankerApiKey: string | undefined;
-    rerankerTimeoutMs: number;
-    keywordBoost: number;
-    keywordMode: KeywordMode;
-    maxMemories: number;
-    retrievalMaxTokens: number;
     maxProfileItems: number;
     injectProfile: boolean;
     containerTagPrefix: string;
@@ -241,6 +226,29 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     captureTraceRetentionDays: number;
     captureAttemptRetentionDays: number;
     captureRetryRetentionHours: number;
+    memorisationMaxSize: number;
+    memorisationSizeUnit: import("./core/memorisation.js").MemorisationSizeUnit;
+    memorisationRepeat: import("./core/memorisation.js").MemorisationRepeat;
+    storagePath: string;
+    /** The global `storagePath` when a project moved `storagePath`; `skills.db` stays there. */
+    skillStoragePath: string | undefined;
+    userEmailOverride: string | undefined;
+    userNameOverride: string | undefined;
+    embeddingModel: string;
+    embeddingDimensions: number;
+    embeddingUseTaskPrefixes: boolean;
+    embeddingApiUrl: string | undefined;
+    embeddingApiKey: string | undefined;
+    similarityThreshold: number;
+    rerankerEnabled: boolean;
+    rerankerApiUrl: string | undefined;
+    rerankerModel: string | undefined;
+    rerankerApiKey: string | undefined;
+    rerankerTimeoutMs: number;
+    keywordBoost: number;
+    keywordMode: KeywordMode;
+    maxMemories: number;
+    retrievalMaxTokens: number;
 };
 export declare function getGlobalConfigSourcePath(): string | undefined;
 export declare function getGlobalConfigWritePath(): string;
@@ -310,26 +318,6 @@ export declare let CONFIG: {
     skillLearning: boolean;
     skillLearningRedact: boolean;
     skillFolders: string[] | undefined;
-    storagePath: string;
-    /** The global `storagePath` when a project moved `storagePath`; `skills.db` stays there. */
-    skillStoragePath: string | undefined;
-    userEmailOverride: string | undefined;
-    userNameOverride: string | undefined;
-    embeddingModel: string;
-    embeddingDimensions: number;
-    embeddingUseTaskPrefixes: boolean;
-    embeddingApiUrl: string | undefined;
-    embeddingApiKey: string | undefined;
-    similarityThreshold: number;
-    rerankerEnabled: boolean;
-    rerankerApiUrl: string | undefined;
-    rerankerModel: string | undefined;
-    rerankerApiKey: string | undefined;
-    rerankerTimeoutMs: number;
-    keywordBoost: number;
-    keywordMode: KeywordMode;
-    maxMemories: number;
-    retrievalMaxTokens: number;
     maxProfileItems: number;
     injectProfile: boolean;
     containerTagPrefix: string;
@@ -355,6 +343,29 @@ export declare let CONFIG: {
     captureTraceRetentionDays: number;
     captureAttemptRetentionDays: number;
     captureRetryRetentionHours: number;
+    memorisationMaxSize: number;
+    memorisationSizeUnit: import("./core/memorisation.js").MemorisationSizeUnit;
+    memorisationRepeat: import("./core/memorisation.js").MemorisationRepeat;
+    storagePath: string;
+    /** The global `storagePath` when a project moved `storagePath`; `skills.db` stays there. */
+    skillStoragePath: string | undefined;
+    userEmailOverride: string | undefined;
+    userNameOverride: string | undefined;
+    embeddingModel: string;
+    embeddingDimensions: number;
+    embeddingUseTaskPrefixes: boolean;
+    embeddingApiUrl: string | undefined;
+    embeddingApiKey: string | undefined;
+    similarityThreshold: number;
+    rerankerEnabled: boolean;
+    rerankerApiUrl: string | undefined;
+    rerankerModel: string | undefined;
+    rerankerApiKey: string | undefined;
+    rerankerTimeoutMs: number;
+    keywordBoost: number;
+    keywordMode: KeywordMode;
+    maxMemories: number;
+    retrievalMaxTokens: number;
 };
 type RuntimeConfig = ReturnType<typeof buildConfig>;
 export { getAutoCaptureProviderStatus, type AutoCaptureProviderStatus, } from "./services/ai/live-model-choice.js";

package/dist/config.js

@@ -1,6 +1,5 @@
 import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { stripJsoncComments } from "./services/jsonc.js";
 import { isValidClaudeConfigDir } from "./services/claude-folder.js";
 import { log } from "./services/logger.js";
@@ -22,20 +21,8 @@ import { expandPath, storagePathFrom, withSkillStorage, } from "./services/space
 import { resolveActiveSpace } from "./services/spaces/active-space.js";
 import { backfillSpaceLabelsFromDisk } from "./services/spaces/space-label.js";
 import { resetStoreHandles } from "./services/spaces/store-handles.js";
-const OMMS_CONFIG_DIR = join(homedir(), ".config", "omms");
-const DATA_DIR = join(homedir(), ".omms");
-const LEGACY_CONFIG_FILES = [
-    join(homedir(), ".config", "opencode", "opencode-mem.jsonc"),
-    join(homedir(), ".config", "opencode", "opencode-mem.json"),
-];
-// Dual-read: the omms config wins; the legacy opencode-mem config is read
-// only when no omms config file exists (decision D13 rule 6). The legacy
-// file is never written.
-const CONFIG_FILES = [
-    join(OMMS_CONFIG_DIR, "omms.jsonc"),
-    join(OMMS_CONFIG_DIR, "omms.json"),
-    ...LEGACY_CONFIG_FILES,
-];
+import * as memorisation from "./core/memorisation-settings.js";
+import { CONFIG_FILES, DATA_DIR, LEGACY_CONFIG_FILES, OMMS_CONFIG_DIR } from "./config-paths.js";
 if (!existsSync(OMMS_CONFIG_DIR))
     mkdirSync(OMMS_CONFIG_DIR, { recursive: true });
 if (!existsSync(DATA_DIR))
@@ -51,6 +38,9 @@ const DEFAULTS = {
     rerankerEnabled: false,
     rerankerTimeoutMs: RERANKER_TIMEOUT_DEFAULT_MS,
     retrievalMaxTokens: 2000,
+    memorisationMaxSize: 2000,
+    memorisationSizeUnit: "characters",
+    memorisationRepeat: "add",
     maxProfileItems: 5,
     injectProfile: true,
     // omms since the tag prefix migration: new memories carry the fork's
@@ -325,6 +315,7 @@ function buildConfig(fileConfig) {
         keywordMode: checkedKeywordMode(fileConfig.keywordMode),
         maxMemories,
         retrievalMaxTokens,
+        ...memorisation.settingsFrom(fileConfig),
         maxProfileItems: fileConfig.maxProfileItems ?? DEFAULTS.maxProfileItems,
         injectProfile: fileConfig.injectProfile ?? DEFAULTS.injectProfile,
         containerTagPrefix: fileConfig.containerTagPrefix ?? DEFAULTS.containerTagPrefix,
@@ -526,6 +517,8 @@ export function initConfig(directory, options = {}) {
     delete projectOverrides.captureTraceRetentionDays;
     // The queue holds conversation text, so only the global file sets how long.
     delete projectOverrides.captureRetryRetentionHours;
+    for (const key of memorisation.MEMORISATION_KEYS)
+        delete projectOverrides[key];
     // Skill learning stores full turns: a project may only turn it off.
     const skillRule = projectSkillOverride(projectConfig);
     if (skillRule.ignoredTurnOn) {

package/dist/core/capture.d.ts

@@ -1,5 +1,5 @@
 import { type CaptureFailureInfo } from "./capture-retry-policy.js";
-import type { CaptureConversation, CapturePromptContext, CaptureProvenance, CaptureSummaryProvider } from "./host.js";
+import type { CaptureConversation, CapturePromptContext, CaptureProvenance, CaptureSkipReason, CaptureSummaryProvider } from "./host.js";
 export interface CaptureWorkUnit extends CaptureProvenance, CaptureConversation {
     projectDirectory: string;
     userPrompt: string;
@@ -12,6 +12,7 @@ export type CaptureResult = {
 } | {
     status: "skipped";
     type?: string;
+    reason?: CaptureSkipReason;
 };
 /**
  * Thrown by `captureConversation` for a failed attempt. Keeps the original

package/dist/core/capture.js

@@ -3,6 +3,7 @@ import { buildCaptureAttemptRecord, emitCaptureAttempt } from "../services/captu
 import { memoryClient } from "../services/client.js";
 import { getTags } from "../services/tags.js";
 import { buildMarkdownContext, getAutoCaptureMarkdownBudget } from "./capture-context.js";
+import { turnSavedMemorisation } from "./memorise-turn.js";
 import { errorHttpStatus, errorRetryAfterMs, } from "./capture-retry-policy.js";
 /**
  * Thrown by `captureConversation` for a failed attempt. Keeps the original
@@ -18,7 +19,7 @@ export class CaptureAttemptError extends Error {
 }
 async function getLatestProjectMemory(containerTag) {
     try {
-        const result = await memoryClient.listMemories(containerTag, 1);
+        const result = await memoryClient.listMemories(containerTag, 1, "project", { kind: "normal" });
         if (!result.success || result.memories.length === 0)
             return null;
         const latest = result.memories[0];
@@ -65,6 +66,12 @@ export async function captureConversation(workUnit, provider) {
     }
 }
 async function runCapture(workUnit, provider, diagnostics, markdownBudget) {
+    // A memorisation reaches an agent only through `recall`. Capturing the turn
+    // that saved one would put the snapshot back into per-prompt recall.
+    if (turnSavedMemorisation(workUnit.toolCalls)) {
+        diagnostics.skipReason = "memorisation-turn";
+        return { status: "skipped", reason: "memorisation-turn" };
+    }
     const tags = getTags(workUnit.projectDirectory);
     const latestMemory = await getLatestProjectMemory(tags.project.tag);
     const context = buildMarkdownContext(workUnit.userPrompt, workUnit.textResponses, workUnit.toolCalls, latestMemory, markdownBudget);

package/dist/core/host.d.ts

@@ -1,5 +1,11 @@
 import type { MemoryHost, MemorySourceType } from "../types/index.js";
 export type CaptureToolOutcome = "ok" | "error" | "unknown";
+/**
+ * Set only on a `memory` tool call in `memorise` mode: `saved` once its result
+ * reported success, `failed` when it did not, `unknown` until a result answers.
+ * Automatic capture skips a turn that holds a `saved` call.
+ */
+export type CaptureMemoriseState = "saved" | "failed" | "unknown";
 export interface CaptureToolCall {
     name: string;
     input: string;
@@ -9,6 +15,8 @@ export interface CaptureToolCall {
     error?: string;
     /** Full path of a read-type call, for skill detection. Memory capture ignores it. */
     path?: string;
+    /** Set by the host readers on a memorise call. Capture skips the turn when it is `saved`. */
+    memorise?: CaptureMemoriseState;
 }
 export interface CaptureConversation {
     textResponses: string[];
@@ -30,6 +38,8 @@ export type CaptureAttemptOutcome = "saved" | "skipped" | "failed";
 /** Fixed failure codes, in the order classification checks them. */
 export declare const CAPTURE_FAILURE_REASONS: readonly ["call-error", "empty-text", "truncated", "invalid-json", "schema-mismatch", "persist-error"];
 export type CaptureFailureReason = (typeof CAPTURE_FAILURE_REASONS)[number];
+/** Why capture ended a turn as skipped before the capture model ran. */
+export type CaptureSkipReason = "memorisation-turn";
 export type CaptureExtractionPath = "host-model" | "external-api";
 /**
  * Filled in by the extraction path during one capture attempt. The capture
@@ -47,6 +57,8 @@ export interface CaptureAttemptDiagnostics {
     userPrompt?: string;
     rawReply?: string;
     failureReason?: CaptureFailureReason;
+    /** Set when capture skipped the turn without calling the capture model. */
+    skipReason?: CaptureSkipReason;
     /** HTTP status of a failed model call, when the path knows it. */
     httpStatus?: number;
     /** The wait a failed model call asked for in its `Retry-After` header. */

package/dist/core/memorisation-operations.d.ts

@@ -0,0 +1,33 @@
+import { type MemoryScope } from "../services/client.js";
+import type { LinkedSearchSettings } from "../services/linked-search.js";
+import type { getTags } from "../services/tags.js";
+import type { MemoryHost } from "../types/index.js";
+import { type MemorisationSettings, type MemorisationSnapshot } from "./memorisation.js";
+export interface MemoriseArgs extends MemorisationSnapshot {
+    content?: string;
+    tags?: string;
+}
+export interface RecallArgs {
+    /** A memorisation ID (`ms-4k7q2p`) or free text. */
+    query?: string;
+    /** Also read as an ID or text when `query` is empty. */
+    memoryId?: string;
+    content?: string;
+    /** Comma-separated labels. Only memorisations that carry all of them match. */
+    tags?: string;
+    limit?: number;
+    scope?: MemoryScope;
+}
+interface MemorisationContext {
+    host?: MemoryHost;
+    hostSessionId?: string;
+}
+/** Saves an exact memorisation: explicit text or a session snapshot. */
+export declare function runMemorise(args: MemoriseArgs, context: MemorisationContext, tags: ReturnType<typeof getTags>, settings: MemorisationSettings, linked: LinkedSearchSettings): Promise<Record<string, unknown>>;
+/**
+ * Fetches memorisations by exact ID, or by text across memorisations only. `tags` keeps only
+ * memorisations that carry every label. With `tags` and no text it returns the newest ones.
+ * An exact ID ignores `tags`.
+ */
+export declare function runRecall(args: RecallArgs, tags: ReturnType<typeof getTags>, scope: MemoryScope | undefined, linked: LinkedSearchSettings): Promise<Record<string, unknown>>;
+export {};

package/dist/core/memorisation-operations.js

@@ -0,0 +1,160 @@
+import { memoryClient } from "../services/client.js";
+import { findSnapshotByHostSession, getMemorisationById, listMemorisationsByTags, memorisationIdTaken, } from "../services/memorisation-store.js";
+import { isFullyPrivate, stripPrivateContent } from "../services/privacy.js";
+import { hasAllTags, isMemorisationId, MEMORISATION_TAG, memorisationId, memorisationSizeError, parseTagList, pickRecallMatches, snapshotText, visibleTags, } from "./memorisation.js";
+const SNAPSHOT_FIELDS = ["topic", "done", "doing", "next"];
+const BLOCKED = { success: false, error: "Private content blocked" };
+/** Strips `<private>` text. A field that is fully private is dropped. */
+function cleanField(value) {
+    if (!value?.trim() || isFullyPrivate(value))
+        return undefined;
+    return stripPrivateContent(value);
+}
+function callerTags(tags) {
+    return [...new Set([MEMORISATION_TAG, ...parseTagList(tags)])];
+}
+/** Builds the text to store, or the refusal to return. */
+function memorisationText(args) {
+    const hasContent = Boolean(args.content?.trim());
+    const hasSnapshot = SNAPSHOT_FIELDS.some((field) => args[field]?.trim());
+    if (hasContent && hasSnapshot) {
+        return {
+            success: false,
+            error: "Give content or snapshot fields (topic, done, doing, next), not both",
+        };
+    }
+    if (!hasContent && !hasSnapshot) {
+        return {
+            success: false,
+            error: "content or at least one snapshot field (topic, done, doing, next) required",
+        };
+    }
+    if (hasContent) {
+        if (isFullyPrivate(args.content))
+            return BLOCKED;
+        return { kind: "explicit", text: stripPrivateContent(args.content) };
+    }
+    const text = snapshotText({
+        topic: cleanField(args.topic),
+        done: cleanField(args.done),
+        doing: cleanField(args.doing),
+        next: cleanField(args.next),
+    });
+    return text ? { kind: "snapshot", text } : BLOCKED;
+}
+/** Saves an exact memorisation: explicit text or a session snapshot. */
+export async function runMemorise(args, context, tags, settings, linked) {
+    const built = memorisationText(args);
+    if ("success" in built)
+        return built;
+    const sizeError = memorisationSizeError(built.text, settings);
+    if (sizeError)
+        return { success: false, error: sizeError };
+    const sessionId = context.hostSessionId;
+    const wantsReplace = built.kind === "snapshot" && settings.memorisationRepeat === "replace";
+    const earlier = wantsReplace && sessionId ? await findSnapshotByHostSession(sessionId, tags.project.tag) : null;
+    const id = earlier?.id ?? (await memorisationId((candidate) => memorisationIdTaken(candidate, linked)));
+    const recordTags = callerTags(args.tags);
+    const info = tags.project;
+    const result = await memoryClient.addMemory(built.text, info.tag, {
+        id,
+        // The client swaps the earlier row for this one in one transaction, so a failed write keeps it.
+        replaceExisting: Boolean(earlier),
+        type: "memorisation",
+        tags: recordTags,
+        memorisation: built.kind,
+        host: context.host,
+        hostSessionId: sessionId,
+        source: "manual",
+        displayName: info.displayName,
+        userName: info.userName,
+        userEmail: info.userEmail,
+        projectPath: info.projectPath,
+        projectName: info.projectName,
+        gitRepoUrl: info.gitRepoUrl,
+    });
+    if (!result.success)
+        return { success: false, error: result.error };
+    const note = wantsReplace && !sessionId
+        ? " It could not replace an earlier snapshot because the host gave no session ID, so it was added."
+        : "";
+    return {
+        success: true,
+        message: `Memorisation saved as ${id}.${note}`,
+        id,
+        replaced: Boolean(earlier),
+        tags: recordTags,
+    };
+}
+function toIso(value) {
+    return typeof value === "number" ? new Date(value).toISOString() : undefined;
+}
+/** How many labelled memorisations a recall with no text returns when the caller gives no limit. */
+const LABEL_RECALL_LIMIT = 10;
+/** A labelled text search reads this many hits, so the label filter does not drop a lower-ranked match. */
+const LABEL_SEARCH_POOL = 200;
+/**
+ * Fetches memorisations by exact ID, or by text across memorisations only. `tags` keeps only
+ * memorisations that carry every label. With `tags` and no text it returns the newest ones.
+ * An exact ID ignores `tags`.
+ */
+export async function runRecall(args, tags, scope, linked) {
+    const input = (args.query ?? args.memoryId ?? args.content)?.trim();
+    const wanted = parseTagList(args.tags);
+    if (!input && wanted.length === 0) {
+        return { success: false, error: "query or tags required: a memorisation ID, text or labels" };
+    }
+    if (!input)
+        return recallByLabels(wanted, tags, scope, args.limit);
+    if (isMemorisationId(input)) {
+        const found = await getMemorisationById(input, tags.project.tag, linked);
+        if (!found)
+            return { success: false, error: `No memorisation has the ID ${input}` };
+        return { success: true, count: 1, matches: [found] };
+    }
+    const result = await memoryClient.searchMemories(input, tags.project.tag, scope, {
+        includeLinked: true,
+        kind: "memorisation",
+        ...(wanted.length > 0 ? { limit: LABEL_SEARCH_POOL } : {}),
+    });
+    if (!result.success)
+        return { success: false, error: result.error };
+    const candidates = (result.results ?? [])
+        .filter((hit) => hasAllTags(hit.tags, wanted))
+        .map((hit) => ({
+        id: hit.id,
+        content: (hit.memory || hit.chunk),
+        confidence: Math.round(hit.similarity * 100),
+        createdAt: toIso(hit.createdAt),
+        tags: visibleTags(hit.tags),
+        ...(hit.spaceName ? { space: hit.spaceName } : {}),
+    }))
+        .sort((a, b) => b.confidence - a.confidence);
+    const matches = pickRecallMatches(candidates, args.limit);
+    return {
+        success: true,
+        query: input,
+        count: matches.length,
+        matches,
+        ...(matches.length === 0 ? { message: "No memorisation matched" } : {}),
+    };
+}
+/** The newest memorisations that carry every label. They are not ranked, so they have no confidence. */
+async function recallByLabels(wanted, tags, scope, limit) {
+    const listed = await listMemorisationsByTags(tags.project.tag, wanted, scope ?? "project", Math.max(1, limit ?? LABEL_RECALL_LIMIT));
+    if (!listed.success)
+        return listed;
+    const matches = listed.memories.map((memory) => ({
+        id: memory.id,
+        content: memory.summary,
+        createdAt: memory.createdAt,
+        tags: visibleTags(memory.tags),
+        ...(memory.spaceName ? { space: memory.spaceName } : {}),
+    }));
+    return {
+        success: true,
+        count: matches.length,
+        matches,
+        ...(matches.length === 0 ? { message: "No memorisation matched" } : {}),
+    };
+}

package/dist/core/memorisation-settings.d.ts

@@ -0,0 +1,11 @@
+import { type MemorisationSettings } from "./memorisation.js";
+export type { MemorisationSettings } from "./memorisation.js";
+export declare const MEMORISATION_KEYS: readonly ["memorisationMaxSize", "memorisationSizeUnit", "memorisationRepeat"];
+export declare const MEMORISATION_DEFAULTS: MemorisationSettings;
+/** Global-only memorisation settings, with defaults for an older config file. */
+export declare function settingsFrom(config: Partial<MemorisationSettings>): MemorisationSettings;
+/** The web writer validates the pair, so a unit edit cannot strand an invalid number. */
+export declare function checkMemorisationSettingsEdits(edits: Record<string, unknown>, current: MemorisationSettings): void;
+export { settingsFrom as memorisationSettingsFrom };
+/** The three settings are global-only; a project config cannot replace them. */
+export declare function removeMemorisationProjectOverrides(config: Record<string, unknown>): void;

package/dist/core/memorisation-settings.js

@@ -0,0 +1,48 @@
+import { memorisationCapError, memorisationCapIsValid, } from "./memorisation.js";
+export const MEMORISATION_KEYS = [
+    "memorisationMaxSize",
+    "memorisationSizeUnit",
+    "memorisationRepeat",
+];
+export const MEMORISATION_DEFAULTS = {
+    memorisationMaxSize: 2000,
+    memorisationSizeUnit: "characters",
+    memorisationRepeat: "add",
+};
+/** Global-only memorisation settings, with defaults for an older config file. */
+export function settingsFrom(config) {
+    const memorisationMaxSize = config.memorisationMaxSize ?? MEMORISATION_DEFAULTS.memorisationMaxSize;
+    const memorisationSizeUnit = config.memorisationSizeUnit ?? MEMORISATION_DEFAULTS.memorisationSizeUnit;
+    if (!memorisationCapIsValid(memorisationMaxSize, memorisationSizeUnit)) {
+        throw new Error("Invalid memorisation size settings");
+    }
+    const memorisationRepeat = config.memorisationRepeat ?? MEMORISATION_DEFAULTS.memorisationRepeat;
+    if (memorisationRepeat !== "add" && memorisationRepeat !== "replace") {
+        throw new Error("Invalid memorisationRepeat config");
+    }
+    return { memorisationMaxSize, memorisationSizeUnit, memorisationRepeat };
+}
+/** The web writer validates the pair, so a unit edit cannot strand an invalid number. */
+export function checkMemorisationSettingsEdits(edits, current) {
+    if (edits.memorisationRepeat !== undefined) {
+        const repeat = edits.memorisationRepeat;
+        if (repeat !== "add" && repeat !== "replace") {
+            throw new Error("memorisationRepeat must be add or replace");
+        }
+    }
+    const hasSize = Object.hasOwn(edits, "memorisationMaxSize");
+    const hasUnit = Object.hasOwn(edits, "memorisationSizeUnit");
+    if (!hasSize && !hasUnit)
+        return;
+    const size = hasSize ? edits.memorisationMaxSize : current.memorisationMaxSize;
+    const unit = hasUnit ? edits.memorisationSizeUnit : current.memorisationSizeUnit;
+    if (!memorisationCapIsValid(size, unit)) {
+        throw new Error(memorisationCapError(unit === "tokens" ? "tokens" : "characters"));
+    }
+}
+export { settingsFrom as memorisationSettingsFrom };
+/** The three settings are global-only; a project config cannot replace them. */
+export function removeMemorisationProjectOverrides(config) {
+    for (const key of MEMORISATION_KEYS)
+        delete config[key];
+}

package/dist/core/memorisation.d.ts

@@ -0,0 +1,43 @@
+export type MemorisationSizeUnit = "characters" | "tokens";
+export type MemorisationRepeat = "add" | "replace";
+export interface MemorisationSettings {
+    memorisationMaxSize: number;
+    memorisationSizeUnit: MemorisationSizeUnit;
+    memorisationRepeat: MemorisationRepeat;
+}
+export interface MemorisationSnapshot {
+    topic?: string;
+    done?: string;
+    doing?: string;
+    next?: string;
+}
+export declare function snapshotText(snapshot: MemorisationSnapshot): string;
+export declare function memorisationId(exists: (id: string) => boolean | Promise<boolean>, random?: () => number): Promise<string>;
+export declare function isMemorisationId(value: string): boolean;
+export declare function memorisationSize(text: string, unit: MemorisationSizeUnit): number;
+export declare function memorisationSizeError(text: string, settings: Pick<MemorisationSettings, "memorisationMaxSize" | "memorisationSizeUnit">): string | null;
+export declare function memorisationSizeRange(unit: MemorisationSizeUnit): {
+    min: number;
+    max: number;
+};
+export declare function memorisationCapIsValid(maxSize: unknown, unit: unknown): maxSize is number;
+export declare function memorisationCapError(unit: MemorisationSizeUnit): string;
+export interface RecallCandidate {
+    id: string;
+    content: string;
+    confidence: number;
+    createdAt?: string;
+    space?: string;
+}
+/** One clear winner is enough. Otherwise return three, or the caller's limit when one is given. */
+export declare function pickRecallMatches<T extends {
+    confidence: number;
+}>(candidates: T[], limit?: number): T[];
+/** The fixed tag every memorisation carries. It is not a label the user sees. */
+export declare const MEMORISATION_TAG = "memorisation";
+/** A comma-separated tag list as unique, trimmed, lower-case tags in the order given. */
+export declare function parseTagList(text: string | undefined): string[];
+/** The labels of a record: its tags without the fixed memorisation tag, in stored order. */
+export declare function visibleTags(tags: string[] | undefined): string[];
+/** True when the record carries every wanted tag. Case and surrounding spaces do not matter. */
+export declare function hasAllTags(recordTags: string[] | undefined, wanted: string[]): boolean;

package/dist/core/memorisation.js

@@ -0,0 +1,76 @@
+import { estimateTokens } from "./context-budget.js";
+export function snapshotText(snapshot) {
+    return ["topic", "done", "doing", "next"]
+        .filter((key) => snapshot[key]?.trim())
+        .map((key) => `${key[0].toUpperCase()}${key.slice(1)}: ${snapshot[key].trim()}`)
+        .join("\n");
+}
+export function memorisationId(exists, random = Math.random) {
+    return (async () => {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const suffix = Math.floor(random() * 36 ** 6)
+                .toString(36)
+                .padStart(6, "0");
+            const id = `ms-${suffix}`;
+            if (!(await exists(id)))
+                return id;
+        }
+        throw new Error("Could not allocate a unique memorisation ID after five tries");
+    })();
+}
+export function isMemorisationId(value) {
+    return /^ms-[a-z0-9]{6}$/.test(value.trim());
+}
+export function memorisationSize(text, unit) {
+    return unit === "tokens" ? estimateTokens(text) : text.length;
+}
+export function memorisationSizeError(text, settings) {
+    const size = memorisationSize(text, settings.memorisationSizeUnit);
+    if (size <= settings.memorisationMaxSize)
+        return null;
+    const unit = settings.memorisationSizeUnit;
+    return `Memorisation size limit is ${settings.memorisationMaxSize} ${unit}; the text has ${unit === "tokens" ? "about " : ""}${size} ${unit}. Shorten it and try again.`;
+}
+export function memorisationSizeRange(unit) {
+    return unit === "tokens" ? { min: 25, max: 5000 } : { min: 100, max: 20000 };
+}
+export function memorisationCapIsValid(maxSize, unit) {
+    return ((unit === "characters" || unit === "tokens") &&
+        Number.isSafeInteger(maxSize) &&
+        maxSize >= memorisationSizeRange(unit).min &&
+        maxSize <= memorisationSizeRange(unit).max);
+}
+export function memorisationCapError(unit) {
+    const { min, max } = memorisationSizeRange(unit);
+    return `memorisationMaxSize must be a whole number from ${min} to ${max} ${unit}`;
+}
+const DEFAULT_RECALL_MATCHES = 3;
+/** One clear winner is enough. Otherwise return three, or the caller's limit when one is given. */
+export function pickRecallMatches(candidates, limit) {
+    const maximum = Math.max(0, limit ?? DEFAULT_RECALL_MATCHES);
+    if (candidates.length === 0 || maximum === 0)
+        return [];
+    const [first, second] = candidates;
+    if (first && first.confidence >= 80 && first.confidence - (second?.confidence ?? 0) >= 10) {
+        return [first];
+    }
+    return candidates.slice(0, maximum);
+}
+/** The fixed tag every memorisation carries. It is not a label the user sees. */
+export const MEMORISATION_TAG = "memorisation";
+const normaliseTag = (tag) => tag.trim().toLowerCase();
+/** A comma-separated tag list as unique, trimmed, lower-case tags in the order given. */
+export function parseTagList(text) {
+    return [...new Set((text ?? "").split(",").map(normaliseTag).filter(Boolean))];
+}
+/** The labels of a record: its tags without the fixed memorisation tag, in stored order. */
+export function visibleTags(tags) {
+    return (tags ?? [])
+        .map((tag) => tag.trim())
+        .filter((tag) => tag && normaliseTag(tag) !== MEMORISATION_TAG);
+}
+/** True when the record carries every wanted tag. Case and surrounding spaces do not matter. */
+export function hasAllTags(recordTags, wanted) {
+    const have = new Set((recordTags ?? []).map(normaliseTag));
+    return wanted.every((tag) => have.has(normaliseTag(tag)));
+}

package/dist/core/memorise-turn.d.ts

@@ -0,0 +1,11 @@
+import type { CaptureMemoriseState, CaptureToolCall } from "./host.js";
+/** `unknown` for a memorise call (a result still has to answer it), otherwise undefined. */
+export declare function memoriseCallState(name: string, args: unknown): "unknown" | undefined;
+/**
+ * The state a result gives a memorise call. A host error, or a JSON reply with
+ * `success: false`, is `failed`. The memory tool reports its own failures as a
+ * normal reply with `success: false`, so the host does not always mark them.
+ */
+export declare function memoriseResultState(isError: boolean, text: string): CaptureMemoriseState;
+/** True when any call in the turn saved a memorisation. */
+export declare function turnSavedMemorisation(toolCalls: readonly CaptureToolCall[]): boolean;