@graphorin/memory 0.6.1 → 0.7.0

package/src/internal/contextualize.ts

@@ -0,0 +1,173 @@
+/**
+ * Contextual retrieval (P1-3). Before a memory is embedded / FTS-indexed
+ * the framework can prepend a short *situating context* (entities,
+ * timeframe, topics) so a terse fact like "moved there in March" stays
+ * findable by "Where did Anna relocate?". This mirrors Anthropic's
+ * Contextual Retrieval, applied to both the vector embedding *and* the
+ * lexical index, while the canonical `text` shown to the user / audit
+ * trail is left untouched.
+ *
+ * Three modes:
+ * - `'off'` - index the bare canonical text (pre-P1-3 behaviour).
+ * - `'late-chunk'` - the **offline default**: prepend a context derived
+ *   deterministically from the memory's own structured metadata. No LLM
+ *   call, so the local-first write path is unchanged in cost.
+ * - `'llm'` - an opt-in, **consolidator-only** enrichment: one cheap
+ *   provider call writes a 1-2 sentence situating prefix. Confined to the
+ *   background consolidator (never the hot write path); a failure or empty
+ *   completion degrades to {@link contextualize} so a write never wedges.
+ *
+ * @packageDocumentation
+ */
+
+import type { Provider, ProviderRequest, Usage } from '@graphorin/core';
+
+/**
+ * Contextual-retrieval mode. `'late-chunk'` is the offline default;
+ * `'llm'` is the opt-in, consolidator-only enrichment. P1-3.
+ *
+ * @stable
+ */
+export type ContextualRetrievalMode = 'off' | 'late-chunk' | 'llm';
+
+/**
+ * Structural subset of a fact / candidate consumed by the
+ * contextualizers. Only **author / extraction-supplied** signals are
+ * used - never framework-defaulted fields (e.g. a `validFrom` defaulted
+ * to write-time) and never opaque scope ids (random uuids would only
+ * add noise to the embedding). A candidate with no structured signals
+ * yields an empty context, so plain `remember({ text })` writes are
+ * left byte-identical.
+ *
+ * @internal
+ */
+export interface ContextualizeInput {
+  readonly text: string;
+  readonly subject?: string;
+  readonly predicate?: string;
+  readonly object?: string;
+  readonly tags?: ReadonlyArray<string>;
+  /** Author-set validity start (ISO-8601). Framework-defaulted values are *not* passed. */
+  readonly validFrom?: string;
+}
+
+const SITUATING_CONTEXT_SYSTEM_PROMPT = [
+  'You are a situating-context assistant for a long-running memory store.',
+  'Given one memory and any structured hints, write a single short sentence (≤ 25 words) that situates it - the entities, timeframe, and topic it concerns - so it can be retrieved later by a vaguely-worded question.',
+  'Do not restate the memory verbatim and do not add facts that are not implied. Return only the sentence, no preamble.',
+].join(' ');
+
+/**
+ * Build the deterministic situating-context prefix from a candidate's
+ * structured signals. Returns `''` when nothing useful is available so
+ * the caller can short-circuit to the canonical text.
+ *
+ * @internal
+ */
+export function buildSituatingContext(input: ContextualizeInput): string {
+  const parts: string[] = [];
+  const subject = trimToUndefined(input.subject);
+  const predicate = trimToUndefined(input.predicate);
+  const object = trimToUndefined(input.object);
+  if (subject !== undefined && predicate !== undefined && object !== undefined) {
+    parts.push(`${subject} ${predicate} ${object}`);
+  } else {
+    if (subject !== undefined) parts.push(subject);
+    if (object !== undefined) parts.push(object);
+  }
+  const validFrom = trimToUndefined(input.validFrom);
+  if (validFrom !== undefined) {
+    parts.push(`as of ${validFrom.length >= 10 ? validFrom.slice(0, 10) : validFrom}`);
+  }
+  const tags = (input.tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);
+  if (tags.length > 0) {
+    parts.push(`topics: ${tags.join(', ')}`);
+  }
+  if (parts.length === 0) return '';
+  return `[Context: ${parts.join('; ')}]`;
+}
+
+/**
+ * Late-chunking contextualizer (offline default). Prepends the
+ * deterministic situating context to the canonical text; a no-op when
+ * the candidate carries no structured signals. Pure - never calls a
+ * provider.
+ *
+ * @internal
+ */
+export function contextualize(input: ContextualizeInput): string {
+  const ctx = buildSituatingContext(input);
+  return ctx === '' ? input.text : `${ctx}\n${input.text}`;
+}
+
+const ZERO_USAGE: Usage = Object.freeze({
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0,
+});
+
+/** Result of the LLM-context enrichment - the index text plus call usage for budgeting. */
+export interface ContextualizeLlmResult {
+  readonly indexText: string;
+  readonly usage: Usage;
+}
+
+/**
+ * LLM-context contextualizer (opt-in, consolidator-only). Spends one
+ * cheap provider call to write a situating prefix, then prepends it to
+ * the canonical text. Resilient by design: an empty completion or a
+ * provider error degrades to {@link contextualize} (deterministic
+ * late-chunk) so the enrichment can never wedge a write. Returns the
+ * usage so the caller can record it against the budget.
+ *
+ * @internal
+ */
+export async function contextualizeWithLlm(
+  input: ContextualizeInput,
+  provider: Provider,
+  opts: { readonly signal?: AbortSignal } = {},
+): Promise<ContextualizeLlmResult> {
+  const request: ProviderRequest = {
+    messages: [{ role: 'user', content: buildSituatingUserPrompt(input) }],
+    systemMessage: SITUATING_CONTEXT_SYSTEM_PROMPT,
+    temperature: 0,
+    // MCON-14: per-call output cap - a one-sentence situating prefix.
+    maxTokens: 256,
+    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+  };
+  try {
+    const response = await provider.generate(request);
+    const prefix = (response.text ?? '').trim();
+    if (prefix.length === 0) {
+      return { indexText: contextualize(input), usage: response.usage };
+    }
+    return { indexText: `${prefix}\n${input.text}`, usage: response.usage };
+  } catch {
+    // Contextualization is an enhancement, not a correctness requirement -
+    // a provider failure must never wedge the underlying write. Fall back
+    // to the deterministic late-chunk prefix at zero cost.
+    return { indexText: contextualize(input), usage: ZERO_USAGE };
+  }
+}
+
+function buildSituatingUserPrompt(input: ContextualizeInput): string {
+  const hints: string[] = [];
+  const subject = trimToUndefined(input.subject);
+  const predicate = trimToUndefined(input.predicate);
+  const object = trimToUndefined(input.object);
+  if (subject !== undefined) hints.push(`subject=${subject}`);
+  if (predicate !== undefined) hints.push(`predicate=${predicate}`);
+  if (object !== undefined) hints.push(`object=${object}`);
+  const tags = (input.tags ?? []).map((t) => t.trim()).filter((t) => t.length > 0);
+  if (tags.length > 0) hints.push(`tags=${tags.join(', ')}`);
+  const validFrom = trimToUndefined(input.validFrom);
+  if (validFrom !== undefined) hints.push(`validFrom=${validFrom}`);
+  const hintLine = hints.length > 0 ? `\nStructured hints: ${hints.join('; ')}` : '';
+  return `Memory: ${input.text}${hintLine}`;
+}
+
+function trimToUndefined(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? undefined : trimmed;
+}

package/src/internal/embedder-binding.ts

@@ -0,0 +1,53 @@
+import type { EmbedderProvider } from '@graphorin/core';
+import type { EmbeddingMetaRegistryLike } from './storage-adapter.js';
+
+/**
+ * Infer the canonical adapter family from the embedder id. The
+ * canonical id format is `'<adapter>:<model>@<dim>'`; we slice the
+ * adapter name off the front so the registry can index by family
+ * without needing the embedder to expose an extra property.
+ *
+ * @internal
+ */
+export function inferAdapterKind(id: string): string {
+  const colonIndex = id.indexOf(':');
+  if (colonIndex < 0) return 'custom';
+  return id.slice(0, colonIndex);
+}
+
+/**
+ * Infer the model id portion of a canonical embedder id.
+ *
+ * @internal
+ */
+export function inferModelName(id: string): string {
+  const colonIndex = id.indexOf(':');
+  const atIndex = id.lastIndexOf('@');
+  if (colonIndex < 0) return id;
+  if (atIndex < 0 || atIndex < colonIndex) return id.slice(colonIndex + 1);
+  return id.slice(colonIndex + 1, atIndex);
+}
+
+/**
+ * Register the supplied embedder with the storage layer's
+ * `embedding_meta` registry. Returns the canonical id surfaced to the
+ * memory writers. Idempotent - a registry that already knows the id
+ * with a matching `configHash` returns the existing row.
+ *
+ * @internal
+ */
+export function bindEmbedder(
+  embedder: EmbedderProvider,
+  registry: EmbeddingMetaRegistryLike,
+): string {
+  const id = embedder.id();
+  registry.registerOrReturn({
+    id,
+    embedderKind: inferAdapterKind(id),
+    model: inferModelName(id),
+    dim: embedder.dim(),
+    configHash: embedder.configHash(),
+    distanceMetric: 'cosine',
+  });
+  return id;
+}

package/src/internal/envelope.ts

@@ -0,0 +1,70 @@
+/**
+ * Untrusted-content envelope helpers shared across the memory package.
+ *
+ * Extracted from the CE-15 compaction-summary neutralization
+ * (`wrapSummaryAsDerived` in `context-engine/compaction/compactor.ts`)
+ * so every prompt that interpolates untrusted memory text (compaction
+ * summaries, reconcile neighbours, deep-phase judge candidates,
+ * reflection evidence) delimits it with ONE substitution scheme. The
+ * scheme is the same visible bracket-substitution `@graphorin/tools`
+ * applies in `wrapEnvelope` (W-030): the closing marker
+ * `<<</untrusted_content>>>` becomes `[[/untrusted_content]]` and the
+ * opening prefix `<<<untrusted_content` becomes `[[untrusted_content`,
+ * tolerant to case and whitespace. Zero-width insertion is not used -
+ * models read straight through zero-width splits (the reason
+ * `normalizeForMatching` strips them before injection scans).
+ *
+ * The helper is deliberately local: `@graphorin/memory` does not
+ * depend on `@graphorin/tools`, and the substitution scheme is a
+ * cross-package SPEC pinned by tests on literal-marker inputs.
+ *
+ * @packageDocumentation
+ */
+
+/** Opening delimiter prefix of the untrusted-content envelope. */
+export const UNTRUSTED_CONTENT_OPEN_PREFIX = '<<<untrusted_content';
+
+/** Closing delimiter of the untrusted-content envelope. */
+export const UNTRUSTED_CONTENT_CLOSE = '<<</untrusted_content>>>';
+
+// Tolerant embedded-marker matching, mirroring the tools package: the
+// closing form optionally consumes its `>>>` terminator so the full
+// marker collapses to `[[/untrusted_content]]`.
+const EMBEDDED_CLOSING_RE = /<<<\s*\/\s*untrusted_content(\s*>>>)?/gi;
+const EMBEDDED_OPENING_RE = /<<<\s*untrusted_content/gi;
+
+/**
+ * Replace envelope markers embedded in `body` with the visible `[[` /
+ * `]]` bracket-substitution so the body cannot prematurely close (or
+ * spoof a nested opening of) the envelope it is being wrapped into.
+ * Marker-free bodies are returned bytes-equal.
+ *
+ * @internal
+ */
+export function neutralizeEnvelopeMarkers(body: string): string {
+  if (!body.includes('<<<')) return body;
+  return body
+    .replace(EMBEDDED_CLOSING_RE, (_match, terminator) =>
+      terminator === undefined ? '[[/untrusted_content' : '[[/untrusted_content]]',
+    )
+    .replace(EMBEDDED_OPENING_RE, '[[untrusted_content');
+}
+
+/**
+ * Wrap `body` in the untrusted-content envelope with the supplied
+ * attributes, neutralizing embedded markers first. Attribute insertion
+ * order is preserved, so
+ * `wrapUntrusted(body, { trust: 'derived', tool: 'compaction-summarizer' })`
+ * reproduces the historical CE-15 output byte-for-byte.
+ *
+ * @internal
+ */
+export function wrapUntrusted(body: string, attrs?: Readonly<Record<string, string>>): string {
+  const attrStr =
+    attrs === undefined
+      ? ''
+      : Object.entries(attrs)
+          .map(([key, value]) => ` ${key}="${value.replace(/"/g, '&quot;')}"`)
+          .join('');
+  return `${UNTRUSTED_CONTENT_OPEN_PREFIX}${attrStr}>>>\n${neutralizeEnvelopeMarkers(body)}\n${UNTRUSTED_CONTENT_CLOSE}`;
+}

package/src/internal/id.ts

@@ -0,0 +1,23 @@
+/**
+ * Stable id generator. Combines `Date.now()` (millisecond resolution),
+ * a per-process monotonic counter (resists collision inside the same
+ * millisecond), and a 36-bit crypto-quality random suffix (ties the id
+ * to the host so different runs do not collide either).
+ *
+ * The format is intentionally NOT a UUID - UUIDs are 16 bytes once
+ * decoded; these ids are 18 chars on average which is what the
+ * `audit.db` hash chain (Phase 03b) was sized for.
+ *
+ * @stable
+ */
+import { randomBytes } from 'node:crypto';
+
+let counter = 0;
+
+export function newMemoryId(prefix: string): string {
+  counter = (counter + 1) & 0xffff;
+  const time = Date.now().toString(36);
+  const c = counter.toString(36).padStart(3, '0');
+  const rand = randomBytes(4).toString('hex');
+  return `${prefix}_${time}${c}${rand}`;
+}

package/src/internal/llm-json.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared tolerant-parsing primitives for LLM text completions that are
+ * expected to carry JSON. Every consolidator phase and search transformer
+ * that parses a model response uses these two helpers; they used to be
+ * copy-pasted per module (7 copies of {@link stripFence}, 3 of
+ * {@link sliceJsonObject}) until the CodeQL ReDoS fix (06b7552) had to be
+ * applied to all of them at once - the canonical demonstration of why the
+ * single definition lives here now.
+ *
+ * Package-local (`internal/`): not part of the public `@graphorin/memory`
+ * API surface.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Strip a single surrounding Markdown code fence, if present. The
+ * info-string is matched with `[^\n]*` (never across lines) so a hostile
+ * megabyte-long first line cannot trigger polynomial backtracking; an
+ * unterminated fence leaves the text untouched and the caller's JSON
+ * parsing fails soft instead.
+ */
+export function stripFence(text: string): string {
+  const match = /^```[^\n]*\n([\s\S]*?)\n```/u.exec(text.trim());
+  return match?.[1] ?? text;
+}
+
+/**
+ * Best-effort recovery slice for completions that wrap a JSON object in
+ * prose: everything from the first `{` to the last `}`. Returns `null`
+ * when no plausible object span exists.
+ */
+export function sliceJsonObject(text: string): string | null {
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start < 0 || end < start) return null;
+  return text.slice(start, end + 1);
+}

package/src/internal/spans.ts

@@ -0,0 +1,35 @@
+import type { SessionScope, SpanAttributes, SpanType, Tracer } from '@graphorin/core';
+
+/**
+ * Sanitize a `SessionScope` for span attributes - the raw user id is
+ * surfaced as-is (it is a stable opaque identifier per DEC-005), but
+ * session and agent ids are emitted only when defined to avoid
+ * polluting the trace with `null` strings.
+ *
+ * @internal
+ */
+export function scopeAttrs(scope: SessionScope): SpanAttributes {
+  const attrs: Record<string, string> = {
+    'memory.scope.user_id': scope.userId,
+  };
+  if (scope.sessionId !== undefined) attrs['memory.scope.session_id'] = scope.sessionId;
+  if (scope.agentId !== undefined) attrs['memory.scope.agent_id'] = scope.agentId;
+  return Object.freeze(attrs);
+}
+
+/**
+ * Run an async function inside a `memory.*` span with the standard
+ * scope attributes already populated. Adds the span result count and
+ * status automatically.
+ *
+ * @internal
+ */
+export async function withMemorySpan<T extends SpanType, R>(
+  tracer: Tracer,
+  type: T,
+  scope: SessionScope,
+  extras: SpanAttributes,
+  fn: (span: import('@graphorin/core').AISpan<T>) => Promise<R>,
+): Promise<R> {
+  return tracer.span({ type, attrs: { ...scopeAttrs(scope), ...extras } }, fn);
+}