mirror-mind 0.0.1 → 0.32.1

package/ts/src/memory/memoryWrite.ts

@@ -0,0 +1,88 @@
+// Shared `memories` row writer + minimal read, extracted so extraction
+// (CV22.DS5) and cultivation's `merge` action (CV22.DS7.US3) do not each grow
+// their own copy of the same INSERT (DRY: the original write path lived only
+// in `conversation/extraction.ts`; cultivation needed the identical shape for
+// a merged memory, so the primitive moved here, one level below both callers,
+// and extraction now calls through it unchanged).
+
+import type { Database, SqlValue, WritableDatabase } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+/** Every writable column of a `memories` row except `last_accessed_at`
+ * (never set on insert -- it starts NULL, same as Python's `Memory` default). */
+export interface MemoryRowInput {
+  id: string;
+  conversationId?: string | null;
+  memoryType: string;
+  layer: string;
+  title: string;
+  content: string;
+  context?: string | null;
+  journey?: string | null;
+  persona?: string | null;
+  tags?: string | null;
+  createdAt: string;
+  relevanceScore?: number;
+  embedding: Uint8Array;
+  metadata?: string | null;
+  useCount?: number;
+  readinessState?: string;
+}
+
+const MEMORY_COLUMNS =
+  "id, conversation_id, memory_type, layer, title, content, context, journey, persona, tags, " +
+  "created_at, relevance_score, embedding, metadata, use_count, readiness_state";
+
+/**
+ * Insert one `memories` row. Mirrors both `insert_memory`-shaped writers in
+ * the Python core: `ConversationExtraction`'s per-memory insert and
+ * `consolidate_cmd.cmd_apply`'s `merge` action -- same 16 columns, same
+ * defaults (`relevance_score` 1.0, `use_count` 0, `readiness_state`
+ * `'observed'`), `last_accessed_at` always starts NULL (omitted, not a
+ * writable column here).
+ */
+export function createMemoryRow(db: WritableDatabase, input: MemoryRowInput): void {
+  const params: SqlValue[] = [
+    input.id,
+    input.conversationId ?? null,
+    input.memoryType,
+    input.layer,
+    input.title,
+    input.content,
+    input.context ?? null,
+    input.journey ?? null,
+    input.persona ?? null,
+    input.tags ?? null,
+    input.createdAt,
+    input.relevanceScore ?? 1.0,
+    input.embedding,
+    input.metadata ?? null,
+    input.useCount ?? 0,
+    input.readinessState ?? "observed",
+  ];
+  db.prepare(
+    `INSERT INTO memories (${MEMORY_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(...params);
+}
+
+/** The projection `consolidate apply`'s `merge` action needs from the first source memory. */
+export interface MergeSourceMemory {
+  memory_type: string;
+  layer: string;
+  title: string;
+  journey: string | null;
+}
+
+/** Port of the fields `cmd_apply`'s merge branch reads via `Store.get_memory`. */
+export function getMemorySourceForMerge(db: Database, id: string): MergeSourceMemory | null {
+  const row = db
+    .prepare("SELECT memory_type, layer, title, journey FROM memories WHERE id = ?")
+    .get(id);
+  if (row === undefined) return null;
+  return {
+    memory_type: requireString(row, "memory_type"),
+    layer: requireString(row, "layer"),
+    title: requireString(row, "title"),
+    journey: optionalString(row, "journey"),
+  };
+}

package/ts/src/memory/reinforcement.ts

@@ -0,0 +1,35 @@
+// TS reinforcement writes — the port of the Python core's log_access / log_use.
+//
+// log_access records a retrieval: it appends a memory_access_log row and caches
+// last_accessed_at on the memory. log_use records the stronger "actually drawn on
+// in a response" signal by incrementing use_count. Both mirror
+// src/memory/storage/memories.py exactly. The timestamp is injected (`nowIso`) so
+// a parity run can freeze the clock and match the Python oracle byte-for-byte;
+// the two statements in log_access share the one `nowIso`, as in Python.
+
+import { type WritableDatabase, withTransaction } from "#db/database.ts";
+
+/**
+ * Record a retrieval: append to memory_access_log and cache last_accessed_at.
+ * The two statements commit as one transaction, matching Python's single
+ * `conn.commit()` — a failure between them must never leave the access row
+ * without the cached timestamp (or vice versa).
+ */
+export function logAccess(
+  db: WritableDatabase,
+  memoryId: string,
+  nowIso: string,
+  context: string | null,
+): void {
+  withTransaction(db, () => {
+    db.prepare(
+      "INSERT INTO memory_access_log (memory_id, accessed_at, access_context) VALUES (?, ?, ?)",
+    ).run(memoryId, nowIso, context);
+    db.prepare("UPDATE memories SET last_accessed_at = ? WHERE id = ?").run(nowIso, memoryId);
+  });
+}
+
+/** Record a use: increment use_count (the stronger reinforcement signal). */
+export function logUse(db: WritableDatabase, memoryId: string): void {
+  db.prepare("UPDATE memories SET use_count = use_count + 1 WHERE id = ?").run(memoryId);
+}

package/ts/src/mirror/context.ts

@@ -0,0 +1,161 @@
+import type { Database } from "#db/database.ts";
+import { blobToFloat32 } from "#db/decode.ts";
+import { getIdentityContent, listIdentityByLayer } from "#identity/identityRead.ts";
+import {
+  type EmbeddingAttemptInfo,
+  type EmbeddingProvider,
+  generateEmbeddingSafely,
+} from "#providers/embedding.ts";
+import { cosineSimilarity } from "#search/ranker.ts";
+import { stripAccents } from "#util/slug.ts";
+
+export interface MirrorContextOptions {
+  persona?: string | null;
+  journey?: string | null;
+  org?: boolean;
+  query?: string | null;
+  touchesIdentity?: boolean;
+  touchesShadow?: boolean;
+  embeddingProvider?: EmbeddingProvider;
+  /**
+   * Where the attachment-search embedding is recorded as spend (CV22.DS9.TS1).
+   *
+   * Attachment search is a paid call that neither engine logged: Python's
+   * `attachment.py` calls `generate_embedding(query)` with no `on_llm_call`, against its
+   * own AI-09 rule that every model-in-the-loop call site logs. The MCP server passes a
+   * sink so its `mirror_context(query)` spend is countable; every other caller omits it
+   * and keeps the oracle's behaviour.
+   */
+  embeddingLedger?: (info: EmbeddingAttemptInfo) => void;
+  extensionContext?: string;
+}
+
+interface AttachmentRow {
+  journeyId: string;
+  name: string;
+  description: string | null;
+  content: string;
+  embedding: Uint8Array;
+}
+
+export async function loadMirrorContext(
+  db: Database,
+  options: MirrorContextOptions = {},
+): Promise<string> {
+  const sections: [string, string | null][] = [];
+  if (options.touchesIdentity ?? true)
+    sections.push(["self/soul", getIdentityContent(db, "self", "soul")]);
+  sections.push(["ego/behavior", getIdentityContent(db, "ego", "behavior")]);
+  sections.push(["user/identity", getIdentityContent(db, "user", "identity")]);
+  if (options.touchesIdentity ?? true)
+    sections.push(["ego/identity", getIdentityContent(db, "ego", "identity")]);
+  if (options.org) {
+    sections.push(["organization/identity", getIdentityContent(db, "organization", "identity")]);
+    sections.push([
+      "organization/principles",
+      getIdentityContent(db, "organization", "principles"),
+    ]);
+  }
+  if (options.persona) {
+    const content = getIdentityContent(db, "persona", options.persona);
+    if (content) sections.push([`persona/${options.persona}`, content]);
+  }
+  for (const row of listIdentityByLayer(db, "knowledge")) {
+    sections.push([`knowledge/${row.key}`, row.content]);
+  }
+  if (options.journey) {
+    const content = getIdentityContent(db, "journey", options.journey);
+    if (content) sections.push([`journey/${options.journey}`, content]);
+  }
+  if (options.touchesShadow) {
+    const shadow = listIdentityByLayer(db, "shadow");
+    if (shadow.length > 0) {
+      sections.push([
+        "shadow/profile",
+        [
+          "[Confirmed shadow patterns — grounded in evidence across multiple conversations]",
+          ...shadow.map((row) => row.content),
+        ].join("\n\n"),
+      ]);
+    }
+  }
+
+  const parts: string[] = [];
+  const constraints = getIdentityContent(db, "ego", "constraints");
+  if (constraints) parts.push(`=== ⛔ HARD CONSTRAINTS ===\n${constraints}`);
+  for (const [label, content] of sections) {
+    if (content) parts.push(`=== ${label} ===\n${content}`);
+  }
+
+  if (options.query) {
+    const attachments = await relevantAttachments(
+      db,
+      options.query,
+      options.journey ?? null,
+      options.embeddingProvider,
+      options.embeddingLedger,
+    );
+    if (attachments.length > 0) {
+      const attachmentParts = ["=== relevant attachments ==="];
+      for (const { row, score } of attachments) {
+        const source = options.journey ? "" : ` [${row.journeyId}]`;
+        attachmentParts.push(`--- ${row.name}${source} (score: ${score.toFixed(3)}) ---`);
+        if (row.description) attachmentParts.push(`Description: ${row.description}`);
+        attachmentParts.push(row.content);
+      }
+      parts.push(attachmentParts.join("\n"));
+    }
+  }
+  if (options.extensionContext) parts.push(options.extensionContext);
+  return parts.join("\n\n");
+}
+
+export async function relevantAttachments(
+  db: Database,
+  query: string,
+  journey: string | null,
+  provider?: EmbeddingProvider,
+  embeddingLedger?: (info: EmbeddingAttemptInfo) => void,
+): Promise<{ row: AttachmentRow; score: number }[]> {
+  const rows = attachmentRows(db, journey);
+  // No attachments, no embedding: the early return is why a query against a database
+  // without attachments records no spend -- there is none.
+  if (rows.length === 0) return [];
+  if (!provider) throw new Error("attachment embedding replay provider is required");
+  const queryEmbedding = await generateEmbeddingSafely(provider, query, {
+    ...(embeddingLedger ? { onAttempt: embeddingLedger } : {}),
+  });
+  const queryTokens = (query.match(/[\p{L}\p{N}_]+/gu) ?? [])
+    .filter((token) => [...token].length >= 2 || /^\p{N}+$/u.test(token))
+    .map((token) => stripAccents(token.toLowerCase()));
+  const scored = rows.map((row) => {
+    let score = cosineSimilarity(queryEmbedding, blobToFloat32(row.embedding));
+    if (!journey && queryTokens.length > 0) {
+      let searchable = stripAccents(
+        `${row.journeyId} ${row.name} ${row.description ?? ""}`.toLowerCase(),
+      );
+      searchable = searchable
+        .replace(/(\P{N})(\p{N})/gu, "$1 $2")
+        .replace(/(\p{N})(\P{N})/gu, "$1 $2");
+      const matches = queryTokens.filter((token) => searchable.includes(token)).length;
+      if (matches > 0) score += (matches / queryTokens.length) * 0.15;
+    }
+    return { row, score };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, journey ? 5 : 8).filter((item) => item.score > 0.4);
+}
+
+function attachmentRows(db: Database, journey: string | null): AttachmentRow[] {
+  const sql = journey
+    ? "SELECT journey_id, name, description, content, embedding FROM attachments WHERE journey_id = ? AND embedding IS NOT NULL ORDER BY created_at"
+    : "SELECT journey_id, name, description, content, embedding FROM attachments WHERE embedding IS NOT NULL ORDER BY created_at";
+  const rows = journey ? db.prepare(sql).all(journey) : db.prepare(sql).all();
+  return rows.map((row) => ({
+    journeyId: String(row.journey_id),
+    name: String(row.name),
+    description: typeof row.description === "string" ? row.description : null,
+    content: String(row.content),
+    embedding: row.embedding as Uint8Array,
+  }));
+}

package/ts/src/mirror/defaultResolution.ts

@@ -0,0 +1,199 @@
+import type { Database } from "#db/database.ts";
+import { descriptorsByLayer } from "#descriptor/descriptorRead.ts";
+import type { OnProviderCallOutcome } from "#observability/callOutcome.ts";
+import { detectPersona, type PersonaRoutingRow } from "#persona/detectPersona.ts";
+import { type EmbeddingProvider, generateEmbeddingSafely } from "#providers/embedding.ts";
+import type { LlmProvider, LlmResponse } from "#providers/llm.ts";
+import { cosineSimilarity } from "#search/ranker.ts";
+import { stripAccents } from "#util/slug.ts";
+import { runReception, sliceCodePoints } from "./reception.ts";
+import { GLOBAL_STICKY_DEFAULTS_SESSION_ID, getRuntimeSession } from "./runtimeSession.ts";
+
+export interface ResolvedMirrorDefaults {
+  persona: string | null;
+  journey: string | null;
+  detectedJourney: [string, number, string][] | null;
+  touchesIdentity: boolean;
+  touchesShadow: boolean;
+}
+
+export interface ResolveMirrorDefaultsInput {
+  persona?: string | null;
+  journey?: string | null;
+  query?: string | null;
+  sessionId?: string | null;
+  receptionEnabled: boolean;
+  llmProvider?: LlmProvider;
+  embeddingProvider?: EmbeddingProvider;
+  onReceptionLlmCall?: (response: LlmResponse, prompt: string) => void;
+  /** Reception's outcome, category only; see `observability/callOutcome.ts`. */
+  onReceptionOutcome?: OnProviderCallOutcome;
+}
+
+interface IdentityRoutingRow {
+  key: string;
+  content: string;
+  metadata: string | null;
+}
+
+export async function resolveMirrorDefaults(
+  db: Database,
+  input: ResolveMirrorDefaultsInput,
+): Promise<ResolvedMirrorDefaults> {
+  let persona = input.persona ?? null;
+  let journey = input.journey ?? null;
+  let detectedJourney: [string, number, string][] | null = null;
+  let touchesIdentity = true;
+  let touchesShadow = false;
+
+  const session = input.sessionId ? getRuntimeSession(db, input.sessionId) : null;
+  const global = getRuntimeSession(db, GLOBAL_STICKY_DEFAULTS_SESSION_ID);
+  const stickyPersona = session?.persona || global?.persona || null;
+  const stickyJourney = session?.journey || global?.journey || null;
+  const query = input.query ?? null;
+
+  if (input.receptionEnabled && query) {
+    if (!input.llmProvider) throw new Error("reception replay provider is required");
+    const personaRows = identityRoutingRows(db, "persona");
+    const journeyRows = identityRoutingRows(db, "journey");
+    const personaDescriptors = descriptorMap(db, "persona");
+    const journeyDescriptors = descriptorMap(db, "journey");
+    const reception = await runReception(
+      query,
+      personaRows.map((row) => ({
+        slug: row.key,
+        description: personaDescriptors.get(row.key) ?? sliceCodePoints(row.content, 200),
+        routingKeywords: routingKeywords(row.metadata),
+      })),
+      journeyRows.map((row) => ({
+        slug: row.key,
+        description: journeyDescriptors.get(row.key) ?? sliceCodePoints(row.content, 200),
+      })),
+      input.llmProvider,
+      input.onReceptionLlmCall,
+      input.onReceptionOutcome,
+    );
+    if (reception.personas.length > 0 && persona === null) persona = reception.personas[0] ?? null;
+    if (reception.journey && journey === null) journey = reception.journey;
+    touchesIdentity = reception.touchesIdentity;
+    touchesShadow = reception.touchesShadow;
+  }
+
+  persona ??= stickyPersona;
+  journey ??= stickyJourney;
+
+  if (persona === null && query) {
+    const matches = detectPersona(query, personaRoutingRows(db));
+    persona = matches[0]?.key ?? null;
+  }
+  if (journey === null && query) {
+    detectedJourney = await detectJourney(db, query, input.embeddingProvider);
+    journey = detectedJourney[0]?.[0] ?? null;
+  }
+
+  return { persona, journey, detectedJourney, touchesIdentity, touchesShadow };
+}
+
+export async function detectJourney(
+  db: Database,
+  query: string,
+  embeddingProvider?: EmbeddingProvider,
+  threshold = 0.35,
+): Promise<[string, number, string][]> {
+  const journeys = identityRoutingRows(db, "journey");
+  if (journeys.length === 0) return [];
+  const queryTokens = new Set(stripAccents(query.toLowerCase()).match(/[\p{L}\p{N}_]+/gu) ?? []);
+  const stopwords = new Set([
+    "o",
+    "a",
+    "os",
+    "as",
+    "de",
+    "do",
+    "da",
+    "dos",
+    "das",
+    "e",
+    "em",
+    "no",
+    "na",
+  ]);
+  const textMatches: [string, number, string][] = [];
+  for (const row of journeys) {
+    const idTokens = new Set(stripAccents(row.key.replaceAll("-", " ").toLowerCase()).split(/\s+/));
+    const firstLine =
+      row.content
+        .split("\n")[0]
+        ?.trim()
+        .replace(/^[# ]+/, "") ?? "";
+    const nameTokens = new Set(
+      stripAccents(firstLine.toLowerCase()).match(/[\p{L}\p{N}_]+/gu) ?? [],
+    );
+    const overlap = new Set<string>();
+    for (const token of [...idTokens, ...nameTokens]) {
+      if (!stopwords.has(token) && queryTokens.has(token)) overlap.add(token);
+    }
+    if (overlap.size > 0) {
+      const all = new Set([...idTokens, ...nameTokens].filter((token) => !stopwords.has(token)));
+      textMatches.push([row.key, Math.min(1, overlap.size / Math.max(all.size, 1) + 0.5), "text"]);
+    }
+  }
+  if (textMatches.length > 0) return textMatches.sort((a, b) => b[1] - a[1]);
+  if (!embeddingProvider) return [];
+  let queryEmbedding: readonly number[];
+  try {
+    queryEmbedding = await generateEmbeddingSafely(embeddingProvider, query);
+  } catch {
+    return [];
+  }
+  const semantic: [string, number, string][] = [];
+  for (const row of journeys) {
+    try {
+      const vector = await generateEmbeddingSafely(
+        embeddingProvider,
+        sliceCodePoints(row.content, 1000) || row.key,
+      );
+      const score = cosineSimilarity(queryEmbedding, vector);
+      if (score >= threshold) semantic.push([row.key, score, "semantic"]);
+    } catch {
+      // Python isolates each journey embedding failure.
+    }
+  }
+  return semantic.sort((a, b) => b[1] - a[1]);
+}
+
+function identityRoutingRows(db: Database, layer: string): IdentityRoutingRow[] {
+  return db
+    .prepare("SELECT key, content, metadata FROM identity WHERE layer = ? ORDER BY key")
+    .all(layer)
+    .map((row) => ({
+      key: String(row.key),
+      content: String(row.content),
+      metadata: typeof row.metadata === "string" ? row.metadata : null,
+    }));
+}
+
+function descriptorMap(db: Database, layer: string): Map<string, string> {
+  return new Map(descriptorsByLayer(db, layer).map((row) => [row.key, row.descriptor]));
+}
+
+function personaRoutingRows(db: Database): PersonaRoutingRow[] {
+  return identityRoutingRows(db, "persona").map((row) => ({
+    key: row.key,
+    routing_keywords: routingKeywords(row.metadata),
+  }));
+}
+
+function routingKeywords(metadata: string | null): string[] {
+  if (!metadata) return [];
+  try {
+    const parsed: unknown = JSON.parse(metadata);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return [];
+    const value = (parsed as Record<string, unknown>).routing_keywords;
+    return Array.isArray(value)
+      ? value.filter((item): item is string => typeof item === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}