lumiverse-spindle-types 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -1,5 +1,14 @@
 import type { SpindleManifest } from "./manifest";
 import type { CouncilMemberContext } from "./council";
+import type {
+  ChatLinkAttachDTO,
+  CortexQueryDTO,
+  MemoryCortexConfigDTO,
+  MemoryEntityStatusUpdateDTO,
+  MemoryEntityUpsertDTO,
+  MemoryRelationUpsertDTO,
+  VaultCreateDTO,
+} from "./memories";
 
 // ─── DTO types for messages ──────────────────────────────────────────────
 
@@ -1257,6 +1266,99 @@ export interface PermissionChangedDetail {
   allGranted: string[];
 }
 
+// ─── Web Search DTOs ────────────────────────────────────────────────────
+
+/** Identifies which provider backs the user's configured web search engine. */
+export type WebSearchProviderDTO = "searxng";
+
+/**
+ * Safe view of a user's web search configuration. The raw API key is never
+ * exposed — only `hasApiKey` indicates whether one is on file.
+ */
+export interface WebSearchSettingsDTO {
+  enabled: boolean;
+  provider: WebSearchProviderDTO;
+  apiUrl: string;
+  requestTimeoutMs: number;
+  defaultResultCount: number;
+  maxResultCount: number;
+  maxPagesToScrape: number;
+  maxCharsPerPage: number;
+  language: string;
+  safeSearch: 0 | 1 | 2;
+  engines: string[];
+  hasApiKey: boolean;
+}
+
+/** A single search result row, normalized across providers. */
+export interface WebSearchResultDTO {
+  title: string;
+  url: string;
+  snippet: string;
+  /** Provider-reported engine identifier when available (e.g. `"google"`, `"bing"`). */
+  engine?: string;
+  /** Provider-reported relevance score when available. */
+  score?: number;
+}
+
+/**
+ * A search result enriched with scraped page content. Only present when the
+ * query was run with `scrape: true` (the default).
+ */
+export interface WebSearchDocumentDTO {
+  title: string;
+  url: string;
+  snippet: string;
+  /** How the page content was extracted (e.g. `"html"`, `"pdf"`). */
+  sourceType?: string;
+  /** Extracted page text, clipped to `WebSearchSettingsDTO.maxCharsPerPage`. */
+  content?: string;
+  /** Length of the source page content before clipping. */
+  contentLength?: number;
+  /** Populated when scraping failed for this result; `content` is then absent. */
+  error?: string;
+}
+
+/** Options forwarded to `spindle.webSearch.query()`. */
+export interface WebSearchRequestDTO {
+  /** Free-text search query. Trimmed by the host; empty values are rejected. */
+  query: string;
+  /**
+   * Desired number of results. Clamped to `WebSearchSettingsDTO.maxResultCount`
+   * on the host; omit to use the user's `defaultResultCount`.
+   */
+  count?: number;
+  /**
+   * When `true` (default), the host scrapes the first
+   * `WebSearchSettingsDTO.maxPagesToScrape` results, fills in
+   * `documents[].content`, and assembles the `context` block. Set to `false`
+   * to skip scraping entirely — only `results` are returned, and
+   * `documents` / `context` are omitted from the response. Useful when the
+   * extension only needs titles, URLs, and snippets.
+   */
+  scrape?: boolean;
+  /** For operator-scoped extensions; ignored on user-scoped extensions. */
+  userId?: string;
+}
+
+/**
+ * Result of a successful `spindle.webSearch.query()` call. `documents` and
+ * `context` are omitted when the request was issued with `scrape: false`.
+ */
+export interface WebSearchResponseDTO {
+  /** The (trimmed) query that was executed. */
+  query: string;
+  /** Raw normalized results from the search provider. */
+  results: WebSearchResultDTO[];
+  /** Per-result scraped page content. Absent when `scrape: false`. */
+  documents?: WebSearchDocumentDTO[];
+  /**
+   * Pre-assembled, prompt-ready context block summarizing the query plus the
+   * scraped documents. Absent when `scrape: false`.
+   */
+  context?: string;
+}
+
 // ─── Theme DTOs ──────────────────────────────────────────────────────────
 
 /**
@@ -2281,6 +2383,50 @@ export type WorkerToHost =
   | { type: "generate_dry_run"; requestId: string; input: DryRunRequestDTO; userId?: string }
   // ─── Chat Memories (gated: "chats") ───────────────────────────────
   | { type: "chats_get_memories"; requestId: string; chatId: string; topK?: number; userId?: string }
+  // ─── Memory Cortex & Long-Term Chat Memory (gated: "memories") ────
+  | { type: "memories_config_get"; requestId: string; userId?: string }
+  | { type: "memories_config_put"; requestId: string; patch: Partial<MemoryCortexConfigDTO>; userId?: string }
+  | { type: "memories_query_cortex"; requestId: string; query: CortexQueryDTO }
+  | { type: "memories_query_linked"; requestId: string; chatId: string; queryText?: string; userId?: string }
+  | { type: "memories_get_cached"; requestId: string; chatId: string }
+  | { type: "memories_get_cached_linked"; requestId: string; chatId: string }
+  | { type: "memories_invalidate_cache"; requestId: string; chatId: string }
+  | { type: "memories_invalidate_linked_cache"; requestId: string; chatId: string }
+  | { type: "memories_entities_list"; requestId: string; chatId: string; activeOnly?: boolean; limit?: number; userId?: string }
+  | { type: "memories_entities_get"; requestId: string; entityId: string; userId?: string }
+  | { type: "memories_entities_find_by_name"; requestId: string; chatId: string; name: string; userId?: string }
+  | { type: "memories_entities_upsert"; requestId: string; chatId: string; entity: MemoryEntityUpsertDTO; chunkId?: string | null; createdAt?: number; userId?: string }
+  | { type: "memories_entities_update_status"; requestId: string; entityId: string; patch: MemoryEntityStatusUpdateDTO; userId?: string }
+  | { type: "memories_entities_add_facts"; requestId: string; entityId: string; facts: string[]; userId?: string }
+  | { type: "memories_entities_get_facts"; requestId: string; entityId: string; userId?: string }
+  | { type: "memories_entities_update_emotional_valence"; requestId: string; entityId: string; valence: Record<string, number>; userId?: string }
+  | { type: "memories_relations_list"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_relations_list_all"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_relations_for_entity"; requestId: string; chatId: string; entityId: string; userId?: string }
+  | { type: "memories_relations_for_entities"; requestId: string; chatId: string; entityIds: string[]; limit?: number; userId?: string }
+  | { type: "memories_relations_upsert"; requestId: string; chatId: string; relation: MemoryRelationUpsertDTO; chunkId?: string | null; userId?: string }
+  | { type: "memories_consolidations_list"; requestId: string; chatId: string; tier?: number; userId?: string }
+  | { type: "memories_consolidations_latest_arc"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_consolidations_run"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_salience_get"; requestId: string; chatId: string; limit?: number; offset?: number; userId?: string }
+  | { type: "memories_vaults_list"; requestId: string; userId?: string }
+  | { type: "memories_vaults_get"; requestId: string; vaultId: string; userId?: string }
+  | { type: "memories_vaults_get_chunks"; requestId: string; vaultId: string; userId?: string }
+  | { type: "memories_vaults_create"; requestId: string; input: VaultCreateDTO; userId?: string }
+  | { type: "memories_vaults_rename"; requestId: string; vaultId: string; name: string; userId?: string }
+  | { type: "memories_vaults_delete"; requestId: string; vaultId: string; userId?: string }
+  | { type: "memories_vaults_reindex"; requestId: string; vaultId: string; userId?: string }
+  | { type: "memories_links_list"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_links_attach"; requestId: string; input: ChatLinkAttachDTO; userId?: string }
+  | { type: "memories_links_remove"; requestId: string; chatId: string; linkId: string; userId?: string }
+  | { type: "memories_links_toggle"; requestId: string; chatId: string; linkId: string; enabled: boolean; userId?: string }
+  | { type: "memories_chat_chunks_list"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_chat_memory_get"; requestId: string; chatId: string; topK?: number; userId?: string }
+  | { type: "memories_chat_memory_warm"; requestId: string; chatId: string; force?: boolean; userId?: string }
+  | { type: "memories_chat_memory_invalidate"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_stats_usage"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_stats_ingestion_status"; requestId: string; chatId: string; userId?: string }
+  | { type: "memories_stats_ingestion_telemetry"; requestId: string; chatId: string; userId?: string }
   // ─── Toast (free tier) ───────────────────────────────────────────────
   | { type: "toast_show"; toastType: "success" | "warning" | "error" | "info"; message: string; title?: string; duration?: number; userId?: string }
   // ─── Push Notifications (gated: "push_notification") ────────────────
@@ -2395,7 +2541,17 @@ export type WorkerToHost =
       model?: string;
       modelSource?: TokenModelSourceDTO;
       userId?: string;
-    };
+    }
+  // ─── Web Search (gated: "web_search") ─────────────────────────────────
+  | {
+      type: "web_search_query";
+      requestId: string;
+      query: string;
+      count?: number;
+      scrape?: boolean;
+      userId?: string;
+    }
+  | { type: "web_search_get_settings"; requestId: string; userId?: string };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 

package/src/index.ts

@@ -155,6 +155,12 @@ export type {
   MessageContentProcessorOrigin,
   MessageContentProcessorCtxDTO,
   MessageContentProcessorResultDTO,
+  WebSearchProviderDTO,
+  WebSearchSettingsDTO,
+  WebSearchResultDTO,
+  WebSearchDocumentDTO,
+  WebSearchRequestDTO,
+  WebSearchResponseDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";
@@ -210,6 +216,58 @@ export type {
 
 export type { ExtensionInfo } from "./extension-info";
 
+export type {
+  EntityTypeDTO,
+  EntityStatusDTO,
+  MentionRoleDTO,
+  RelationTypeDTO,
+  RelationStatusDTO,
+  EmotionalTagDTO,
+  NarrativeFlagDTO,
+  ContradictionFlagDTO,
+  FactExtractionStatusDTO,
+  EntityConfidenceDTO,
+  SalienceSourceDTO,
+  ChatLinkTypeDTO,
+  SalienceBreakdownDTO,
+  MemoryEntityDTO,
+  MemoryEntityUpsertDTO,
+  MemoryEntityStatusUpdateDTO,
+  MemoryMentionDTO,
+  MemoryRelationDTO,
+  MemoryRelationUpsertDTO,
+  StatusChangeDTO,
+  MemorySalienceDTO,
+  MemoryConsolidationDTO,
+  CortexQueryDTO,
+  CortexMemoryComponentsDTO,
+  CortexMemoryDTO,
+  EntitySnapshotRelationshipDTO,
+  EntitySnapshotDTO,
+  RelationEdgeDTO,
+  CortexStatsDTO,
+  CortexResultDTO,
+  VaultDTO,
+  VaultChunkDTO,
+  VaultEntityDTO,
+  VaultRelationDTO,
+  VaultCreateDTO,
+  VaultWithContentsDTO,
+  VaultReindexResultDTO,
+  ChatLinkDTO,
+  ChatLinkAttachDTO,
+  VaultCortexDataDTO,
+  InterlinkCortexDataDTO,
+  LinkedCortexResultDTO,
+  MemoryCortexConfigDTO,
+  CortexUsageStatsDTO,
+  CortexIngestionTimingsDTO,
+  CortexIngestionStatusDTO,
+  CortexIngestionTelemetryDTO,
+  ChatChunkDTO,
+  ChatMemoryWarmupResultDTO,
+} from "./memories";
+
 export type {
   SpindleAPI,
   FrontendProcessHandle,

package/src/memories.ts

@@ -0,0 +1,607 @@
+/**
+ * Memory Cortex & Long-Term Chat Memory DTOs.
+ *
+ * Surfaces the Lumiverse hybrid memory architecture to extensions via the
+ * `memories` permission. Covers:
+ *
+ *  - Memory Cortex
+ *      • config (entity tracking, salience scoring, retrieval tuning)
+ *      • retrieval (cortex query, linked-cortex query, vault query)
+ *      • entity graph (entities, relations, mentions)
+ *      • consolidations & salience records
+ *      • vaults (snapshots of cortex state) and chat links (vault attach /
+ *        bidirectional interlinks)
+ *      • ingestion / maintenance telemetry
+ *
+ *  - Long-Term Chat Memory
+ *      • vectorized chat chunks (list, get, warm)
+ *      • cached retrieval result for the {{memories}} macro
+ *
+ * Service-layer shapes use camelCase; SQLite row shapes (snake_case) are not
+ * exposed to extensions — DTOs are normalised here.
+ */
+
+// ─── Enums ─────────────────────────────────────────────────────────────
+
+export type EntityTypeDTO =
+  | "character"
+  | "location"
+  | "item"
+  | "faction"
+  | "concept"
+  | "event";
+
+export type EntityStatusDTO =
+  | "active"
+  | "inactive"
+  | "deceased"
+  | "destroyed"
+  | "unknown";
+
+export type MentionRoleDTO =
+  | "subject"
+  | "object"
+  | "present"
+  | "referenced"
+  | "absent";
+
+export type RelationTypeDTO =
+  | "ally"
+  | "enemy"
+  | "lover"
+  | "parent"
+  | "child"
+  | "sibling"
+  | "mentor"
+  | "rival"
+  | "owns"
+  | "member_of"
+  | "located_in"
+  | "fears"
+  | "serves"
+  | "custom";
+
+export type RelationStatusDTO = "active" | "broken" | "dormant" | "former";
+
+export type EmotionalTagDTO =
+  | "grief"
+  | "joy"
+  | "tension"
+  | "dread"
+  | "intimacy"
+  | "betrayal"
+  | "revelation"
+  | "resolve"
+  | "humor"
+  | "melancholy"
+  | "awe"
+  | "fury";
+
+export type NarrativeFlagDTO =
+  | "first_meeting"
+  | "death"
+  | "promise"
+  | "confession"
+  | "departure"
+  | "transformation"
+  | "battle"
+  | "discovery"
+  | "reunion"
+  | "loss";
+
+export type ContradictionFlagDTO = "none" | "temporal" | "complex" | "suspect";
+
+export type FactExtractionStatusDTO = "never" | "attempted_empty" | "ok";
+
+export type EntityConfidenceDTO = "confirmed" | "provisional";
+
+export type SalienceSourceDTO = "heuristic" | "sidecar";
+
+export type ChatLinkTypeDTO = "vault" | "interlink";
+
+// ─── Entity Graph ──────────────────────────────────────────────────────
+
+export interface SalienceBreakdownDTO {
+  mentionComponent: number;
+  arcComponent: number;
+  graphComponent: number;
+  total: number;
+}
+
+export interface MemoryEntityDTO {
+  id: string;
+  chatId: string;
+  name: string;
+  entityType: EntityTypeDTO;
+  aliases: string[];
+  description: string;
+  firstSeenChunkId: string | null;
+  lastSeenChunkId: string | null;
+  firstSeenAt: number | null;
+  lastSeenAt: number | null;
+  mentionCount: number;
+  salienceAvg: number;
+  status: EntityStatusDTO;
+  statusChangedAt: number | null;
+  facts: string[];
+  emotionalValence: Record<string, number>;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+  factExtractionStatus: FactExtractionStatusDTO;
+  factExtractionLastAttempt: number | null;
+  salienceBreakdown: SalienceBreakdownDTO;
+  lastMentionTimestamp: number | null;
+  recentMentionCount: number;
+  confidence: EntityConfidenceDTO;
+  userEditedAt: number | null;
+}
+
+/**
+ * Input shape for upserting an entity. Matches the heuristic / sidecar
+ * extraction shape so an extension can replay its own NER results into the
+ * graph. `confidence` is the raw [0, 1] extractor confidence; entities below
+ * the configured threshold are dropped by the host.
+ */
+export interface MemoryEntityUpsertDTO {
+  name: string;
+  type: EntityTypeDTO;
+  aliases?: string[];
+  confidence?: number;
+  role?: MentionRoleDTO;
+  /** Marks the entity as needing corroboration before promotion. */
+  provisional?: boolean;
+}
+
+export interface MemoryEntityStatusUpdateDTO {
+  status: EntityStatusDTO;
+  statusChangedAt?: number;
+}
+
+export interface MemoryMentionDTO {
+  id: string;
+  entityId: string;
+  chunkId: string;
+  chatId: string;
+  role: MentionRoleDTO;
+  excerpt: string | null;
+  sentiment: number;
+  createdAt: number;
+}
+
+// ─── Relations ─────────────────────────────────────────────────────────
+
+export interface MemoryRelationDTO {
+  id: string;
+  chatId: string;
+  sourceEntityId: string;
+  targetEntityId: string;
+  relationType: RelationTypeDTO;
+  relationLabel: string | null;
+  strength: number;
+  sentiment: number;
+  evidenceChunkIds: string[];
+  firstEstablishedAt: number | null;
+  lastReinforcedAt: number | null;
+  status: RelationStatusDTO;
+  metadata: Record<string, unknown>;
+  createdAt: number;
+  updatedAt: number;
+  contradictionFlag: ContradictionFlagDTO;
+  contradictionPeerId: string | null;
+  sentimentRange: [number, number] | null;
+  supersededBy: string | null;
+  arcIds: string[];
+  firstSeenArcId: string | null;
+  lastSeenArcId: string | null;
+  lastEvidenceTimestamp: number | null;
+  decayRate: number;
+  edgeSalience: number;
+  labelAliases: string[];
+  canonicalEdgeId: string | null;
+  mergedInto: string | null;
+}
+
+/**
+ * Input shape for upserting a relation. Uses entity *names* (not ids) so
+ * extensions can produce relations symbolically — the host resolves canonical
+ * ids server-side. Both endpoints must already exist in the entity graph;
+ * the relation is silently dropped otherwise.
+ */
+export interface MemoryRelationUpsertDTO {
+  source: string;
+  target: string;
+  type: RelationTypeDTO;
+  label: string;
+  sentiment: number;
+}
+
+// ─── Salience ──────────────────────────────────────────────────────────
+
+export interface StatusChangeDTO {
+  entity: string;
+  change: string;
+  detail: string;
+}
+
+export interface MemorySalienceDTO {
+  chunkId: string;
+  chatId: string;
+  score: number;
+  scoreSource: SalienceSourceDTO;
+  emotionalTags: EmotionalTagDTO[];
+  statusChanges: StatusChangeDTO[];
+  narrativeFlags: NarrativeFlagDTO[];
+  hasDialogue: boolean;
+  hasAction: boolean;
+  hasInternalThought: boolean;
+  wordCount: number;
+  scoredAt: number;
+  scoredBy: string | null;
+}
+
+// ─── Consolidations ────────────────────────────────────────────────────
+
+export interface MemoryConsolidationDTO {
+  id: string;
+  chatId: string;
+  tier: number;
+  title: string | null;
+  summary: string;
+  sourceChunkIds: string[];
+  sourceConsolidationIds: string[];
+  entityIds: string[];
+  messageRangeStart: number | null;
+  messageRangeEnd: number | null;
+  timeRangeStart: number | null;
+  timeRangeEnd: number | null;
+  salienceAvg: number;
+  emotionalTags: EmotionalTagDTO[];
+  tokenCount: number;
+  vectorizedAt: number | null;
+  vectorModel: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ─── Cortex Retrieval ──────────────────────────────────────────────────
+
+/**
+ * Input to a Memory Cortex retrieval query.
+ *
+ * The `userId` field is normally inferred from the calling extension's
+ * effective user; pass it explicitly only for operator-scoped extensions.
+ */
+export interface CortexQueryDTO {
+  chatId: string;
+  queryText: string;
+  entityFilter?: string[];
+  timeRange?: { start?: number; end?: number };
+  emotionalContext?: EmotionalTagDTO[];
+  generationType?: string;
+  topK?: number;
+  includeConsolidations?: boolean;
+  includeRelationships?: boolean;
+  excludeMessageIds?: string[];
+  userId?: string;
+}
+
+export interface CortexMemoryComponentsDTO {
+  semantic: number;
+  salience: number;
+  recency: number;
+  reinforcement: number;
+  emotional: number;
+  entity: number;
+}
+
+export interface CortexMemoryDTO {
+  source: "chunk" | "consolidation";
+  sourceId: string;
+  content: string;
+  finalScore: number;
+  components: CortexMemoryComponentsDTO;
+  emotionalTags: EmotionalTagDTO[];
+  entityNames: string[];
+  messageRange: [number, number];
+  timeRange: [number, number];
+}
+
+export interface EntitySnapshotRelationshipDTO {
+  targetName: string;
+  type: RelationTypeDTO;
+  label: string | null;
+  strength: number;
+  sentiment: number;
+}
+
+export interface EntitySnapshotDTO {
+  id: string;
+  name: string;
+  type: EntityTypeDTO;
+  status: EntityStatusDTO;
+  description: string;
+  lastSeenAt: number | null;
+  mentionCount: number;
+  topFacts: string[];
+  emotionalProfile: Record<string, number>;
+  relationships: EntitySnapshotRelationshipDTO[];
+}
+
+export interface RelationEdgeDTO {
+  sourceName: string;
+  targetName: string;
+  type: RelationTypeDTO;
+  label: string | null;
+  strength: number;
+  sentiment: number;
+}
+
+export interface CortexStatsDTO {
+  candidatePoolSize: number;
+  vectorSearchResults: number;
+  entitiesMatched: number;
+  scoreFusionApplied: boolean;
+  topScore: number;
+  retrievalTimeMs: number;
+  /** Set when the retrieval hit its internal time budget. */
+  timedOut?: boolean;
+  /** Set when retrieval bailed out because the caller's AbortSignal fired. */
+  aborted?: boolean;
+}
+
+export interface CortexResultDTO {
+  memories: CortexMemoryDTO[];
+  entityContext: EntitySnapshotDTO[];
+  activeRelationships: RelationEdgeDTO[];
+  arcContext: string | null;
+  stats: CortexStatsDTO;
+}
+
+// ─── Vaults & Linked Cortex ────────────────────────────────────────────
+
+export interface VaultDTO {
+  id: string;
+  userId: string;
+  sourceChatId: string | null;
+  sourceChatName: string | null;
+  name: string;
+  description: string;
+  entityCount: number;
+  relationCount: number;
+  chunkCount: number;
+  createdAt: number;
+}
+
+export interface VaultChunkDTO {
+  id: string;
+  vaultId: string;
+  sourceChunkId: string;
+  content: string;
+  salienceScore: number | null;
+  emotionalTags: string[];
+  entityNames: string[];
+  sourceCreatedAt: number;
+  copiedAt: number;
+}
+
+export interface VaultEntityDTO {
+  id: string;
+  vaultId: string;
+  name: string;
+  entityType: EntityTypeDTO;
+  aliases: string[];
+  description: string;
+  status: EntityStatusDTO;
+  facts: string[];
+  emotionalValence: Record<string, number>;
+  salienceAvg: number;
+}
+
+export interface VaultRelationDTO {
+  id: string;
+  vaultId: string;
+  sourceEntityName: string;
+  targetEntityName: string;
+  relationType: RelationTypeDTO;
+  relationLabel: string | null;
+  strength: number;
+  sentiment: number;
+  status: RelationStatusDTO;
+}
+
+export interface VaultCreateDTO {
+  chatId: string;
+  name: string;
+  description?: string;
+}
+
+export interface VaultWithContentsDTO {
+  vault: VaultDTO;
+  entities: VaultEntityDTO[];
+  relations: VaultRelationDTO[];
+}
+
+export interface VaultReindexResultDTO {
+  mode: string;
+  chunkCount: number;
+}
+
+export interface ChatLinkDTO {
+  id: string;
+  userId: string;
+  chatId: string;
+  linkType: ChatLinkTypeDTO;
+  vaultId: string | null;
+  vaultName: string | null;
+  vaultEntityCount: number | null;
+  vaultRelationCount: number | null;
+  targetChatId: string | null;
+  targetChatName: string | null;
+  targetChatExists: boolean;
+  label: string;
+  enabled: boolean;
+  priority: number;
+  createdAt: number;
+}
+
+export interface ChatLinkAttachDTO {
+  chatId: string;
+  linkType: ChatLinkTypeDTO;
+  vaultId?: string;
+  targetChatId?: string;
+  label?: string;
+  /** Interlinks only. When true, also creates the reverse link on the target chat. */
+  bidirectional?: boolean;
+}
+
+export interface VaultCortexDataDTO {
+  vaultId: string;
+  vaultName: string;
+  sourceChatId?: string;
+  entities: EntitySnapshotDTO[];
+  relations: RelationEdgeDTO[];
+  /** Retrieved memories from the vault's chunk snapshot (when queryText supplied). */
+  memories?: CortexMemoryDTO[];
+  arcContext?: string | null;
+}
+
+export interface InterlinkCortexDataDTO {
+  targetChatId: string;
+  targetChatName: string;
+  result: CortexResultDTO;
+}
+
+export interface LinkedCortexResultDTO {
+  vaults: VaultCortexDataDTO[];
+  interlinks: InterlinkCortexDataDTO[];
+}
+
+// ─── Cortex Config ─────────────────────────────────────────────────────
+
+/**
+ * Memory Cortex configuration.
+ *
+ * The host owns the canonical schema (see `MemoryCortexConfig` in the
+ * backend). The DTO is intentionally permissive — only the top-level toggles
+ * extensions are likely to flip are typed, and the index signature passes
+ * advanced fields (retrieval tuning, sidecar configuration, decay curves,
+ * consolidation thresholds, entity pruning, etc.) straight through. New
+ * fields added by the host are visible immediately to extensions without
+ * a coordinated type bump.
+ */
+export interface MemoryCortexConfigDTO {
+  enabled: boolean;
+  entityTracking: boolean;
+  entityExtractionMode: string;
+  salienceScoring: boolean;
+  salienceScoringMode?: string;
+  thoughtMarkers?: unknown;
+  entityWhitelist?: string[];
+  entityExtractionFilters?: unknown;
+  retrieval?: Record<string, unknown>;
+  decay?: Record<string, unknown>;
+  consolidation?: Record<string, unknown>;
+  entityPruning?: Record<string, unknown>;
+  sidecar?: Record<string, unknown>;
+  sidecarTimeoutMs?: number;
+  retrievalTimeoutMs?: number;
+  [key: string]: unknown;
+}
+
+// ─── Telemetry & Stats ─────────────────────────────────────────────────
+
+export interface CortexUsageStatsDTO {
+  entityCount: number;
+  relationCount: number;
+  salienceRecordCount: number;
+  consolidationCount: number;
+  /** Advanced fields exposed by the host's gc module (mention counts, last
+   *  GC timestamp, etc.) pass through unchanged. */
+  [key: string]: number | string | boolean | null | undefined;
+}
+
+export interface CortexIngestionTimingsDTO {
+  mode: "heuristic" | "sidecar" | "mixed";
+  fontMs: number;
+  heuristicMs: number;
+  heuristicSalienceMs: number;
+  heuristicEntityMs: number;
+  heuristicRelationshipMs: number;
+  heuristicAliasMs: number;
+  sidecarMs: number;
+  graphMs: number;
+  dbMs: number;
+  totalMs: number;
+  completedAt: number;
+  chunkId: string;
+}
+
+export interface CortexIngestionStatusDTO {
+  chatId: string;
+  status: "idle" | "processing" | "complete" | "error";
+  phase:
+    | "queued"
+    | "font"
+    | "heuristics"
+    | "sidecar"
+    | "persisting"
+    | "complete"
+    | "error";
+  chunkId: string | null;
+  startedAt: number | null;
+  updatedAt: number;
+  pendingJobs: number;
+  error?: string;
+  timings?: CortexIngestionTimingsDTO | null;
+}
+
+export interface CortexIngestionTelemetryDTO {
+  samples: number;
+  last: CortexIngestionTimingsDTO | null;
+  averages: {
+    fontMs: number;
+    heuristicMs: number;
+    sidecarMs: number;
+    graphMs: number;
+    dbMs: number;
+    totalMs: number;
+  };
+}
+
+// ─── Long-Term Chat Memory ─────────────────────────────────────────────
+
+/**
+ * A vectorized chat chunk — the basic unit of long-term chat memory. Chunks
+ * are produced from contiguous same-role messages bounded by token target
+ * and scene-break heuristics; the {{memories}} macro retrieves the top-K
+ * chunks by hybrid vector + BM25 score during prompt assembly.
+ */
+export interface ChatChunkDTO {
+  id: string;
+  chatId: string;
+  startMessageId: string;
+  endMessageId: string;
+  messageIds: string[];
+  content: string;
+  tokenCount: number;
+  messageCount: number;
+  vectorizedAt: number | null;
+  vectorModel: string | null;
+  retrievalCount: number;
+  lastRetrievedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/**
+ * Result of a long-term chat memory warmup. `status` describes the action
+ * taken; `reason` is a short human-readable string useful for diagnostics
+ * when nothing was queued.
+ */
+export interface ChatMemoryWarmupResultDTO {
+  status: "skipped" | "complete" | "rebuilding" | "queued" | "error";
+  reason?: string;
+  rebuilt?: boolean;
+  vectorizationsQueued?: number;
+}

package/src/permissions.ts

@@ -15,7 +15,13 @@
  * - "presets"              — CRUD on user presets and prompt blocks
  * - "personas"             — CRUD on personas
  * - "databanks"            — CRUD on databanks and their documents
+ * - "memories"             — CRUD on the Memory Cortex (entities, relations, vaults, chat
+ *                            links, consolidations) and long-term chat memory (vectorized
+ *                            chat-chunk retrieval, warmup, cache).
  * - "macro_interceptor"    — transform raw templates before macro parsing/dispatch
+ * - "web_search"           — execute searches via the user's configured web search
+ *                            provider (e.g. SearXNG) and read the safe view of their
+ *                            web search settings (never the API key).
  */
 export type SpindlePermission =
   | "generation"
@@ -35,12 +41,14 @@ export type SpindlePermission =
   | "world_books"
   | "regex_scripts"
   | "databanks"
+  | "memories"
   | "personas"
   | "push_notification"
   | "image_gen"
   | "images"
   | "generation_parameters"
-  | "macro_interceptor";
+  | "macro_interceptor"
+  | "web_search";
 
 export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "generation",
@@ -60,12 +68,14 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "world_books",
   "regex_scripts",
   "databanks",
+  "memories",
   "personas",
   "push_notification",
   "image_gen",
   "images",
   "generation_parameters",
   "macro_interceptor",
+  "web_search",
 ] as const;
 
 export function isValidPermission(p: string): p is SpindlePermission {

package/src/spindle-api.ts

@@ -103,7 +103,35 @@ import type {
   MessageContentProcessorResultDTO,
   SharedRpcRequestContextDTO,
   SharedRpcEndpointPolicyDTO,
+  WebSearchRequestDTO,
+  WebSearchResponseDTO,
+  WebSearchSettingsDTO,
 } from "./api";
+import type {
+  ChatChunkDTO,
+  ChatLinkAttachDTO,
+  ChatLinkDTO,
+  ChatMemoryWarmupResultDTO,
+  CortexIngestionStatusDTO,
+  CortexIngestionTelemetryDTO,
+  CortexQueryDTO,
+  CortexResultDTO,
+  CortexUsageStatsDTO,
+  LinkedCortexResultDTO,
+  MemoryConsolidationDTO,
+  MemoryCortexConfigDTO,
+  MemoryEntityDTO,
+  MemoryEntityStatusUpdateDTO,
+  MemoryEntityUpsertDTO,
+  MemoryRelationDTO,
+  MemoryRelationUpsertDTO,
+  MemorySalienceDTO,
+  VaultChunkDTO,
+  VaultCreateDTO,
+  VaultDTO,
+  VaultReindexResultDTO,
+  VaultWithContentsDTO,
+} from "./memories";
 
 export interface FrontendProcessHandle {
   /** Host-assigned process ID unique within the extension runtime. */
@@ -827,6 +855,193 @@ export interface SpindleAPI {
     };
   };
 
+  /**
+   * Memory Cortex & Long-Term Chat Memory (permission: "memories").
+   *
+   * Lumiverse's hybrid memory architecture exposed as a single CRUD surface:
+   *
+   *  - **`cortex`** — config get/put, retrieval (cortex query, linked-cortex
+   *    query for vaults + interlinks), warm-cache reads, cache invalidation.
+   *  - **`entities`** / **`relations`** — entity graph CRUD: list, find,
+   *    upsert, status updates, fact appends, emotional valence, plus active
+   *    + unfiltered relation reads and `upsert` for symbolic edges.
+   *  - **`consolidations`** — list arcs by tier, fetch the latest arc, and
+   *    `run()` to trigger a background consolidation pass.
+   *  - **`salience`** — read salience records (score, emotional tags,
+   *    narrative flags) for chunks already ingested.
+   *  - **`vaults`** — frozen snapshots of cortex state. `create()` snapshots
+   *    a chat's entities/relations/chunks, `reindex()` re-copies the chunk
+   *    snapshot after a LanceDB reset, plus list / get / rename / delete.
+   *  - **`links`** — attach vaults to chats or set up bidirectional
+   *    chat-to-chat interlinks; list / remove / toggle.
+   *  - **`chatMemory`** — the long-term chat memory layer used by the
+   *    `{{memories}}` macro: list vectorized chunks, fetch top-K retrieval,
+   *    warm a chat (rebuild + queue vectorization), invalidate cache.
+   *  - **`stats`** — usage counters, live ingestion phase, and ingestion
+   *    timing telemetry.
+   *
+   * For user-scoped extensions, `userId` is inferred from the extension
+   * owner. For operator-scoped extensions, pass `userId` to scope a call
+   * to a specific user.
+   *
+   * All chat-scoped calls verify chat ownership against the resolved user
+   * — extensions cannot read or mutate cortex state for chats they do not
+   * own.
+   */
+  memories: {
+    cortex: {
+      /** Get the user's Memory Cortex configuration. */
+      getConfig(userId?: string): Promise<MemoryCortexConfigDTO>;
+      /** Patch the user's Memory Cortex configuration. Unspecified fields are left untouched. */
+      putConfig(patch: Partial<MemoryCortexConfigDTO>, userId?: string): Promise<MemoryCortexConfigDTO>;
+      /**
+       * Execute a cortex-enhanced memory retrieval. Combines vector search,
+       * entity-context fan-out, recency, reinforcement, and emotional
+       * components into a unified `CortexResultDTO`.
+       *
+       * Results are cached server-side; the next call within ~5 minutes
+       * for the same chat + query shape returns the cached value.
+       */
+      query(query: CortexQueryDTO): Promise<CortexResultDTO>;
+      /**
+       * Read the most recent cortex result from the warm cache without
+       * triggering a re-query. Returns `null` if no cached result exists
+       * or it expired. Synchronous from the caller's perspective (no
+       * vector search runs); useful when an extension just needs the same
+       * memories the active generation saw.
+       */
+      getCached(chatId: string): Promise<CortexResultDTO | null>;
+      /**
+       * Resolve linked-cortex data for a chat — every attached vault plus
+       * every bidirectional interlink target. When `queryText` is supplied,
+       * vault retrieval and interlink queries are enriched with relevance
+       * to the current conversation.
+       */
+      queryLinked(chatId: string, options?: { queryText?: string; userId?: string }): Promise<LinkedCortexResultDTO>;
+      /** Read the cached linked-cortex result for a chat. Mirrors {@link getCached}. */
+      getCachedLinked(chatId: string): Promise<LinkedCortexResultDTO | null>;
+      /** Invalidate the cortex retrieval cache for a chat. */
+      invalidateCache(chatId: string): Promise<void>;
+      /** Invalidate the linked-cortex retrieval cache for a chat. */
+      invalidateLinkedCache(chatId: string): Promise<void>;
+    };
+
+    entities: {
+      /**
+       * List entities for a chat. By default returns only entities with
+       * `status: "active"`, ordered by salience; pass `activeOnly: false`
+       * to include retired / deceased / destroyed entities.
+       */
+      list(chatId: string, options?: { activeOnly?: boolean; limit?: number; userId?: string }): Promise<MemoryEntityDTO[]>;
+      get(entityId: string, userId?: string): Promise<MemoryEntityDTO | null>;
+      findByName(chatId: string, name: string, userId?: string): Promise<MemoryEntityDTO | null>;
+      /**
+       * Upsert an entity. Matches against canonical name and known aliases;
+       * inserts a new row on miss. `chunkId` and `createdAt` attribute the
+       * mention used to fill `lastSeen*` fields — pass them when replaying
+       * an extractor over a specific chunk.
+       */
+      upsert(
+        chatId: string,
+        entity: MemoryEntityUpsertDTO,
+        options?: { chunkId?: string | null; createdAt?: number; userId?: string },
+      ): Promise<MemoryEntityDTO>;
+      updateStatus(entityId: string, patch: MemoryEntityStatusUpdateDTO, userId?: string): Promise<MemoryEntityDTO>;
+      addFacts(entityId: string, facts: string[], userId?: string): Promise<MemoryEntityDTO>;
+      getFacts(entityId: string, userId?: string): Promise<string[]>;
+      updateEmotionalValence(entityId: string, valence: Record<string, number>, userId?: string): Promise<MemoryEntityDTO>;
+    };
+
+    relations: {
+      /** Active relations for a chat (excludes superseded / merged edges). */
+      list(chatId: string, userId?: string): Promise<MemoryRelationDTO[]>;
+      /** Every relation row including superseded / merged edges — for diagnostics. */
+      listAll(chatId: string, userId?: string): Promise<MemoryRelationDTO[]>;
+      forEntity(chatId: string, entityId: string, userId?: string): Promise<MemoryRelationDTO[]>;
+      forEntities(chatId: string, entityIds: string[], options?: { limit?: number; userId?: string }): Promise<MemoryRelationDTO[]>;
+      /**
+       * Upsert a relation. Both endpoints must already exist in the entity
+       * graph (use `entities.upsert` first); the relation is silently
+       * dropped otherwise. `chunkId` attributes the evidence to a chunk.
+       */
+      upsert(
+        chatId: string,
+        relation: MemoryRelationUpsertDTO,
+        options?: { chunkId?: string | null; userId?: string },
+      ): Promise<MemoryRelationDTO | null>;
+    };
+
+    consolidations: {
+      /** List arcs for a chat. Pass `tier` to filter to one tier (1 = scene, 2 = chapter, …). */
+      list(chatId: string, options?: { tier?: number; userId?: string }): Promise<MemoryConsolidationDTO[]>;
+      /** The most recent arc across all tiers, or `null` if none have been produced. */
+      latestArc(chatId: string, userId?: string): Promise<MemoryConsolidationDTO | null>;
+      /**
+       * Trigger an async consolidation pass over the chat's chunks. Returns
+       * immediately; new arcs become visible via `list()` once the
+       * background job completes.
+       */
+      run(chatId: string, userId?: string): Promise<void>;
+    };
+
+    salience: {
+      /** List salience records for a chat's chunks, ordered by `scoredAt`. */
+      list(chatId: string, options?: { limit?: number; offset?: number; userId?: string }): Promise<MemorySalienceDTO[]>;
+    };
+
+    vaults: {
+      list(userId?: string): Promise<VaultDTO[]>;
+      /** Fetch a vault with its entities + relations. Returns `null` if not found or not owned by the resolved user. */
+      get(vaultId: string, userId?: string): Promise<VaultWithContentsDTO | null>;
+      getChunks(vaultId: string, userId?: string): Promise<VaultChunkDTO[]>;
+      /**
+       * Snapshot a chat's cortex state into a new vault. Copies entities,
+       * relations and chunk content; LanceDB embeddings are copied in the
+       * background.
+       */
+      create(input: VaultCreateDTO, userId?: string): Promise<VaultDTO>;
+      rename(vaultId: string, name: string, userId?: string): Promise<boolean>;
+      delete(vaultId: string, userId?: string): Promise<boolean>;
+      /** Re-run the LanceDB chunk copy for a vault (e.g. after an embedding model swap). */
+      reindex(vaultId: string, userId?: string): Promise<VaultReindexResultDTO>;
+    };
+
+    links: {
+      list(chatId: string, userId?: string): Promise<ChatLinkDTO[]>;
+      /**
+       * Attach a vault or set up a chat-to-chat interlink. For interlinks,
+       * pass `bidirectional: true` to also create the reverse link.
+       */
+      attach(input: ChatLinkAttachDTO, userId?: string): Promise<ChatLinkDTO[]>;
+      remove(chatId: string, linkId: string, userId?: string): Promise<boolean>;
+      toggle(chatId: string, linkId: string, enabled: boolean, userId?: string): Promise<boolean>;
+    };
+
+    chatMemory: {
+      /**
+       * List the vectorized chunks for a chat. Useful for inspecting the
+       * raw retrieval index used by the `{{memories}}` macro.
+       */
+      listChunks(chatId: string, userId?: string): Promise<ChatChunkDTO[]>;
+      /** Top-K chat memory chunks for a chat via hybrid vector + BM25 search. */
+      get(chatId: string, options?: { topK?: number; userId?: string }): Promise<ChatMemoryResultDTO>;
+      /**
+       * Warm long-term chat memory: rebuilds chunks if stale and queues any
+       * pending chunk vectorizations. Pass `force: true` to rebuild even
+       * when the chunk hash is fresh.
+       */
+      warm(chatId: string, options?: { force?: boolean; userId?: string }): Promise<ChatMemoryWarmupResultDTO>;
+      /** Drop the cached `{{memories}}` retrieval result for a chat. */
+      invalidate(chatId: string, userId?: string): Promise<void>;
+    };
+
+    stats: {
+      usage(chatId: string, userId?: string): Promise<CortexUsageStatsDTO>;
+      ingestionStatus(chatId: string, userId?: string): Promise<CortexIngestionStatusDTO | null>;
+      ingestionTelemetry(chatId: string, userId?: string): Promise<CortexIngestionTelemetryDTO>;
+    };
+  };
+
   /**
    * Personas CRUD (permission: "personas").
    * Manage user personas (identity profiles).
@@ -1158,6 +1373,74 @@ export interface SpindleAPI {
     }>;
   };
 
+  /**
+   * Web search (permission: `"web_search"`).
+   *
+   * Execute searches via the user's configured web search provider
+   * (currently SearXNG; additional providers will be added over time) and
+   * read the safe view of their web search settings. The host enforces all
+   * upstream limits (engine list, max result count, max pages to scrape,
+   * timeouts) — extensions cannot supply their own endpoint or API key.
+   *
+   * For user-scoped extensions, `userId` is inferred from the extension
+   * owner. Operator-scoped extensions should pass the `userId` of the user
+   * whose search engine should run the query.
+   *
+   * @example
+   * ```ts
+   * // Pre-flight: confirm web search is configured before issuing a query.
+   * const settings = await spindle.webSearch.getSettings()
+   * if (!settings.enabled) {
+   *   spindle.toast.warning('Configure a web search provider in Settings → Web Search first.')
+   *   return
+   * }
+   *
+   * // Full enriched query — scrapes the top-N pages and returns a
+   * // ready-to-inject context block.
+   * const enriched = await spindle.webSearch.query({
+   *   query: 'latest LLM benchmark results',
+   *   count: 5,
+   * })
+   * await spindle.chat.appendMessage(chatId, {
+   *   role: 'system',
+   *   content: enriched.context ?? '',
+   * })
+   *
+   * // Lightweight query — titles, URLs, snippets only.
+   * const quick = await spindle.webSearch.query({
+   *   query: 'who won the 2026 world cup',
+   *   scrape: false,
+   * })
+   * for (const row of quick.results) {
+   *   spindle.log.info(`${row.title} — ${row.url}`)
+   * }
+   * ```
+   */
+  webSearch: {
+    /**
+     * Run a search against the user's configured provider.
+     *
+     * Rejects with `"Web search is disabled"` when the user has not
+     * configured a provider, and with `"Web search API URL is not configured"`
+     * when the upstream endpoint is missing. Other upstream errors surface
+     * as `Error("SearXNG returned HTTP NNN")` (or equivalent for future
+     * providers).
+     *
+     * When `input.scrape` is `false`, `documents` and `context` are omitted
+     * from the response. Otherwise the host scrapes up to
+     * `WebSearchSettingsDTO.maxPagesToScrape` results, fills in
+     * `documents[].content`, and assembles a prompt-ready `context` block.
+     */
+    query(input: WebSearchRequestDTO): Promise<WebSearchResponseDTO>;
+    /**
+     * Read the safe view of the user's web search configuration. The raw
+     * API key is never exposed — only `hasApiKey` indicates whether one is
+     * on file. Useful for branching on `enabled` / `provider` /
+     * `maxResultCount` before issuing a query.
+     */
+    getSettings(userId?: string): Promise<WebSearchSettingsDTO>;
+  };
+
   /**
    * Text editor (free tier — no permission needed).
    * Opens the native Lumiverse expanded text editor modal on the user's