lumiverse-spindle-types 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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 ──────────────────────────────────────────────
 
@@ -2281,6 +2290,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") ────────────────

package/src/index.ts

@@ -210,6 +210,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,6 +15,9 @@
  * - "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
  */
 export type SpindlePermission =
@@ -35,6 +38,7 @@ export type SpindlePermission =
   | "world_books"
   | "regex_scripts"
   | "databanks"
+  | "memories"
   | "personas"
   | "push_notification"
   | "image_gen"
@@ -60,6 +64,7 @@ export const ALL_PERMISSIONS: readonly SpindlePermission[] = [
   "world_books",
   "regex_scripts",
   "databanks",
+  "memories",
   "personas",
   "push_notification",
   "image_gen",

package/src/spindle-api.ts

@@ -104,6 +104,31 @@ import type {
   SharedRpcRequestContextDTO,
   SharedRpcEndpointPolicyDTO,
 } 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 +852,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).