@snoai/memory 0.0.0-stage → 1.0.0

package/dist/model-reply-text-CKopStP2.js

@@ -0,0 +1,334 @@
+//#region src/model/llm-json-utils.ts
+/** @file llm-json-utils.ts
+* @purpose Extracts and repairs JSON returned by LLM providers.
+* @boundary Response-text normalization only; schema validation remains with callers.
+*/
+/**
+* Extract JSON from an LLM response that may be wrapped in markdown fences
+* or contain surrounding text.
+*/
+function extractJsonFromResponse(text) {
+	for (const fence of text.matchAll(/```(?:json)?\s*\n?([\s\S]*?)```/g)) {
+		const body = (fence[1] ?? "").trim();
+		if (isRecoverableJson(body)) return body;
+	}
+	let searchFrom = 0;
+	while (searchFrom < text.length) {
+		const slice = balancedSliceFrom(text, searchFrom);
+		if (slice === null || slice.text === null) return null;
+		if (isRecoverableJson(slice.text)) return slice.text;
+		searchFrom = slice.start + 1;
+	}
+	return null;
+}
+/** True when the slice is JSON or the existing repair pass can make it JSON. */
+function isRecoverableJson(candidate) {
+	try {
+		JSON.parse(candidate);
+		return true;
+	} catch {
+		const repaired = repairCommonJson(candidate);
+		if (repaired === candidate) return false;
+		try {
+			JSON.parse(repaired);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+}
+/** The first balanced `{...}` or `[...]` at or after `from`, with the index it started at. */
+function balancedSliceFrom(text, from) {
+	const start = firstContainerIndex(text, from);
+	if (start === -1) return null;
+	const opener = text[start];
+	const closer = opener === "[" ? "]" : "}";
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === void 0) continue;
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = inString;
+			continue;
+		}
+		if (ch === "\"") {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (ch === opener) depth++;
+		else if (ch === closer) {
+			depth--;
+			if (depth === 0) return {
+				text: text.substring(start, i + 1),
+				start
+			};
+		}
+	}
+	return {
+		text: null,
+		start
+	};
+}
+/** First `{` or `[` that is not inside a string, or -1. */
+function firstContainerIndex(text, from = 0) {
+	let inString = false;
+	let escaped = false;
+	for (let i = from; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === void 0) continue;
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (ch === "\\") {
+			escaped = inString;
+			continue;
+		}
+		if (ch === "\"") {
+			inString = !inString;
+			continue;
+		}
+		if (inString) continue;
+		if (ch === "{" || ch === "[") return i;
+	}
+	return -1;
+}
+/** Implements preview text as the local LLM transport operation. */
+function previewText(value, maxLen = 200) {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	if (normalized.length <= maxLen) return normalized;
+	return `${normalized.slice(0, maxLen - 3)}...`;
+}
+/** Implements next non whitespace char as the local LLM transport operation. */
+function nextNonWhitespaceChar(text, start) {
+	for (let i = start; i < text.length; i++) {
+		const ch = text[i];
+		if (ch !== void 0 && !/\s/.test(ch)) return ch;
+	}
+}
+/**
+* Best-effort repair for common LLM JSON issues:
+* - unescaped quotes inside string values
+* - raw newlines / tabs inside strings
+* - trailing commas before } or ]
+*/
+function repairCommonJson(text) {
+	let result = "";
+	let inString = false;
+	let escaped = false;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === void 0) continue;
+		if (escaped) {
+			result += ch;
+			escaped = false;
+			continue;
+		}
+		if (inString) {
+			if (ch === "\\") {
+				result += ch;
+				escaped = true;
+				continue;
+			}
+			if (ch === "\"") {
+				const nextCh = nextNonWhitespaceChar(text, i + 1);
+				if (nextCh === void 0 || nextCh === "," || nextCh === "}" || nextCh === "]" || nextCh === ":") {
+					result += ch;
+					inString = false;
+				} else result += "\\\"";
+				continue;
+			}
+			if (ch === "\n") {
+				result += "\\n";
+				continue;
+			}
+			if (ch === "\r") {
+				result += "\\r";
+				continue;
+			}
+			if (ch === "	") {
+				result += "\\t";
+				continue;
+			}
+			result += ch;
+			continue;
+		}
+		if (ch === "\"") {
+			result += ch;
+			inString = true;
+			continue;
+		}
+		if (ch === ",") {
+			const nextCh = nextNonWhitespaceChar(text, i + 1);
+			if (nextCh === "}" || nextCh === "]") continue;
+		}
+		result += ch;
+	}
+	return result;
+}
+//#endregion
+//#region src/engine/shared/model-reply-text.ts
+/** @file model-reply-text.ts
+* @purpose Turns one raw model reply into the ordered JSON payload candidates a caller may accept.
+* @boundary Response-text normalization only; the caller owns every schema decision.
+*/
+/**
+* Balanced container starting at `start`, or undefined when it never closes.
+*
+* String state is tracked so a brace inside a string value does not close the container.
+*/
+function balancedEnd(text, start) {
+	let inString = false;
+	let escaped = false;
+	const stack = [];
+	for (let index = start; index < text.length; index += 1) {
+		const char = text[index];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			continue;
+		}
+		if (char === "{" || char === "[") stack.push(char);
+		else if (char === "}" || char === "]") {
+			const opening = stack.at(-1);
+			if (opening === "{" && char !== "}" || opening === "[" && char !== "]") return void 0;
+			stack.pop();
+			if (stack.length === 0) return index + 1;
+		}
+	}
+}
+/**
+* Every top-level balanced container, NON-OVERLAPPING.
+*
+* Resuming after each container instead of scanning from every index is what keeps the scan out of
+* string values. Measured 2026-09-04 on a live reply that echoed the transcript back —
+* `[{"role":"assistant","content":"{\"records\":[]}"}]` — the per-index scan offered the escaped
+* inner `{"records":[]}` as a candidate and it passed the caller's schema, so an echoed turn was
+* about to be recorded as "nothing to record" and its real content lost.
+*/
+function balancedSpans(text) {
+	const spans = [];
+	let start = 0;
+	while (start < text.length) {
+		const char = text[start];
+		if (char !== "{" && char !== "[") {
+			start += 1;
+			continue;
+		}
+		const end = balancedEnd(text, start);
+		if (end === void 0) {
+			start += 1;
+			continue;
+		}
+		spans.push({
+			start,
+			end
+		});
+		start = end;
+	}
+	return spans;
+}
+/**
+* Spans of every JSON string literal in `text`, so a tag the user typed can be told apart from a
+* tag the model wrote. Unterminated strings are ignored: only closed literals are protected.
+*/
+function stringSpans(text) {
+	const spans = [];
+	let start = -1;
+	let escaped = false;
+	for (let index = 0; index < text.length; index += 1) {
+		const char = text[index];
+		if (start === -1) {
+			if (char === "\"") start = index;
+			continue;
+		}
+		if (escaped) escaped = false;
+		else if (char === "\\") escaped = true;
+		else if (char === "\"") {
+			spans.push({
+				start,
+				end: index + 1
+			});
+			start = -1;
+		}
+	}
+	return spans;
+}
+const THINK_BLOCK = /<think>[\s\S]*?<\/think>|<think>[\s\S]*$/giu;
+/**
+* Removes think blocks unless they start inside a JSON string literal.
+*
+* The rule is "is this tag part of someone's data", not "does this block contain JSON". Keying on
+* whether the block overlapped a balanced container kept exactly the dangerous case: a model that
+* drafts a wrong payload inside `<think>` and writes the right one after it — measured, the draft
+* was returned as candidate 0 and won. A `<think>` inside a string value is user content and is
+* left byte-identical.
+*/
+function stripThinkOutsideCandidates(raw) {
+	const protectedSpans = stringSpans(raw);
+	const inString = (index) => protectedSpans.some((span) => index >= span.start && index < span.end);
+	let out = "";
+	let cursor = 0;
+	THINK_BLOCK.lastIndex = 0;
+	for (const match = { value: THINK_BLOCK.exec(raw) }; match.value !== null; match.value = THINK_BLOCK.exec(raw)) {
+		const at = match.value.index;
+		if (inString(at)) continue;
+		out += raw.slice(cursor, at);
+		cursor = at + match.value[0].length;
+	}
+	return out + raw.slice(cursor);
+}
+function fencedBlocks(text) {
+	return [...text.matchAll(/```(?:json)?\s*\n?([\s\S]*?)```/gu)].map((match) => (match[1] ?? "").trim()).filter((body) => body.length > 0);
+}
+/**
+* The JSON payload candidates in one reply, in the order a caller should try them.
+*
+* Fenced blocks first: a model that fences its answer fences the answer, not its commentary.
+* Then the non-overlapping balanced containers. Each candidate appears as written and, when it
+* does not parse, once more repaired.
+*/
+function modelReplyJsonCandidates(raw) {
+	const text = stripThinkOutsideCandidates(raw).trim();
+	const ordered = [...fencedBlocks(text), ...balancedSpans(text).map((span) => text.slice(span.start, span.end))];
+	const candidates = [];
+	for (const candidate of ordered) {
+		if (!candidates.includes(candidate)) candidates.push(candidate);
+		const repaired = repairCommonJson(candidate);
+		if (repaired !== candidate && !candidates.includes(repaired)) candidates.push(repaired);
+	}
+	return candidates;
+}
+/**
+* The first candidate `accept` admits, or undefined when none does.
+*
+* The caller decides what a payload is. Handing back a single "best" candidate instead let a
+* syntactically valid but wrong-shaped example consume the caller's only chance while the real
+* payload sat behind it.
+*/
+function readModelReplyJson(raw, accept) {
+	for (const candidate of modelReplyJsonCandidates(raw)) {
+		let parsed;
+		try {
+			parsed = JSON.parse(candidate);
+		} catch {
+			continue;
+		}
+		const admitted = accept(parsed);
+		if (admitted !== void 0) return admitted;
+	}
+}
+//#endregion
+export { repairCommonJson as a, previewText as i, readModelReplyJson as n, extractJsonFromResponse as r, modelReplyJsonCandidates as t };

package/dist/observable-embedder-DQnNgf9O.d.ts

@@ -0,0 +1,17 @@
+import { n as PluginObservability } from "./adapter-DMEmCTKo.js";
+import { r as EmbeddingConfig, t as Embedder } from "./embedding-provider-client-vynZMuit.js";
+//#region src/engine/observability/observable-embedder.d.ts
+type SessionUuidProvider = () => string | undefined;
+declare class ObservableEmbedder extends Embedder {
+  private readonly observability;
+  private readonly sessionUuidProvider;
+  private readonly observationScope;
+  constructor(config: EmbeddingConfig, stateDir: string, observability: PluginObservability, sessionUuidProvider: SessionUuidProvider);
+  override embed(text: string): Promise<Float32Array>;
+  protected override embedDirect(text: string): Promise<Float32Array>;
+  override embedMany(values: string[]): Promise<Float32Array[]>;
+  override embedChunks(texts: string[]): Promise<Float32Array[]>;
+  private observeEmbedding;
+}
+//#endregion
+export { ObservableEmbedder as t };

package/dist/observable-llm-client-uwqPADpN.d.ts

@@ -0,0 +1,21 @@
+import { i as LlmClientConfig, r as LlmClient, s as MemoryLlmRequest } from "./plugin-config-schema-C0UUbOmG.js";
+import { n as PluginObservability } from "./adapter-DMEmCTKo.js";
+import "./llm-client-DOTSGzhe.js";
+//#region src/engine/observability/observable-llm-client.d.ts
+type SessionUuidProvider = () => string | undefined;
+declare class ObservableLlmClient implements LlmClient {
+  private readonly inner;
+  private readonly config;
+  private readonly observability;
+  private readonly sessionUuidProvider;
+  private readonly usageMutex;
+  constructor(inner: LlmClient, config: Pick<LlmClientConfig, "preset" | "routing">, observability: PluginObservability, sessionUuidProvider: SessionUuidProvider);
+  completeJson<T>(request: MemoryLlmRequest): Promise<T | null>;
+  completeText(request: MemoryLlmRequest): Promise<string | null>;
+  private observeCall;
+  getResolvedConfig(): ReturnType<LlmClient["getResolvedConfig"]>;
+  getLastError(): string | null;
+  getLastUsage(): ReturnType<LlmClient["getLastUsage"]>;
+}
+//#endregion
+export { ObservableLlmClient as t };

package/dist/observable-memory-store-BaZKbhgq.d.ts

@@ -0,0 +1,73 @@
+import { b as MemoryTier, g as MemoryEntry, v as MemoryMetadata, y as MemorySearchResult } from "./types-DxKqU60b.js";
+import { n as PluginObservability } from "./adapter-DMEmCTKo.js";
+import { r as EmbeddingConfig } from "./embedding-provider-client-vynZMuit.js";
+import { C as MemoryStore, F as TaskLifecycleBatchWriteResult, M as SupersedeClose, N as SupersedePreserveExisting, P as TaskLifecycleBatchWriteInput, at as ListOptions, dt as RecordUnplacedCandidateResult, f as AtomicExtractionWriteResult, ft as SearchOptions, gt as StoreResult, ht as StoreInput, j as SupersedeActiveFactGuard, mt as StoreConfig, ot as MemoryRow, rt as ChunkSearchResult, u as AtomicExtractionWriteInput, ut as RecordUnplacedCandidateInput, w as MemoryStoreInternals, yt as UpdateChanges } from "./memory-store-base-XRA4S9Xl.js";
+import "./store-2pM0-dZg.js";
+//#region src/engine/observability/observable-memory-store.d.ts
+type SessionUuidProvider = () => string | undefined;
+declare class ObservableMemoryStore extends MemoryStore {
+  private readonly observability;
+  private readonly sessionUuidProvider;
+  private readonly embeddingConfig;
+  constructor(config: StoreConfig, observability: PluginObservability, sessionUuidProvider: SessionUuidProvider, embeddingConfig: Pick<EmbeddingConfig, "provider" | "model">);
+  override store(entry: StoreInput): Promise<StoreResult>;
+  override storeAtomicExtractionChunk(input: AtomicExtractionWriteInput): Promise<AtomicExtractionWriteResult>;
+  override applyTaskLifecycleBatchWithAtomicWrite(input: TaskLifecycleBatchWriteInput): Promise<TaskLifecycleBatchWriteResult>;
+  private emitCreatedWrites;
+  override update(id: string, changes: UpdateChanges): Promise<MemoryEntry | null>;
+  override bulkStore(entries: Array<StoreInput | null | undefined>): Promise<StoreResult[]>;
+  override supersede(args: {
+    create: StoreInput;
+    closes: SupersedeClose[];
+    activeFactGuard?: SupersedeActiveFactGuard;
+    preserveExisting?: SupersedePreserveExisting;
+  }): Promise<StoreResult>;
+  override createMergeWithRawLineage(args: Parameters<MemoryStore["createMergeWithRawLineage"]>[0]): ReturnType<MemoryStore["createMergeWithRawLineage"]>;
+  override createEventAndSupersede(args: Parameters<MemoryStore["createEventAndSupersede"]>[0]): ReturnType<MemoryStore["createEventAndSupersede"]>;
+  override importEntry(entry: Parameters<MemoryStore["importEntry"]>[0]): ReturnType<MemoryStore["importEntry"]>;
+  backfillMissingChunks(): Promise<number>;
+  override findByContentHash(hash: string, projectId?: string): MemoryEntry | undefined;
+  override findByExtractionIdempotencyKey(projectId: string, key: string): MemoryEntry | undefined;
+  /**
+   * Audited like a write, because it is one — a preserved failure that leaves no
+   * audit trail is a write nobody can find afterwards.
+   */
+  override recordUnplacedCandidate(input: RecordUnplacedCandidateInput): RecordUnplacedCandidateResult;
+  override getById(id: string): MemoryEntry | undefined;
+  override getByFactKey(projectId: string, factKey: string): MemoryEntry | undefined;
+  override hasId(id: string): Promise<boolean>;
+  override searchChunksSemantic(vector: Float32Array, opts: SearchOptions): Promise<ChunkSearchResult[]>;
+  override searchChunksKeyword(query: string, opts: SearchOptions): Promise<ChunkSearchResult[]>;
+  override searchSemantic(vector: Float32Array, opts?: SearchOptions): Promise<MemorySearchResult[]>;
+  override searchKeyword(query: string, opts?: SearchOptions): Promise<MemorySearchResult[]>;
+  fetchMemoriesInOrder(memoryIds: string[], opts?: SearchOptions): MemoryRow[];
+  override getVectorsByIds(ids: string[]): Map<string, Float32Array>;
+  override getChunksByParent(memoryIds: string[], facetPolicy?: SearchOptions["facetPolicy"]): Map<string, Array<{
+    chunkIndex: number;
+    chunkText: string;
+    facet: "current" | "history";
+  }>>;
+  override list(opts?: ListOptions): Promise<MemoryEntry[]>;
+  override listReflectionItems(opts: Parameters<MemoryStore["listReflectionItems"]>[0]): ReturnType<MemoryStore["listReflectionItems"]>;
+  override getMemoryMetadata(memoryId: string): Promise<MemoryMetadata | undefined>;
+  override updateTier(memoryId: string, newTier: MemoryTier, options?: {
+    writerAuthority?: "offline-family";
+  }): Promise<void>;
+  override updateMetadata(memoryId: string, patch: Partial<MemoryMetadata>): Promise<void>;
+  override applyMetadataDelta(memoryId: string, deltaFn: (current: MemoryMetadata) => Partial<MemoryMetadata>): Promise<void>;
+  override applyMetadataDeltas(entries: Parameters<MemoryStore["applyMetadataDeltas"]>[0]): Promise<void>;
+  override resolveReflectionItem(memoryId: string, opts: Parameters<MemoryStore["resolveReflectionItem"]>[1]): ReturnType<MemoryStore["resolveReflectionItem"]>;
+  override delete(idOrPrefix: string, options?: Parameters<MemoryStore["delete"]>[1]): Promise<number>;
+  override deleteMany(ids: string[], options?: Parameters<MemoryStore["deleteMany"]>[1]): Promise<number>;
+  deleteByIds(ids: string[], options?: Parameters<MemoryStoreInternals["deleteByIds"]>[1]): void;
+  override bulkDelete(filter: Parameters<MemoryStore["bulkDelete"]>[0], options?: Parameters<MemoryStore["bulkDelete"]>[1]): ReturnType<MemoryStore["bulkDelete"]>;
+  private auditEntryReadSync;
+  private auditSearch;
+  private auditMemorySearch;
+  private auditMetadataMutation;
+  private resolveDeleteIds;
+  private readExistingMemoryIds;
+  private emitWrite;
+}
+//#endregion
+export { ObservableMemoryStore as t };

package/dist/observable-retriever-Dt_NUxAA.d.ts

@@ -0,0 +1,23 @@
+import { x as RetrievalResult } from "./types-DxKqU60b.js";
+import { n as PluginObservability } from "./adapter-DMEmCTKo.js";
+import { r as EmbeddingConfig, t as Embedder } from "./embedding-provider-client-vynZMuit.js";
+import { d as RetrievalConfig, f as RetrievalContext, t as MemoryRetriever } from "./retriever-Ruk3zp7_.js";
+import { C as MemoryStore } from "./memory-store-base-XRA4S9Xl.js";
+import "./store-2pM0-dZg.js";
+//#region src/engine/observability/observable-retriever.d.ts
+type SessionUuidProvider = () => string | undefined;
+type RetrievalTraceResult = Awaited<ReturnType<MemoryRetriever["retrieveWithTrace"]>>;
+declare class ObservableMemoryRetriever extends MemoryRetriever {
+  private readonly observability;
+  private readonly sessionUuidProvider;
+  private readonly embeddingConfig;
+  constructor(store: MemoryStore, embedder: Embedder, logger: {
+    warn: (message: string, fields?: Record<string, unknown>) => void;
+  } | undefined, config: RetrievalConfig | undefined, observability: PluginObservability, sessionUuidProvider: SessionUuidProvider, embeddingConfig: Pick<EmbeddingConfig, "provider" | "model">);
+  override retrieve(context: RetrievalContext): Promise<RetrievalResult[]>;
+  override retrieveWithTrace(context: RetrievalContext): Promise<RetrievalTraceResult>;
+  private observeRead;
+  private emitRead;
+}
+//#endregion
+export { ObservableMemoryRetriever as t };

package/dist/operation-cancellation-CTKWwNHk.js

@@ -0,0 +1,81 @@
+import { createLogger } from "@snoai/utils/logger";
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/engine/operation-cancellation.ts
+const operations = new AsyncLocalStorage();
+const log = createLogger("sno-station-mem:cancellation");
+/** Carries cancellation through the existing nested extraction and reflection writers. */
+async function withMemoryOperation(method, signal, run) {
+	const operation = {
+		id: randomUUID(),
+		signal,
+		writes: 0,
+		transactionDepth: 0
+	};
+	return operations.run(operation, async () => {
+		try {
+			signal?.throwIfAborted();
+			const result = await run();
+			signal?.throwIfAborted();
+			return result;
+		} finally {
+			if (signal?.aborted) log.error("memory.operation.aborted", {
+				method,
+				outcome: "aborted",
+				writes: operation.writes
+			}, {
+				event_name: "memory.operation.aborted",
+				file: "packages/memory/src/engine/operation-cancellation.ts",
+				function: "withMemoryOperation",
+				site_id: "memory.operation.aborted"
+			});
+		}
+	});
+}
+function memoryOperationId() {
+	return operations.getStore()?.id;
+}
+function memoryOperationSignal(signal) {
+	const request = operations.getStore()?.signal;
+	if (!request) return signal;
+	if (!signal || request === signal) return request;
+	return AbortSignal.any([request, signal]);
+}
+function checkMemoryOperation() {
+	const operation = operations.getStore();
+	if (!operation?.transactionDepth) operation?.signal?.throwIfAborted();
+}
+/** One synchronous SQL statement; failed statements never count as completed writes. */
+function memoryWrite(write) {
+	checkMemoryOperation();
+	const result = write();
+	const operation = operations.getStore();
+	if (operation) operation.writes++;
+	return result;
+}
+/** A started transaction finishes atomically; rollback also restores its write count. */
+function memoryTransaction(transaction) {
+	checkMemoryOperation();
+	const operation = operations.getStore();
+	if (!operation) return transaction();
+	const writes = operation.writes;
+	operation.transactionDepth++;
+	try {
+		return transaction();
+	} catch (error) {
+		operation.writes = writes;
+		throw error;
+	} finally {
+		operation.transactionDepth--;
+	}
+}
+/** Do not cancel an in-progress file write; check before starting the next step. */
+async function memoryFileWrite(write) {
+	checkMemoryOperation();
+	const result = await write();
+	const operation = operations.getStore();
+	if (operation) operation.writes++;
+	return result;
+}
+//#endregion
+export { memoryTransaction as a, memoryOperationSignal as i, memoryFileWrite as n, memoryWrite as o, memoryOperationId as r, withMemoryOperation as s, checkMemoryOperation as t };

package/dist/paths-qVF-5uBq.d.ts

@@ -0,0 +1 @@
+import "./profile-TWPJ_myr.js";