om-memory-system 5.9.0 → 5.10.1

package/dist/services/client.d.ts

@@ -1,6 +1,7 @@
 import { type MemoryReadOptions } from "./linked-search.js";
 import type { MemoryType } from "../types/index.js";
 import type { SearchResult } from "./turso/types.js";
+import type { MemoryKind } from "./memory-kind.js";
 export type MemoryScope = "project" | "all-projects";
 export declare class LocalMemoryClient {
     private initPromise;
@@ -34,6 +35,10 @@ export declare class LocalMemoryClient {
         timing: number;
     }>;
     addMemory(content: string, containerTag: string, metadata?: {
+        /** A caller-chosen record ID, such as a memorisation `ms-` ID. Default: a generated `mem_` ID. */
+        id?: string;
+        /** Overwrite the row with `id` in one transaction, so a failed write keeps the old row. */
+        replaceExisting?: boolean;
         type?: MemoryType;
         source?: "manual" | "auto-capture" | "import" | "api";
         tags?: string[];
@@ -95,7 +100,7 @@ export declare class LocalMemoryClient {
     }): Promise<import("./shard-path-migration-service.js").PathMigrationResult>;
     exportMemories(currentDirectory: string, outputPath: string): Promise<import("./memory-portability-service.js").ExportMemoriesResult>;
     importMemories(currentDirectory: string, inputPath: string, dryRun?: boolean): Promise<import("./memory-portability-service.js").ImportMemoriesResult>;
-    searchMemoriesBySessionID(sessionID: string, containerTag: string, limit?: number): Promise<{
+    searchMemoriesBySessionID(sessionID: string, containerTag: string, limit?: number, kind?: MemoryKind): Promise<{
         success: true;
         results: {
             id: any;

package/dist/services/client.js

@@ -11,6 +11,8 @@ import { findLinkedMemoryOwner, linkedRefusal, linkedSettingsFrom, listLinkedSpa
 import { CONFIG } from "../config.js";
 import { activeOwner } from "./active-space-access.js";
 import { log } from "./logger.js";
+import { replaceMemoryRow } from "./memory-replace.js";
+import { searchMemoriesBySessionID as readSessionMemories } from "./client-session-read.js";
 export class LocalMemoryClient {
     initPromise = null;
     isInitialized = false;
@@ -64,7 +66,7 @@ export class LocalMemoryClient {
         // Capture the result count and the reranker settings at entry: initialize,
         // embedding, and shard reads all await, and a config edit during them must
         // not change this search's limit or reranker target.
-        const maxMemories = CONFIG.maxMemories;
+        const maxMemories = options.limit ?? CONFIG.maxMemories;
         const keywordBoost = CONFIG.keywordBoost;
         const reranker = rerankSettingsFrom(CONFIG);
         // The reranker path below always uses the boost: it needs a full pool on the similarity scale.
@@ -96,13 +98,14 @@ export class LocalMemoryClient {
                     queryText: query,
                     maxMemories,
                     similarityThreshold: CONFIG.similarityThreshold,
+                    kind: options.kind ?? "normal",
                 }, reranker, {
-                    search: (shardList, vector, tag, limit, threshold, queryText) => tursoVectorSearch.searchAcrossShards(shardList, vector, tag, limit, threshold, queryText, keywordBoost),
+                    search: (shardList, vector, tag, limit, threshold, queryText, kind) => tursoVectorSearch.searchAcrossShards(shardList, vector, tag, limit, threshold, queryText, keywordBoost, "boost", undefined, kind),
                     log: (message, meta) => log(message, meta),
                 }));
             }
             else {
-                ({ results, warnings } = await tursoVectorSearch.searchAcrossShards(shards, queryVector, scope === "all-projects" ? "" : containerTag, maxMemories, CONFIG.similarityThreshold, query, keywordBoost, keywordMode));
+                ({ results, warnings } = await tursoVectorSearch.searchAcrossShards(shards, queryVector, scope === "all-projects" ? "" : containerTag, maxMemories, CONFIG.similarityThreshold, query, keywordBoost, keywordMode, undefined, options.kind ?? "normal"));
             }
             // Linked spaces fill only the places the own search left (D6); the reranker never sees them.
             if (options.includeLinked) {
@@ -113,7 +116,10 @@ export class LocalMemoryClient {
                     containerTag,
                     ownCount: results.length,
                     owner: activeOwner(),
-                    settings: linkedSettingsFrom(CONFIG),
+                    settings: options.limit === undefined
+                        ? linkedSettingsFrom(CONFIG)
+                        : { ...linkedSettingsFrom(CONFIG), maxMemories: options.limit },
+                    kind: options.kind ?? "normal",
                 });
                 results = [...results, ...linked.results];
                 warnings = [...warnings, ...linked.warnings];
@@ -146,11 +152,11 @@ export class LocalMemoryClient {
                 });
             }
             const { scope, hash } = extractScopeFromContainerTag(containerTag);
-            return tursoShardManager.withScopeWriteLock(scope, hash, async () => {
+            return await tursoShardManager.withScopeWriteLock(scope, hash, async () => {
                 const shard = await tursoShardManager.getWriteShard(scope, hash);
-                const id = `mem_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
                 const now = Date.now();
-                const { displayName, userName, userEmail, projectPath, projectName, gitRepoUrl, type, tags: _tags, ...dynamicMetadata } = metadata || {};
+                const { id: customId, replaceExisting, displayName, userName, userEmail, projectPath, projectName, gitRepoUrl, type, tags: _tags, ...dynamicMetadata } = metadata || {};
+                const id = customId ?? `mem_${now}_${Math.random().toString(36).substring(2, 11)}`;
                 const record = {
                     id,
                     content,
@@ -169,6 +175,9 @@ export class LocalMemoryClient {
                     gitRepoUrl,
                     metadata: Object.keys(dynamicMetadata).length > 0 ? JSON.stringify(dynamicMetadata) : undefined,
                 };
+                if (replaceExisting && customId && (await replaceMemoryRow(record))) {
+                    return { success: true, id };
+                }
                 const db = await tursoConnectionManager.getConnection(shard.dbPath);
                 await tursoVectorSearch.insertVector(db, record);
                 await tursoShardManager.incrementVectorCount(shard.id);
@@ -225,7 +234,7 @@ export class LocalMemoryClient {
                 const allMemories = [];
                 for (const shard of shards) {
                     const db = await tursoConnectionManager.getConnection(shard.dbPath);
-                    const rows = await tursoVectorSearch.listMemories(db, scope === "all-projects" ? "" : containerTag, limit);
+                    const rows = await tursoVectorSearch.listMemories(db, scope === "all-projects" ? "" : containerTag, limit, options.kind ?? "normal");
                     allMemories.push(...rows);
                 }
                 allMemories.sort((a, b) => Number(b.created_at) - Number(a.created_at));
@@ -240,6 +249,7 @@ export class LocalMemoryClient {
                     ownCount: memories.length,
                     owner: activeOwner(),
                     settings: linkedSettingsFrom(CONFIG),
+                    kind: options.kind ?? "normal",
                 });
                 memories = [...memories, ...linked.memories];
             }
@@ -315,36 +325,10 @@ export class LocalMemoryClient {
             return { success: false, dryRun: Boolean(dryRun), error: errorMessage };
         }
     }
-    async searchMemoriesBySessionID(sessionID, containerTag, limit = 10) {
+    async searchMemoriesBySessionID(sessionID, containerTag, limit = 10, kind = "normal") {
         try {
             await this.initialize();
-            const { scope, hash } = extractScopeFromContainerTag(containerTag);
-            const shards = await tursoShardManager.getAllShards(scope, hash);
-            if (shards.length === 0) {
-                return { success: true, results: [], total: 0, timing: 0 };
-            }
-            const allMemories = [];
-            for (const shard of shards) {
-                const db = await tursoConnectionManager.getConnection(shard.dbPath);
-                const memories = await tursoVectorSearch.getMemoriesBySessionID(db, sessionID);
-                allMemories.push(...memories);
-            }
-            allMemories.sort((a, b) => Number(b.created_at) - Number(a.created_at));
-            const results = allMemories.slice(0, limit).map((row) => ({
-                id: row.id,
-                memory: row.content,
-                similarity: 1.0,
-                tags: row.tags || [],
-                metadata: row.metadata || {},
-                containerTag: row.container_tag,
-                displayName: row.display_name,
-                userName: row.user_name,
-                userEmail: row.user_email,
-                projectPath: row.project_path,
-                projectName: row.project_name,
-                gitRepoUrl: row.git_repo_url,
-                createdAt: row.created_at,
-            }));
+            const results = await readSessionMemories(sessionID, containerTag, limit, kind);
             return { success: true, results, total: results.length, timing: 0 };
         }
         catch (error) {

package/dist/services/deduplication-service.js

@@ -6,6 +6,7 @@ import { CONFIG } from "../config.js";
 import { log } from "./logger.js";
 import { cosineSimilarity } from "../utils/math.js";
 import { parseExtractedVector } from "./turso/vector-utils.js";
+import { memoryKindPredicate } from "./memory-kind.js";
 export class DeduplicationService {
     isRunning = false;
     async detectAndRemoveDuplicates() {
@@ -25,7 +26,17 @@ export class DeduplicationService {
             const nearDuplicateGroups = [];
             for (const shard of allShards) {
                 const db = await tursoConnectionManager.getConnection(shard.dbPath);
-                const memories = await tursoVectorSearch.getAllMemoriesWithExtractedVectors(db);
+                const memories = await db.all(`
+          SELECT
+            id,
+            content,
+            container_tag,
+            created_at,
+            vector_extract(vector) AS vector_json
+          FROM memories
+          WHERE ${memoryKindPredicate()}
+          ORDER BY created_at DESC
+        `);
                 const contentMap = new Map();
                 for (const memory of memories) {
                     const key = `${memory.container_tag}:${memory.content}`;

package/dist/services/global-config-writer.js

@@ -10,6 +10,7 @@ import { KEYWORD_MODES } from "../utils/keyword-boost.js";
 import { getMemoryLimitRule } from "../utils/memory-limits.js";
 import { OPENING_CONTEXT_QUERY_MAX_LENGTH } from "./injection-options-config.js";
 import { RERANKER_TIMEOUT_MAX_MS, RERANKER_TIMEOUT_MIN_MS } from "./request-timeouts.js";
+import { checkMemorisationSettingsEdits, memorisationSettingsFrom, } from "../core/memorisation-settings.js";
 const keys = new Set([
     "opencodeProvider",
     "opencodeModel",
@@ -53,6 +54,9 @@ const keys = new Set([
     "subagentMemory",
     "compaction.enabled",
     "compaction.memoryLimit",
+    "memorisationRepeat",
+    "memorisationMaxSize",
+    "memorisationSizeUnit",
 ]);
 function isFolder(path) {
     try {
@@ -112,6 +116,10 @@ function isValidEdit(key, value) {
     // keywordMode: null removes the key, so the mode follows the default again.
     if (key === "keywordMode")
         return value === null || KEYWORD_MODES.includes(value);
+    if (key === "memorisationSizeUnit")
+        return value === "characters" || value === "tokens";
+    if (key === "memorisationRepeat" || key === "memorisationMaxSize")
+        return true;
     // The opening context query: null removes it; an empty query means no opening search.
     if (key === "openingContextQuery") {
         return (value === null ||
@@ -270,6 +278,12 @@ options = {}) {
             throw new ConfigConflictError();
         }
         let content = original.content;
+        const errors = [];
+        const current = parse(content, errors, { allowTrailingComma: true });
+        if (errors.length || !current || typeof current !== "object" || Array.isArray(current)) {
+            throw new Error("Config contains invalid JSONC");
+        }
+        checkMemorisationSettingsEdits(edits, memorisationSettingsFrom(current));
         for (const [key, value] of Object.entries(edits)) {
             // A nested identifier maps to its JSONC leaf path, so chatMessage.maxMemories
             // and compaction.enabled write the leaf, never a literal dotted key.
@@ -286,7 +300,6 @@ options = {}) {
                 formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" },
             }));
         }
-        const errors = [];
         const parsed = parse(content, errors, { allowTrailingComma: true });
         if (errors.length)
             throw new Error("Config contains invalid JSONC");

package/dist/services/linked-search.d.ts

@@ -1,5 +1,6 @@
 import type { SearchResult } from "./turso/types.js";
 import type { KeywordMode } from "../utils/keyword-boost.js";
+import type { MemoryKind } from "./memory-kind.js";
 /**
  * Linked-space reads (design D6): the active space may link other spaces and
  * read their memories, read-only. This module holds every rule of that read:
@@ -15,6 +16,9 @@ export type LinkedScope = "project" | "all-projects";
 /** Options shared by the search and list reads: `includeLinked` reads linked spaces too (D6). */
 export interface MemoryReadOptions {
     includeLinked?: boolean;
+    kind?: MemoryKind;
+    /** Search only: the result limit for this read, instead of `maxMemories`. */
+    limit?: number;
 }
 /** The settings a linked search needs; the caller snapshots them from CONFIG. */
 export interface LinkedSearchSettings {
@@ -56,6 +60,7 @@ export interface ListedMemory {
     type: string | undefined;
     createdAt: string;
     metadata: Record<string, unknown> | undefined;
+    tags: string[];
     displayName: unknown;
     userName: unknown;
     userEmail: unknown;
@@ -77,6 +82,7 @@ export declare function searchLinkedSpaces(input: {
     ownCount: number;
     owner: LinkedOwner;
     settings: LinkedSearchSettings;
+    kind?: MemoryKind;
 }): Promise<{
     results: LinkedSearchResult[];
     warnings: string[];
@@ -89,6 +95,7 @@ export declare function listLinkedSpaces(input: {
     ownCount: number;
     owner: LinkedOwner;
     settings: LinkedSearchSettings;
+    kind?: MemoryKind;
 }): Promise<{
     memories: ListedMemory[];
     warnings: string[];
@@ -106,3 +113,11 @@ export declare function linkedRefusal(name: string): {
 export declare function findLinkedMemoryOwner(memoryId: string, owner: LinkedOwner, settings: LinkedSearchSettings): Promise<{
     name: string;
 } | null>;
+/**
+ * Reads one memory row by id from the linked spaces, with the space name. Read-only.
+ * A `containerTag` keeps only rows of that project; null accepts any project.
+ */
+export declare function readLinkedMemory(memoryId: string, owner: LinkedOwner, settings: LinkedSearchSettings, containerTag: string | null): Promise<{
+    name: string;
+    row: Record<string, unknown>;
+} | null>;

package/dist/services/linked-search.js

@@ -54,6 +54,7 @@ export function mapListedMemory(row) {
         type: row.type ? String(row.type) : undefined,
         createdAt: safeToISOString(row.created_at),
         metadata: safeJSONParse(row.metadata),
+        tags: typeof row.tags === "string" ? row.tags.split(",").filter(Boolean) : [],
         displayName: row.display_name,
         userName: row.user_name,
         userEmail: row.user_email,
@@ -143,7 +144,7 @@ export async function searchLinkedSpaces(input) {
             continue;
         }
         try {
-            const { results } = await tursoVectorSearch.searchAcrossShards(shards, input.queryVector, input.scope === "all-projects" ? "" : input.containerTag, room, input.settings.similarityThreshold, input.query, input.settings.keywordBoost, input.settings.keywordMode, (dbPath) => target.store.openShard(dbPath));
+            const { results } = await tursoVectorSearch.searchAcrossShards(shards, input.queryVector, input.scope === "all-projects" ? "" : input.containerTag, room, input.settings.similarityThreshold, input.query, input.settings.keywordBoost, input.settings.keywordMode, (dbPath) => target.store.openShard(dbPath), input.kind ?? "normal");
             linked.push(...results.map((result) => ({ ...result, spaceName: target.name })));
         }
         catch (error) {
@@ -174,7 +175,7 @@ export async function listLinkedSpaces(input) {
         try {
             for (const shard of shards) {
                 const db = await target.store.openShard(shard.dbPath);
-                const rows = await tursoVectorSearch.listMemories(db, input.scope === "all-projects" ? "" : input.containerTag, room);
+                const rows = await tursoVectorSearch.listMemories(db, input.scope === "all-projects" ? "" : input.containerTag, room, input.kind ?? "normal");
                 linked.push(...rows.map((row) => ({ ...mapListedMemory(row), spaceName: target.name })));
             }
         }
@@ -217,3 +218,23 @@ export async function findLinkedMemoryOwner(memoryId, owner, settings) {
     }
     return null;
 }
+/**
+ * Reads one memory row by id from the linked spaces, with the space name. Read-only.
+ * A `containerTag` keeps only rows of that project; null accepts any project.
+ */
+export async function readLinkedMemory(memoryId, owner, settings, containerTag) {
+    const warnings = [];
+    for (const target of await linkedTargets(owner, settings, warnings)) {
+        const shards = [
+            ...(await target.store.listShards("user", "")),
+            ...(await target.store.listShards("project", "")),
+        ];
+        for (const shard of shards) {
+            const db = await target.store.openShard(shard.dbPath);
+            const row = await db.get(`SELECT * FROM memories WHERE id = ? AND (? IS NULL OR container_tag = ?)`, [memoryId, containerTag, containerTag]);
+            if (row)
+                return { name: target.name, row };
+        }
+    }
+    return null;
+}

package/dist/services/live-captured-entries.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { CONFIG } from "../config.js";
 import { tursoConnectionManager } from "./turso/connection-manager.js";
 import { tursoShardManager } from "./turso/shard-manager.js";
+import { memoryKindPredicate } from "./memory-kind.js";
 /** Read user and assistant IDs saved by live capture in one project session. */
 export async function findLiveCapturedEntryIds(projectHash, host, sessionId) {
     const entries = new Set();
@@ -11,7 +12,7 @@ export async function findLiveCapturedEntryIds(projectHash, host, sessionId) {
     const shards = await tursoShardManager.getAllShards("project", projectHash);
     for (const shard of shards) {
         const db = await tursoConnectionManager.getConnection(shard.dbPath);
-        const rows = await db.all(`SELECT metadata FROM memories WHERE json_valid(metadata)
+        const rows = await db.all(`SELECT metadata FROM memories WHERE json_valid(metadata) AND ${memoryKindPredicate()}
        AND json_extract(metadata, '$.host') = ?
        AND json_extract(metadata, '$.hostSessionId') = ?
        AND json_extract(metadata, '$.sourceType') != 'history-import'`, [host, sessionId]);

package/dist/services/memorisation-routes.d.ts

@@ -0,0 +1,16 @@
+import type { MemoryScope } from "./client.js";
+import type { RouteResult } from "./chat/chat-routes.js";
+import type { LinkedSearchSettings } from "./linked-search.js";
+/** The CONFIG values recall needs. The route registration builds them, so this module has no CONFIG import. */
+export interface MemorisationRouteConfig {
+    defaultScope: MemoryScope | undefined;
+    linked: LinkedSearchSettings;
+}
+/**
+ * Routes for the Memorisation page. Returns undefined for paths it does not own.
+ * `GET /api/memorisations?tags=a,b` lists, `GET /api/memorisations/recall?q=&tags=` recalls
+ * and `POST /api/memorisations/bulk-delete` deletes. The general `/api/memories` delete
+ * routes refuse memorisations by design, so this module owns the bulk delete. Memorisation
+ * text is returned to the page and never written to the log.
+ */
+export declare function routeMemorisations(path: string, method: string, url: URL, cwd: string, config: MemorisationRouteConfig, readBody?: () => Promise<any>): Promise<RouteResult | undefined>;

package/dist/services/memorisation-routes.js

@@ -0,0 +1,94 @@
+import { isMemorisationId, parseTagList, visibleTags } from "../core/memorisation.js";
+/** Enough for any project: a memorisation is capped in size, and the user saves each on purpose. */
+const LIST_LIMIT = 200;
+/** The most IDs one bulk delete takes. */
+const BULK_DELETE_MAX = 500;
+const ok = (data) => ({ status: 200, body: { success: true, data } });
+const fail = (status, error) => ({
+    status,
+    body: { success: false, error },
+});
+/**
+ * Routes for the Memorisation page. Returns undefined for paths it does not own.
+ * `GET /api/memorisations?tags=a,b` lists, `GET /api/memorisations/recall?q=&tags=` recalls
+ * and `POST /api/memorisations/bulk-delete` deletes. The general `/api/memories` delete
+ * routes refuse memorisations by design, so this module owns the bulk delete. Memorisation
+ * text is returned to the page and never written to the log.
+ */
+export async function routeMemorisations(path, method, url, cwd, config, readBody) {
+    const wanted = parseTagList(url.searchParams.get("tags") ?? undefined);
+    if (method === "GET" && path === "/api/memorisations")
+        return listMemorisations(cwd, wanted);
+    if (method === "GET" && path === "/api/memorisations/recall") {
+        return recall(url.searchParams, wanted, cwd, config);
+    }
+    if (method === "POST" && path === "/api/memorisations/bulk-delete" && readBody) {
+        return bulkDelete(await readBody(), cwd, config);
+    }
+    return undefined;
+}
+async function listMemorisations(cwd, wanted) {
+    const [{ listMemorisationsByTags }, { getTags }] = await Promise.all([
+        import("./memorisation-store.js"),
+        import("./tags.js"),
+    ]);
+    const result = await listMemorisationsByTags(getTags(cwd).project.tag, wanted, "project", LIST_LIMIT);
+    if (!result.success)
+        return fail(500, result.error);
+    const memorisations = result.memories.map((memory) => ({
+        id: memory.id,
+        content: memory.summary,
+        createdAt: memory.createdAt,
+        host: typeof memory.metadata?.host === "string" ? memory.metadata.host : undefined,
+        kind: typeof memory.metadata?.memorisation === "string" ? memory.metadata.memorisation : undefined,
+        space: memory.spaceName,
+        tags: visibleTags(memory.tags),
+    }));
+    return ok({ memorisations });
+}
+async function recall(params, wanted, cwd, config) {
+    const text = params.get("q")?.trim();
+    if (!text && wanted.length === 0)
+        return fail(400, "q or tags required: an ID, text or labels");
+    const limit = Number(params.get("limit"));
+    const [{ runRecall }, { getTags }] = await Promise.all([
+        import("../core/memorisation-operations.js"),
+        import("./tags.js"),
+    ]);
+    const result = await runRecall({
+        query: text,
+        tags: wanted.join(","),
+        ...(Number.isInteger(limit) && limit > 0 ? { limit } : {}),
+    }, getTags(cwd), config.defaultScope, config.linked);
+    if (result.success !== true) {
+        // An unknown ID is a missing record. Any other refusal is a server problem.
+        const error = String(result.error ?? "Recall failed");
+        return fail(error.startsWith("No memorisation has the ID") ? 404 : 500, error);
+    }
+    return ok({ count: result.count, matches: result.matches });
+}
+/** Deletes memorisations of this project from the active space. Linked spaces are never touched. */
+async function bulkDelete(body, cwd, config) {
+    const ids = body?.ids;
+    if (!Array.isArray(ids) ||
+        ids.length < 1 ||
+        ids.length > BULK_DELETE_MAX ||
+        !ids.every((id) => typeof id === "string" && isMemorisationId(id))) {
+        return fail(400, `ids must be 1 to ${BULK_DELETE_MAX} memorisation IDs (ms-xxxxxx)`);
+    }
+    const [{ deleteMemorisation }, { getTags }] = await Promise.all([
+        import("./memorisation-store.js"),
+        import("./tags.js"),
+    ]);
+    const containerTag = getTags(cwd).project.tag;
+    const deleted = [];
+    const skipped = [];
+    for (const id of new Set(ids)) {
+        const outcome = await deleteMemorisation(id, containerTag, config.linked);
+        if (outcome === "deleted")
+            deleted.push(id);
+        else
+            skipped.push({ id, reason: outcome });
+    }
+    return ok({ deleted, skipped });
+}

package/dist/services/memorisation-store.d.ts

@@ -0,0 +1,45 @@
+import { type LinkedSearchSettings, type ListedMemory } from "./linked-search.js";
+import type { MemoryScope } from "./client.js";
+export interface StoredMemorisation {
+    id: string;
+    content: string;
+    createdAt: string;
+    /** The labels: the stored tags without the fixed memorisation tag. */
+    tags: string[];
+    /** Set when the record lives in a linked, read-only space. */
+    space?: string;
+}
+/**
+ * Looks a memorisation up by exact ID in the active space, then in the linked spaces. Only
+ * rows of the given project are returned, the same rule as text recall and list.
+ * The caller snapshots `linked` from CONFIG, so this module never imports it.
+ */
+export declare function getMemorisationById(id: string, containerTag: string, linked: LinkedSearchSettings): Promise<StoredMemorisation | null>;
+/**
+ * True when any project in the active or a linked space already uses this memorisation ID.
+ * A new ID must be free everywhere, so this check ignores the project.
+ */
+export declare function memorisationIdTaken(id: string, linked: LinkedSearchSettings): Promise<boolean>;
+/** The newest session snapshot of one host session in the project, or null. */
+export declare function findSnapshotByHostSession(hostSessionId: string, containerTag: string): Promise<{
+    id: string;
+} | null>;
+/**
+ * The project's memorisations that carry every tag in `tags`, newest first, in the active
+ * space and its linked spaces. The tag filter runs before `limit`, so an old labelled
+ * row is not pushed out by newer rows without the label.
+ */
+export declare function listMemorisationsByTags(containerTag: string, tags: string[], scope: MemoryScope, limit: number): Promise<{
+    success: true;
+    memories: ListedMemory[];
+} | {
+    success: false;
+    error: string;
+}>;
+export type MemorisationDeleteOutcome = "deleted" | "not-found" | "linked" | "not-memorisation";
+/**
+ * Deletes one memorisation of this project from the active space. A row of another project,
+ * or no row, is "not-found". A row of another type is kept ("not-memorisation"). A row that
+ * lives only in a linked, read-only space is "linked" and is never touched.
+ */
+export declare function deleteMemorisation(id: string, containerTag: string, linked: LinkedSearchSettings): Promise<MemorisationDeleteOutcome>;

package/dist/services/memorisation-store.js

@@ -0,0 +1,120 @@
+import { hasAllTags, visibleTags } from "../core/memorisation.js";
+import { activeOwner } from "./active-space-access.js";
+import { readLinkedMemory } from "./linked-search.js";
+import { extractScopeFromContainerTag } from "./memory-scope.js";
+import { memoryClient } from "./client.js";
+import { tursoConnectionManager } from "./turso/connection-manager.js";
+import { tursoShardManager } from "./turso/shard-manager.js";
+import { tursoVectorSearch } from "./turso/vector-search.js";
+function toStored(row, space) {
+    const created = Number(row.created_at);
+    return {
+        id: String(row.id),
+        content: String(row.content),
+        createdAt: new Date(Number.isFinite(created) ? created : 0).toISOString(),
+        tags: visibleTags(typeof row.tags === "string" ? row.tags.split(",") : []),
+        ...(space ? { space } : {}),
+    };
+}
+/** The active-space row with this ID, in any project, or null. */
+async function findActiveRow(id) {
+    await memoryClient.ensureStorageReady();
+    const shards = [
+        ...(await tursoShardManager.getAllShards("user", "")),
+        ...(await tursoShardManager.getAllShards("project", "")),
+    ];
+    for (const shard of shards) {
+        const db = await tursoConnectionManager.getConnection(shard.dbPath);
+        const row = await tursoVectorSearch.getMemoryById(db, id);
+        if (row)
+            return row;
+    }
+    return null;
+}
+/**
+ * Looks a memorisation up by exact ID in the active space, then in the linked spaces. Only
+ * rows of the given project are returned, the same rule as text recall and list.
+ * The caller snapshots `linked` from CONFIG, so this module never imports it.
+ */
+export async function getMemorisationById(id, containerTag, linked) {
+    const row = await findActiveRow(id);
+    if (row?.container_tag === containerTag && row.type === "memorisation")
+        return toStored(row);
+    const found = await readLinkedMemory(id, activeOwner(), linked, containerTag);
+    return found?.row.type === "memorisation" ? toStored(found.row, found.name) : null;
+}
+/**
+ * True when any project in the active or a linked space already uses this memorisation ID.
+ * A new ID must be free everywhere, so this check ignores the project.
+ */
+export async function memorisationIdTaken(id, linked) {
+    if ((await findActiveRow(id))?.type === "memorisation")
+        return true;
+    const found = await readLinkedMemory(id, activeOwner(), linked, null);
+    return found?.row.type === "memorisation";
+}
+/** The newest session snapshot of one host session in the project, or null. */
+export async function findSnapshotByHostSession(hostSessionId, containerTag) {
+    await memoryClient.ensureStorageReady();
+    const { scope, hash } = extractScopeFromContainerTag(containerTag);
+    let newest = null;
+    for (const shard of await tursoShardManager.getAllShards(scope, hash)) {
+        const db = await tursoConnectionManager.getConnection(shard.dbPath);
+        const row = await db.get(`SELECT id, created_at FROM memories
+       WHERE type = 'memorisation'
+         AND container_tag = ?
+         AND json_extract(metadata, '$.memorisation') = 'snapshot'
+         AND json_extract(metadata, '$.hostSessionId') = ?
+       ORDER BY created_at DESC LIMIT 1`, [containerTag, hostSessionId]);
+        if (row && (!newest || Number(row.created_at) > newest.createdAt)) {
+            newest = { id: String(row.id), createdAt: Number(row.created_at) };
+        }
+    }
+    return newest ? { id: newest.id } : null;
+}
+/** Far above any real project: a memorisation is capped in size and the user saves each on purpose. */
+const READ_CEILING = 10_000;
+/**
+ * The project's memorisations that carry every tag in `tags`, newest first, in the active
+ * space and its linked spaces. The tag filter runs before `limit`, so an old labelled
+ * row is not pushed out by newer rows without the label.
+ */
+export async function listMemorisationsByTags(containerTag, tags, scope, limit) {
+    const result = await memoryClient.listMemories(containerTag, READ_CEILING, scope, {
+        includeLinked: true,
+        kind: "memorisation",
+    });
+    if (!result.success)
+        return { success: false, error: result.error };
+    const memories = result.memories
+        .filter((memory) => hasAllTags(memory.tags, tags))
+        // Own rows come first from the client, then linked rows. Callers want one timeline.
+        .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())
+        .slice(0, limit);
+    return { success: true, memories };
+}
+/**
+ * Deletes one memorisation of this project from the active space. A row of another project,
+ * or no row, is "not-found". A row of another type is kept ("not-memorisation"). A row that
+ * lives only in a linked, read-only space is "linked" and is never touched.
+ */
+export async function deleteMemorisation(id, containerTag, linked) {
+    await memoryClient.ensureStorageReady();
+    const shards = [
+        ...(await tursoShardManager.getAllShards("user", "")),
+        ...(await tursoShardManager.getAllShards("project", "")),
+    ];
+    for (const shard of shards) {
+        const db = await tursoConnectionManager.getConnection(shard.dbPath);
+        const row = await tursoVectorSearch.getMemoryById(db, id);
+        if (!row || row.container_tag !== containerTag)
+            continue;
+        if (row.type !== "memorisation")
+            return "not-memorisation";
+        await tursoVectorSearch.deleteVector(db, id);
+        await tursoShardManager.decrementVectorCount(shard.id);
+        return "deleted";
+    }
+    const found = await readLinkedMemory(id, activeOwner(), linked, containerTag);
+    return found?.row.type === "memorisation" ? "linked" : "not-found";
+}

package/dist/services/memory-kind.d.ts

@@ -0,0 +1,6 @@
+/** The records an ordinary memory read includes. Memorisations need an explicit request. */
+export type MemoryKind = "normal" | "memorisation";
+/** Appends the record-kind predicate before the query's result limit. */
+export declare function memoryKindPredicate(column?: string, kind?: MemoryKind): string;
+/** Untagged normal memories eligible for AI tag backfill. */
+export declare const UNTAGGED_NORMAL_PREDICATE: string;

package/dist/services/memory-kind.js

@@ -0,0 +1,6 @@
+/** Appends the record-kind predicate before the query's result limit. */
+export function memoryKindPredicate(column = "type", kind = "normal") {
+    return kind === "memorisation" ? `${column} = 'memorisation'` : `${column} IS NOT 'memorisation'`;
+}
+/** Untagged normal memories eligible for AI tag backfill. */
+export const UNTAGGED_NORMAL_PREDICATE = `(tags IS NULL OR tags = '') AND ${memoryKindPredicate()}`;

package/dist/services/memory-portability-service.js

@@ -78,7 +78,8 @@ export class MemoryPortabilityService {
             if (!existsSync(shard.dbPath))
                 continue;
             const db = await tursoConnectionManager.getConnection(shard.dbPath);
-            const rows = await tursoVectorSearch.getAllMemories(db);
+            // An export keeps every kind, memorisations included.
+            const rows = await tursoVectorSearch.getAllMemories(db, "all");
             for (const row of rows) {
                 const exported = rowToExportedMemory(row);
                 if (exported)