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

package/lib/types/contracts.d.ts

@@ -0,0 +1,496 @@
+/** Contracts owned by the Memory Spaces Source, not the Mnemon Core. */
+export type { MemoryJsonValue as JsonValue } from 'dsh-mnemon/contracts';
+export type MemoryProviderId = string;
+export type MemoryProviderConnectionValue = string | number | boolean;
+export type MemoryProviderConnection = Record<string, MemoryProviderConnectionValue>;
+export interface MemoryProviderIcon {
+    /** Bundled brand token, self-contained image data, or a short text glyph. */
+    kind: 'brand' | 'data-url' | 'glyph';
+    value: string;
+}
+export interface MemoryProviderConfigOption {
+    value: string;
+    label: string;
+    /** Optional Host-provided translation key; clients fall back to label. */
+    i18nKey?: string;
+}
+export 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[];
+}
+export type MemoryPlacementCapability = 'graph' | 'entities' | 'related' | 'exact-write' | 'link' | 'forget';
+export type MemoryPlacementPreference = 'balanced' | 'local-first' | 'shared-first';
+export interface MemoryPlacementRules {
+    allowedProviderIds?: MemoryProviderId[];
+    dataBoundary?: 'allow-remote' | 'local-only';
+    requiredCapabilities?: MemoryPlacementCapability[];
+    preference?: MemoryPlacementPreference;
+}
+/** Persistent policy for provider selection during Agent-supervised memory distillation. */
+export 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>>;
+}
+export 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>>;
+}
+export interface AutomaticMemoryPlacementRequest {
+    mode: 'automatic';
+    /** User-authored routing guidance. Hard rules above always take precedence. */
+    prompt?: string;
+    rules?: MemoryPlacementRules;
+}
+export 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;
+}
+export 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';
+}
+export 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;
+}
+export 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;
+}
+export interface MemoryProviderServiceCatalog {
+    providers: MemoryProviderDescriptor[];
+    items: MemoryProviderServiceView[];
+    generatedAt: string;
+}
+export interface UpdateMemoryProviderServiceRequest {
+    providerId: MemoryProviderId;
+    settings: MemoryProviderConnection;
+    enabled?: boolean;
+    clearSecrets?: string[];
+}
+export interface MemoryProviderRuntimeStatus {
+    providerId: MemoryProviderId;
+    label: string;
+    icon?: MemoryProviderIcon;
+    enabled: boolean;
+    configured: boolean;
+    status: 'disabled' | 'idle' | 'healthy' | 'unhealthy';
+    memoryBodyCount: number;
+    activeMemoryBodyCount: number;
+    error?: string;
+}
+export 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;
+}
+export interface OpenVikingBodyConnection {
+    endpoint: string;
+    targetUri: string;
+    apiKey?: string;
+    account?: string;
+    user?: string;
+    actorPeerId?: string;
+}
+export interface MemoryBody {
+    id: string;
+    name: string;
+    description: string;
+    active: boolean;
+    dbPath: string;
+    provider: MemoryBodyProvider;
+    placement?: MemoryPlacementDecision;
+    createdAt: string;
+    updatedAt: string;
+}
+export 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;
+}
+export interface UpdateMemoryBodyRequest {
+    name?: string;
+    description?: string;
+    active?: boolean;
+    connection?: MemoryProviderConnection;
+    clearSecrets?: string[];
+    openViking?: Partial<OpenVikingBodyConnection> & {
+        clearApiKey?: boolean;
+    };
+}
+export interface MemoryBodyMetadataUpdate {
+    memoryBodyId: string;
+    title: string;
+    description: string;
+}
+export interface MemoryBodyMetadataMaintenanceResult {
+    delegated: true;
+    runId: string;
+    provider: string;
+    summary: string;
+    updates: MemoryBodyMetadataUpdate[];
+}
+export type Category = 'preference' | 'decision' | 'fact' | 'insight' | 'context' | 'general';
+export declare const CATEGORIES: readonly ["preference", "decision", "fact", "insight", "context", "general"];
+export type Source = 'user' | 'agent' | 'external';
+export declare const SOURCES: readonly ["user", "agent", "external"];
+export type EdgeType = 'temporal' | 'semantic' | 'causal' | 'entity';
+export declare const EDGE_TYPES: readonly ["temporal", "semantic", "causal", "entity"];
+export type Intent = 'WHY' | 'WHEN' | 'ENTITY' | 'GENERAL';
+export declare const INTENTS: readonly ["WHY", "WHEN", "ENTITY", "GENERAL"];
+export type RecallRelevanceTier = 'high' | 'medium' | 'low' | 'unknown';
+export 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;
+}
+export interface SearchRequest {
+    query: string;
+    mode?: 'smart' | 'keyword' | 'basic';
+    limit?: number;
+    category?: Category;
+    source?: Source;
+    intent?: Intent;
+    memoryBodyIds?: string[];
+}
+export interface RememberRequest {
+    content: string;
+    category?: Category;
+    importance?: number;
+    tags?: string[];
+    entities?: string[];
+    source?: Source;
+    memoryBodyId?: string;
+}
+export interface MemoryBodyStats {
+    totalInsights: number;
+    deletedInsights: number;
+    edgeCount: number;
+    oplogCount: number;
+    dbSizeBytes: number;
+    byCategory: Record<string, number>;
+    topEntities: Array<{
+        entity: string;
+        count: number;
+    }>;
+}
+export 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;
+}
+export 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;
+}
+export interface MemoryGraphNode extends Insight {
+    color: string;
+    graphId?: string;
+    kind?: 'memory' | 'entity' | 'space';
+    memoryBodyIds?: string[];
+    memoryBodyNames?: string[];
+    occurrenceCount?: number;
+}
+export interface MemoryGraphEdge {
+    sourceId: string;
+    targetId: string;
+    label: string;
+    color: string;
+    type?: EdgeType | 'scope';
+}
+export 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[];
+}
+export type MemoryReadMode = 'search' | 'graph' | 'projection' | 'enumerable' | 'query-only' | 'entities' | 'unsupported';
+export 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.
+ */
+export interface MemoryReadSource {
+    memoryBodyId: string;
+    memoryBodyName: string;
+    providerId: MemoryProviderId;
+    providerLabel: string;
+    mode: MemoryReadMode;
+    status: MemoryReadStatus;
+    itemCount: number;
+    edgeCount?: number;
+    hint?: string;
+    quality?: RecallQualityStats;
+}
+export interface RecallQualityStats {
+    policyId: string;
+    fallbackFrom?: string;
+    fetched: number;
+    retained: number;
+    selected: number;
+    droppedLowScore: number;
+    droppedNonPositiveScore: number;
+    droppedInvalidScore: number;
+    unscored: number;
+    unscaled: number;
+}
+export interface MemoryListRequest {
+    query?: string;
+    category?: Category;
+    limit?: number;
+    memoryBodyIds?: string[];
+}
+export interface MemoryListView {
+    items: MemoryGraphNode[];
+    total: number;
+    generatedAt: string;
+    /** Omitted only when talking to a pre-provider-aware Host. */
+    sources?: MemoryReadSource[];
+}
+export 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'>>;
+}
+export interface MemoryPlacementCandidate {
+    id: MemoryProviderId;
+    label: string;
+    kind: 'local' | 'remote';
+    configured: boolean;
+    summary: string;
+    capabilities: MemoryProviderCapabilities;
+}
+export interface PreparedMemoryPlacement {
+    prompt: string;
+    candidates: MemoryPlacementCandidate[];
+    appliedRules: string[];
+    selectorBrief: string;
+}
+export interface LlmMemoryPlacementSelection {
+    providerId: string;
+    reason: string;
+    confidence: string;
+}
+export declare const DEFAULT_EMBEDDING_ENDPOINT = "http://localhost:11434";
+export declare const DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
+export declare const EMBEDDING_PROTOCOL_AUTO = "auto";
+export declare const EMBEDDING_PROTOCOL_OLLAMA = "ollama";
+export declare const EMBEDDING_PROTOCOL_OPENAI = "openai";
+/** Default protocol defers to Mnemon's /v1 auto-detection. */
+export declare const DEFAULT_EMBEDDING_PROTOCOL = "auto";
+/** Wire protocols accepted by the embedding protocol override; single source for schema, resolver, and UI validation. */
+export declare const MNEMON_EMBEDDING_PROTOCOLS: readonly ["auto", "ollama", "openai"];
+export 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;
+}
+export interface ResolvedRecallQualityConfig {
+    policy: string;
+    lowScoreThreshold: number;
+    highScoreThreshold: number;
+    candidateMultiplier: number;
+    maxMediumResults: number;
+    maxUnknownResults: number;
+}
+export type MnemonEmbeddingProtocol = (typeof MNEMON_EMBEDDING_PROTOCOLS)[number];
+export 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;
+}
+export interface ResolvedMnemonEmbeddingConfig {
+    enabled: boolean;
+    endpoint: string;
+    model: string;
+    apiKey: string;
+    protocol: MnemonEmbeddingProtocol;
+}
+export 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. */
+export 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;
+    };
+}
+export interface EntityView {
+    items: Array<{
+        entity: string;
+        count: number;
+    }>;
+    insights: Insight[];
+    selected?: string;
+    /** Omitted only when talking to a pre-provider-aware Host. */
+    sources?: MemoryReadSource[];
+}

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "dsh-mnemon-source-memory-spaces",
+  "version": "0.5.0-rc.1",
+  "description": "Memory Spaces Source and its private Provider SDK.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./provider-sdk": {
+      "types": "./lib/provider-sdk.d.ts",
+      "default": "./lib/provider-sdk.js"
+    },
+    "./package.json": "./package.json",
+    "./testing": {
+      "types": "./lib/testing.d.ts",
+      "default": "./lib/testing.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./contracts": {
+      "types": "./lib/contracts.d.ts",
+      "default": "./lib/contracts.js"
+    }
+  },
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown && tsc -p tsconfig.client-types.json",
+    "test": "vitest run",
+    "verify": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "dsh-mnemon": "0.5.0-rc.1",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-rc.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "dsh-mnemon": "0.5.0-rc.1",
+    "dsh-mnemon-provider-byterover": "0.5.0-rc.1",
+    "dsh-mnemon-provider-hindsight": "0.5.0-rc.1",
+    "dsh-mnemon-provider-holographic": "0.5.0-rc.1",
+    "dsh-mnemon-provider-honcho": "0.5.0-rc.1",
+    "dsh-mnemon-provider-mem0": "0.5.0-rc.1",
+    "dsh-mnemon-provider-mnemon-native": "0.5.0-rc.1",
+    "dsh-mnemon-provider-openviking": "0.5.0-rc.1",
+    "dsh-mnemon-provider-retaindb": "0.5.0-rc.1",
+    "dsh-mnemon-provider-supermemory": "0.5.0-rc.1",
+    "jsdom": "^26.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "slots"
+      ],
+      "platform": "web",
+      "external": [
+        "dsh-mnemon/client"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "rc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omdsh-dev/dsh-mnemon.git",
+    "directory": "plugins/dsh-mnemon-source-memory-spaces"
+  },
+  "homepage": "https://github.com/omdsh-dev/dsh-mnemon/tree/main/plugins/dsh-mnemon-source-memory-spaces#readme",
+  "bugs": {
+    "url": "https://github.com/omdsh-dev/dsh-mnemon/issues"
+  }
+}