dsh-mnemon-source-memory-spaces 0.5.0-rc.1

package/lib/contracts.d.ts

@@ -0,0 +1,498 @@
+import { MemoryJsonValue as JsonValue } from "dsh-mnemon/contracts";
+//#region src/contracts.d.ts
+type MemoryProviderId = string;
+type MemoryProviderConnectionValue = string | number | boolean;
+type MemoryProviderConnection = Record<string, MemoryProviderConnectionValue>;
+interface MemoryProviderIcon {
+  /** Bundled brand token, self-contained image data, or a short text glyph. */
+  kind: 'brand' | 'data-url' | 'glyph';
+  value: string;
+}
+interface MemoryProviderConfigOption {
+  value: string;
+  label: string;
+  /** Optional Host-provided translation key; clients fall back to label. */
+  i18nKey?: string;
+}
+interface MemoryProviderConfigField {
+  key: string;
+  label: string;
+  /** Optional Host-provided translation key; clients fall back to label. */
+  i18nKey?: string;
+  /** Service fields are configured once in Settings; memory fields belong to each Memory Space. */
+  scope: 'service' | 'memory';
+  /** A reusable local data location presented with the same default/custom scope UI as Mnemon Native. */
+  role?: 'global-location';
+  input: 'text' | 'url' | 'secret' | 'number' | 'boolean' | 'select' | 'path';
+  required: boolean;
+  defaultValue?: MemoryProviderConnectionValue;
+  placeholder?: string;
+  help?: string;
+  min?: number;
+  max?: number;
+  maxLength?: number;
+  pattern?: string;
+  normalize?: 'trim-trailing-slash';
+  validationMessage?: string;
+  /** Seed an empty service default from this field on the first discovered Memory Space. */
+  discoveryDefaultFrom?: string;
+  options?: MemoryProviderConfigOption[];
+}
+type MemoryPlacementCapability = 'graph' | 'entities' | 'related' | 'exact-write' | 'link' | 'forget';
+type MemoryPlacementPreference = 'balanced' | 'local-first' | 'shared-first';
+interface MemoryPlacementRules {
+  allowedProviderIds?: MemoryProviderId[];
+  dataBoundary?: 'allow-remote' | 'local-only';
+  requiredCapabilities?: MemoryPlacementCapability[];
+  preference?: MemoryPlacementPreference;
+}
+/** Persistent policy for provider selection during Agent-supervised memory distillation. */
+interface MemoryPersistenceStrategy {
+  mode?: 'manual' | 'automatic';
+  /** Fixed provider in manual mode. */
+  providerId?: MemoryProviderId;
+  /** User-authored guidance used only after hard rules have filtered automatic candidates. */
+  prompt?: string;
+  rules?: MemoryPlacementRules;
+  /** Memory-level connection values for providers that may be selected by the policy. */
+  providerConnections?: Partial<Record<MemoryProviderId, MemoryProviderConnection>>;
+}
+interface ResolvedMemoryPersistenceStrategy {
+  mode: 'manual' | 'automatic';
+  providerId: MemoryProviderId;
+  prompt: string;
+  rules: {
+    allowedProviderIds: MemoryProviderId[];
+    dataBoundary: 'allow-remote' | 'local-only';
+    requiredCapabilities: MemoryPlacementCapability[];
+    preference: MemoryPlacementPreference;
+  };
+  providerConnections: Partial<Record<MemoryProviderId, MemoryProviderConnection>>;
+}
+interface AutomaticMemoryPlacementRequest {
+  mode: 'automatic';
+  /** User-authored routing guidance. Hard rules above always take precedence. */
+  prompt?: string;
+  rules?: MemoryPlacementRules;
+}
+interface MemoryPlacementDecision {
+  mode: 'automatic';
+  providerId: MemoryProviderId;
+  decidedBy: 'rules' | 'llm';
+  reason: string;
+  confidence: 'high' | 'medium' | 'low';
+  candidateProviderIds: MemoryProviderId[];
+  appliedRules: string[];
+  decidedAt: string;
+  runId?: string;
+  subagentProvider?: string;
+}
+interface MemoryProviderCapabilities {
+  search: boolean;
+  browse: boolean;
+  graph: boolean;
+  entities: boolean;
+  related: boolean;
+  remember: boolean;
+  link: boolean;
+  forget: boolean;
+  writeMode: 'exact' | 'async-extracting';
+  deletionMode: 'soft' | 'hard' | 'unsupported';
+}
+interface MemoryProviderDescriptor {
+  /** Provider implementation type; omitted when it is identical to id. */
+  typeId?: string;
+  id: MemoryProviderId;
+  label: string;
+  icon?: MemoryProviderIcon;
+  kind: 'local' | 'remote';
+  /** How the provider data scope reacts when DSH switches workspaces. */
+  workspaceBinding: 'automatic' | 'optional-override' | 'provider-global';
+  summary: string;
+  /** Optional Host-provided translation key; clients fall back to summary. */
+  summaryI18nKey?: string;
+  origin: 'native' | 'third-party';
+  capabilities: MemoryProviderCapabilities;
+  fields: MemoryProviderConfigField[];
+  /** Runtime projection: whether this scope has a usable saved service configuration. */
+  serviceConfigured?: boolean;
+}
+interface MemoryProviderServiceView {
+  providerId: MemoryProviderId;
+  enabled: boolean;
+  configured: boolean;
+  settings: MemoryProviderConnection;
+  configuredSecrets: string[];
+  /** Present only on the settings RPC so its password inputs can use native reveal/hide behavior. */
+  secretValues?: MemoryProviderConnection;
+}
+interface MemoryProviderServiceCatalog {
+  providers: MemoryProviderDescriptor[];
+  items: MemoryProviderServiceView[];
+  generatedAt: string;
+}
+interface UpdateMemoryProviderServiceRequest {
+  providerId: MemoryProviderId;
+  settings: MemoryProviderConnection;
+  enabled?: boolean;
+  clearSecrets?: string[];
+}
+interface MemoryProviderRuntimeStatus {
+  providerId: MemoryProviderId;
+  label: string;
+  icon?: MemoryProviderIcon;
+  enabled: boolean;
+  configured: boolean;
+  status: 'disabled' | 'idle' | 'healthy' | 'unhealthy';
+  memoryBodyCount: number;
+  activeMemoryBodyCount: number;
+  error?: string;
+}
+interface MemoryBodyProvider {
+  id: MemoryProviderId;
+  /** Implementation type; differs from id when one module has several child instances. */
+  typeId?: string;
+  label: string;
+  icon?: MemoryProviderIcon;
+  origin?: 'native' | 'third-party';
+  kind: 'local' | 'remote';
+  location: string;
+  targetUri?: string;
+  account?: string;
+  user?: string;
+  actorPeerId?: string;
+  apiKeyConfigured: boolean;
+  settings: MemoryProviderConnection;
+  configuredSecrets: string[];
+  capabilities: MemoryProviderCapabilities;
+}
+interface OpenVikingBodyConnection {
+  endpoint: string;
+  targetUri: string;
+  apiKey?: string;
+  account?: string;
+  user?: string;
+  actorPeerId?: string;
+}
+interface MemoryBody {
+  id: string;
+  name: string;
+  description: string;
+  active: boolean;
+  dbPath: string;
+  provider: MemoryBodyProvider;
+  placement?: MemoryPlacementDecision;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreateMemoryBodyRequest {
+  name: string;
+  description: string;
+  active?: boolean;
+  providerId?: MemoryProviderId;
+  connection?: MemoryProviderConnection;
+  /** Candidate-specific settings used only while resolving automatic placement. */
+  providerConnections?: Partial<Record<MemoryProviderId, MemoryProviderConnection>>;
+  openViking?: OpenVikingBodyConnection;
+  placement?: AutomaticMemoryPlacementRequest;
+}
+interface UpdateMemoryBodyRequest {
+  name?: string;
+  description?: string;
+  active?: boolean;
+  connection?: MemoryProviderConnection;
+  clearSecrets?: string[];
+  openViking?: Partial<OpenVikingBodyConnection> & {
+    clearApiKey?: boolean;
+  };
+}
+interface MemoryBodyMetadataUpdate {
+  memoryBodyId: string;
+  title: string;
+  description: string;
+}
+interface MemoryBodyMetadataMaintenanceResult {
+  delegated: true;
+  runId: string;
+  provider: string;
+  summary: string;
+  updates: MemoryBodyMetadataUpdate[];
+}
+type Category = 'preference' | 'decision' | 'fact' | 'insight' | 'context' | 'general';
+declare const CATEGORIES: readonly ["preference", "decision", "fact", "insight", "context", "general"];
+type Source = 'user' | 'agent' | 'external';
+declare const SOURCES: readonly ["user", "agent", "external"];
+type EdgeType = 'temporal' | 'semantic' | 'causal' | 'entity';
+declare const EDGE_TYPES: readonly ["temporal", "semantic", "causal", "entity"];
+type Intent = 'WHY' | 'WHEN' | 'ENTITY' | 'GENERAL';
+declare const INTENTS: readonly ["WHY", "WHEN", "ENTITY", "GENERAL"];
+type RecallRelevanceTier = 'high' | 'medium' | 'low' | 'unknown';
+interface Insight {
+  id: string;
+  content: string;
+  category?: string;
+  importance?: number;
+  tags?: string[];
+  entities?: string[];
+  source?: string;
+  score?: number;
+  /** Policy-normalized query relevance; absent for unknown Provider score scales. */
+  normalizedScore?: number;
+  /** Query relevance assigned by the active deterministic recall quality policy. */
+  relevanceTier?: RecallRelevanceTier;
+  /** Comparable rank score only when results were fused across providers. */
+  federatedScore?: number;
+  confidence?: string;
+  intent?: string;
+  matchedVia?: string;
+  createdAt?: string;
+  depth?: number;
+  edgeType?: string;
+  memoryBodyId?: string;
+  memoryBodyName?: string;
+  memoryProviderId?: MemoryProviderId;
+  /** Provider label captured with the result so Client UI never needs an id catalog. */
+  memoryProviderLabel?: string;
+  /** Owning Provider capabilities at read time; safe to expose to clients. */
+  memoryCapabilities?: MemoryProviderCapabilities;
+  externalUri?: string;
+}
+interface SearchRequest {
+  query: string;
+  mode?: 'smart' | 'keyword' | 'basic';
+  limit?: number;
+  category?: Category;
+  source?: Source;
+  intent?: Intent;
+  memoryBodyIds?: string[];
+}
+interface RememberRequest {
+  content: string;
+  category?: Category;
+  importance?: number;
+  tags?: string[];
+  entities?: string[];
+  source?: Source;
+  memoryBodyId?: string;
+}
+interface MemoryBodyStats {
+  totalInsights: number;
+  deletedInsights: number;
+  edgeCount: number;
+  oplogCount: number;
+  dbSizeBytes: number;
+  byCategory: Record<string, number>;
+  topEntities: Array<{
+    entity: string;
+    count: number;
+  }>;
+}
+interface MemoryBodyView extends MemoryBody {
+  /** True when Mnemon's persisted active-file selection points to this Store. */
+  mnemonDefault: boolean;
+  /** False when an external provider is disabled while its Memory Space registration remains preserved. */
+  providerEnabled?: boolean;
+  healthy: boolean;
+  /** A fast directory response is visible while provider health resolves independently. */
+  statusLoading?: boolean;
+  error?: string;
+  stats?: MemoryBodyStats;
+}
+interface MemoryBodyCatalog {
+  items: MemoryBodyView[];
+  providers: MemoryProviderDescriptor[];
+  /** Sanitized policy exposed to memory workers; provider connection values are never included. */
+  persistenceStrategy?: Omit<ResolvedMemoryPersistenceStrategy, 'providerConnections'>;
+  total: number;
+  activeCount: number;
+  directory: string;
+  generatedAt: string;
+}
+interface MemoryGraphNode extends Insight {
+  color: string;
+  graphId?: string;
+  kind?: 'memory' | 'entity' | 'space';
+  memoryBodyIds?: string[];
+  memoryBodyNames?: string[];
+  occurrenceCount?: number;
+}
+interface MemoryGraphEdge {
+  sourceId: string;
+  targetId: string;
+  label: string;
+  color: string;
+  type?: EdgeType | 'scope';
+}
+interface MemoryGraphSnapshot {
+  nodes: MemoryGraphNode[];
+  edges: MemoryGraphEdge[];
+  generatedAt: string;
+  memoryBodies?: Array<Pick<MemoryBody, 'id' | 'name' | 'active'>>;
+  /** Per-space observation state for capability-aware overview rendering. */
+  sources?: MemoryReadSource[];
+}
+type MemoryReadMode = 'search' | 'graph' | 'projection' | 'enumerable' | 'query-only' | 'entities' | 'unsupported';
+type MemoryReadStatus = 'ready' | 'empty' | 'query-required' | 'unsupported' | 'unavailable';
+/**
+ * One provider-backed Memory Space participating in a read surface.
+ *
+ * The mode describes what the provider can truthfully expose; status describes
+ * the result of this particular read. Keeping those dimensions separate lets
+ * the UI distinguish an empty graph from a flat projection, a query-only
+ * engine, and an unavailable connection.
+ */
+interface MemoryReadSource {
+  memoryBodyId: string;
+  memoryBodyName: string;
+  providerId: MemoryProviderId;
+  providerLabel: string;
+  mode: MemoryReadMode;
+  status: MemoryReadStatus;
+  itemCount: number;
+  edgeCount?: number;
+  hint?: string;
+  quality?: RecallQualityStats;
+}
+interface RecallQualityStats {
+  policyId: string;
+  fallbackFrom?: string;
+  fetched: number;
+  retained: number;
+  selected: number;
+  droppedLowScore: number;
+  droppedNonPositiveScore: number;
+  droppedInvalidScore: number;
+  unscored: number;
+  unscaled: number;
+}
+interface MemoryListRequest {
+  query?: string;
+  category?: Category;
+  limit?: number;
+  memoryBodyIds?: string[];
+}
+interface MemoryListView {
+  items: MemoryGraphNode[];
+  total: number;
+  generatedAt: string;
+  /** Omitted only when talking to a pre-provider-aware Host. */
+  sources?: MemoryReadSource[];
+}
+interface MemoryBodyMetadataSample {
+  memoryBodyId: string;
+  name: string;
+  description: string;
+  providerId: MemoryBody['provider']['id'];
+  providerLabel: string;
+  method: 'native-basic' | 'browse' | 'search';
+  evidence: Array<Pick<Insight, 'content' | 'category' | 'entities'>>;
+}
+interface MemoryPlacementCandidate {
+  id: MemoryProviderId;
+  label: string;
+  kind: 'local' | 'remote';
+  configured: boolean;
+  summary: string;
+  capabilities: MemoryProviderCapabilities;
+}
+interface PreparedMemoryPlacement {
+  prompt: string;
+  candidates: MemoryPlacementCandidate[];
+  appliedRules: string[];
+  selectorBrief: string;
+}
+interface LlmMemoryPlacementSelection {
+  providerId: string;
+  reason: string;
+  confidence: string;
+}
+declare const DEFAULT_EMBEDDING_ENDPOINT = "http://localhost:11434";
+declare const DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
+declare const EMBEDDING_PROTOCOL_AUTO = "auto";
+declare const EMBEDDING_PROTOCOL_OLLAMA = "ollama";
+declare const EMBEDDING_PROTOCOL_OPENAI = "openai";
+/** Default protocol defers to Mnemon's /v1 auto-detection. */
+declare const DEFAULT_EMBEDDING_PROTOCOL = "auto";
+/** Wire protocols accepted by the embedding protocol override; single source for schema, resolver, and UI validation. */
+declare const MNEMON_EMBEDDING_PROTOCOLS: readonly ["auto", "ollama", "openai"];
+interface RecallQualityConfig {
+  /** Registered deterministic policy id. */
+  policy?: string;
+  lowScoreThreshold?: number;
+  highScoreThreshold?: number;
+  /** Provider candidate expansion before quality filtering, from 1 through 5. */
+  candidateMultiplier?: number;
+  /** Maximum medium-relevance rows admitted by the strict policy. */
+  maxMediumResults?: number;
+  /** Maximum unknown-scale or unscored rows admitted by the strict policy. */
+  maxUnknownResults?: number;
+}
+interface ResolvedRecallQualityConfig {
+  policy: string;
+  lowScoreThreshold: number;
+  highScoreThreshold: number;
+  candidateMultiplier: number;
+  maxMediumResults: number;
+  maxUnknownResults: number;
+}
+type MnemonEmbeddingProtocol = (typeof MNEMON_EMBEDDING_PROTOCOLS)[number];
+interface MnemonEmbeddingConfig {
+  /** When false or omitted, Mnemon keeps its inherited environment and built-in defaults. */
+  enabled?: boolean;
+  endpoint?: string;
+  model?: string;
+  /** Optional Bearer token forwarded as MNEMON_EMBED_API_KEY for OpenAI-compatible endpoints. */
+  apiKey?: string;
+  /** Explicit wire-protocol override; 'auto' keeps Mnemon's /v1 auto-detection. */
+  protocol?: MnemonEmbeddingProtocol;
+}
+interface ResolvedMnemonEmbeddingConfig {
+  enabled: boolean;
+  endpoint: string;
+  model: string;
+  apiKey: string;
+  protocol: MnemonEmbeddingProtocol;
+}
+interface MnemonEmbeddingStatus {
+  available: boolean;
+  model: string;
+  /** Protocol Mnemon resolved for the embedding endpoint; omitted when the CLI does not report one. */
+  protocol?: string;
+  totalInsights: number;
+  embedded: number;
+  coverage: string;
+}
+/** Domain status only; workbench/lifecycle status belongs to the default adapter. */
+interface MemorySpacesStatus {
+  healthy: boolean;
+  error?: string;
+  version?: string;
+  cliPath: string;
+  commandFound: boolean;
+  dataDir: string;
+  store: string;
+  mnemonDefaultStore: string;
+  dshActiveStores: string[];
+  writeEnabled: boolean;
+  timeoutMs: number;
+  defaultRecallLimit: number;
+  recallQuality: ResolvedRecallQualityConfig;
+  memoryBodyDirectory: string;
+  memoryBodies: MemoryBodyView[];
+  providerServices?: MemoryProviderRuntimeStatus[];
+  stats?: MemoryBodyStats & {
+    dbPath?: string;
+  };
+}
+interface EntityView {
+  items: Array<{
+    entity: string;
+    count: number;
+  }>;
+  insights: Insight[];
+  selected?: string;
+  /** Omitted only when talking to a pre-provider-aware Host. */
+  sources?: MemoryReadSource[];
+}
+//#endregion
+export { AutomaticMemoryPlacementRequest, CATEGORIES, Category, CreateMemoryBodyRequest, DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_PROTOCOL, EDGE_TYPES, EMBEDDING_PROTOCOL_AUTO, EMBEDDING_PROTOCOL_OLLAMA, EMBEDDING_PROTOCOL_OPENAI, EdgeType, EntityView, INTENTS, Insight, Intent, type JsonValue, LlmMemoryPlacementSelection, MNEMON_EMBEDDING_PROTOCOLS, MemoryBody, MemoryBodyCatalog, MemoryBodyMetadataMaintenanceResult, MemoryBodyMetadataSample, MemoryBodyMetadataUpdate, MemoryBodyProvider, MemoryBodyStats, MemoryBodyView, MemoryGraphEdge, MemoryGraphNode, MemoryGraphSnapshot, MemoryListRequest, MemoryListView, MemoryPersistenceStrategy, MemoryPlacementCandidate, MemoryPlacementCapability, MemoryPlacementDecision, MemoryPlacementPreference, MemoryPlacementRules, MemoryProviderCapabilities, MemoryProviderConfigField, MemoryProviderConfigOption, MemoryProviderConnection, MemoryProviderConnectionValue, MemoryProviderDescriptor, MemoryProviderIcon, MemoryProviderId, MemoryProviderRuntimeStatus, MemoryProviderServiceCatalog, MemoryProviderServiceView, MemoryReadMode, MemoryReadSource, MemoryReadStatus, MemorySpacesStatus, MnemonEmbeddingConfig, MnemonEmbeddingProtocol, MnemonEmbeddingStatus, OpenVikingBodyConnection, PreparedMemoryPlacement, RecallQualityConfig, RecallQualityStats, RecallRelevanceTier, RememberRequest, ResolvedMemoryPersistenceStrategy, ResolvedMnemonEmbeddingConfig, ResolvedRecallQualityConfig, SOURCES, SearchRequest, Source, UpdateMemoryBodyRequest, UpdateMemoryProviderServiceRequest };

package/lib/contracts.js

@@ -0,0 +1,41 @@
+//#region src/contracts.ts
+const CATEGORIES = [
+	"preference",
+	"decision",
+	"fact",
+	"insight",
+	"context",
+	"general"
+];
+const SOURCES = [
+	"user",
+	"agent",
+	"external"
+];
+const EDGE_TYPES = [
+	"temporal",
+	"semantic",
+	"causal",
+	"entity"
+];
+const INTENTS = [
+	"WHY",
+	"WHEN",
+	"ENTITY",
+	"GENERAL"
+];
+const DEFAULT_EMBEDDING_ENDPOINT = "http://localhost:11434";
+const DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
+const EMBEDDING_PROTOCOL_AUTO = "auto";
+const EMBEDDING_PROTOCOL_OLLAMA = "ollama";
+const EMBEDDING_PROTOCOL_OPENAI = "openai";
+/** Default protocol defers to Mnemon's /v1 auto-detection. */
+const DEFAULT_EMBEDDING_PROTOCOL = EMBEDDING_PROTOCOL_AUTO;
+/** Wire protocols accepted by the embedding protocol override; single source for schema, resolver, and UI validation. */
+const MNEMON_EMBEDDING_PROTOCOLS = [
+	EMBEDDING_PROTOCOL_AUTO,
+	EMBEDDING_PROTOCOL_OLLAMA,
+	EMBEDDING_PROTOCOL_OPENAI
+];
+//#endregion
+export { CATEGORIES, DEFAULT_EMBEDDING_ENDPOINT, DEFAULT_EMBEDDING_MODEL, DEFAULT_EMBEDDING_PROTOCOL, EDGE_TYPES, EMBEDDING_PROTOCOL_AUTO, EMBEDDING_PROTOCOL_OLLAMA, EMBEDDING_PROTOCOL_OPENAI, INTENTS, MNEMON_EMBEDDING_PROTOCOLS, SOURCES };

package/lib/definitions-CEpa-tvm.d.ts

@@ -0,0 +1,135 @@
+import { EdgeType, Insight, JsonValue, MemoryBody, MemoryBodyStats, MemoryGraphSnapshot, MemoryListRequest, MemoryProviderCapabilities, MemoryProviderConfigField, MemoryProviderConnection, MemoryProviderDescriptor, MemoryProviderIcon, RememberRequest, SearchRequest } from "./contracts.js";
+import { Context, Plugin } from "@deepseek-ai/cordis";
+//#region src/providers/adapter.d.ts
+/** Minimum parent authority a Provider needs; no private controller class. */
+interface MemorySpaceAuthority {
+  readonly runner: {
+    effectiveDataDir(): string;
+  };
+  list(): MemoryBody[];
+  providerConnection(id: string, expectedProviderId?: string): MemoryProviderConnection;
+}
+/** Scoped command transport consumed by the Native Provider. */
+interface MemorySpaceNativeRunner {
+  runJson(args: readonly string[], options?: {
+    signal?: AbortSignal;
+    store?: string;
+  }): Promise<JsonValue>;
+  runText(args: readonly string[], options?: {
+    signal?: AbortSignal;
+    store?: string;
+  }): Promise<string>;
+}
+interface MemoryProviderAdapterFactoryContext {
+  memoryBodies: MemorySpaceAuthority;
+  config: {
+    timeoutMs: number;
+    defaultRecallLimit?: number;
+  };
+  nativeRunner?: MemorySpaceNativeRunner;
+}
+interface ProviderBodyStatus {
+  healthy: boolean;
+  error?: string;
+  stats?: MemoryBodyStats;
+}
+interface ProviderSearchResult {
+  results: Insight[];
+  hint?: string;
+}
+interface ProviderScoreSemantics {
+  /** Provider promises a finite relevance score in 0..1 where larger is better. */
+  kind: 'normalized-relevance';
+}
+type MemoryProviderScoreSemantics = 'normalized-relevance' | 'provider-native' | 'none';
+declare const NORMALIZED_RELEVANCE_SCORE: ProviderScoreSemantics;
+/** One provider-owned namespace projected into DSH as a Memory Space. */
+interface ProviderMemorySpace {
+  /** Stable identifier owned by the provider, never a DSH-generated title. */
+  externalId: string;
+  name: string;
+  description: string;
+  connection: MemoryProviderConnection;
+}
+/**
+ * Third-layer memory data plane. DSH owns routing and lifecycle; adapters own
+ * only one body's persistence and retrieval semantics.
+ */
+interface MemoryProviderAdapter {
+  readonly id: MemoryBody['provider']['id'];
+  readonly scoreSemantics?: ProviderScoreSemantics;
+  /** Enumerate the complete set of namespaces visible to this service connection. */
+  discover?(connection: MemoryProviderConnection, signal?: AbortSignal): Promise<ProviderMemorySpace[]>;
+  /** Drop a short-lived health result before an explicit user reconnect. */
+  invalidateStatus?(memoryBodyId?: string): void;
+  status(body: MemoryBody, signal?: AbortSignal): Promise<ProviderBodyStatus>;
+  search(body: MemoryBody, request: SearchRequest, signal?: AbortSignal): Promise<ProviderSearchResult>;
+  graph(body: MemoryBody, signal?: AbortSignal): Promise<MemoryGraphSnapshot>;
+  list(body: MemoryBody, request: MemoryListRequest, signal?: AbortSignal): Promise<Insight[]>;
+  remember(body: MemoryBody, request: RememberRequest, signal?: AbortSignal): Promise<JsonValue>;
+  /** Optional cheap bounded metadata sampling, without a graph projection. */
+  metadataSample?(body: MemoryBody, limit: number, signal?: AbortSignal): Promise<Insight[]>;
+  /** Persist an ordered host-authorized batch and return one receipt per request. */
+  rememberMany?(body: MemoryBody, requests: readonly RememberRequest[], signal?: AbortSignal): Promise<JsonValue[]>;
+  related?(body: MemoryBody, id: string, depth: number, edge?: EdgeType, signal?: AbortSignal): Promise<Insight[]>;
+  link?(body: MemoryBody, sourceId: string, targetId: string, type: EdgeType, weight: number, reason?: string, signal?: AbortSignal): Promise<JsonValue>;
+  forget?(body: MemoryBody, id: string, signal?: AbortSignal): Promise<JsonValue>;
+  /** Release generation-owned clients, timers, pools, or subprocess handles. */
+  dispose?(): void | Promise<void>;
+}
+//#endregion
+//#region src/providers/definitions.d.ts
+declare const MEMORY_SPACE_PROVIDER_API_VERSION: "dsh-mnemon.memory-space-provider/v1";
+type MemorySpaceProviderScoreSemantics = 'normalized-relevance' | 'provider-native' | 'none';
+/**
+ * Complete, JSON-safe definition metadata owned by the Memory Spaces Source.
+ * It is deliberately not a Mnemon-wide contribution manifest.
+ */
+interface MemorySpaceProviderManifest {
+  apiVersion: typeof MEMORY_SPACE_PROVIDER_API_VERSION;
+  kind: 'provider';
+  typeId: string;
+  packageName: string;
+  version: string;
+  label: string;
+  icon?: MemoryProviderIcon | undefined;
+  summary: string;
+  summaryI18nKey?: string;
+  origin: 'native' | 'third-party';
+  locality: 'local' | 'remote';
+  workspaceBinding: MemoryProviderDescriptor['workspaceBinding'];
+  capabilities: MemoryProviderCapabilities;
+  fields: MemoryProviderConfigField[];
+  secrets: string[];
+  scoreSemantics: MemorySpaceProviderScoreSemantics;
+}
+interface MemorySpaceProviderRuntimeContext extends MemoryProviderAdapterFactoryContext {
+  /** Stable identity of this child mount inside one Memory Spaces Source. */
+  providerInstanceId: string;
+  manifest: MemorySpaceProviderManifest;
+}
+interface MemorySpaceProviderDefinition {
+  manifest: MemorySpaceProviderManifest;
+  create(context: MemorySpaceProviderRuntimeContext): MemoryProviderAdapter;
+}
+type MemorySpaceProviderDisposer = () => void | Promise<void>;
+/** Capability handed directly to one child Fiber through a lexical closure. */
+interface MemorySpaceProviderHost {
+  install(owner: Context, definition: MemorySpaceProviderDefinition): MemorySpaceProviderDisposer;
+}
+/** Typed child module mounted only by a Memory Spaces parent Fiber. */
+interface MemorySpaceProviderModule<Config = undefined> {
+  readonly id: string;
+  /** Optional Cordis-compatible Standard Schema used for this child config. */
+  readonly Config?: Plugin.Base<Config>['Config'];
+  apply(ctx: Context, host: MemorySpaceProviderHost, config: Config): void | Promise<void>;
+}
+interface MemorySpaceProviderEntry<Config = unknown> {
+  instanceId: string;
+  module: MemorySpaceProviderModule<Config>;
+  config: Config;
+}
+declare function defineMemorySpaceProvider<Config>(module: MemorySpaceProviderModule<Config>): MemorySpaceProviderModule<Config>;
+declare function defineMemorySpaceProviderDefinition(definition: MemorySpaceProviderDefinition): MemorySpaceProviderDefinition;
+//#endregion
+export { NORMALIZED_RELEVANCE_SCORE as _, MemorySpaceProviderHost as a, ProviderScoreSemantics as b, MemorySpaceProviderRuntimeContext as c, defineMemorySpaceProviderDefinition as d, MemoryProviderAdapter as f, MemorySpaceNativeRunner as g, MemorySpaceAuthority as h, MemorySpaceProviderEntry as i, MemorySpaceProviderScoreSemantics as l, MemoryProviderScoreSemantics as m, MemorySpaceProviderDefinition as n, MemorySpaceProviderManifest as o, MemoryProviderAdapterFactoryContext as p, MemorySpaceProviderDisposer as r, MemorySpaceProviderModule as s, MEMORY_SPACE_PROVIDER_API_VERSION as t, defineMemorySpaceProvider as u, ProviderBodyStatus as v, ProviderSearchResult as x, ProviderMemorySpace as y };