mindgraph 0.15.1 → 0.17.0

package/dist/index.d.ts

@@ -114,7 +114,10 @@ interface EnrichedSearchResponse {
 interface PathStep {
     node_uid: string;
     label: string;
+    /** Plain semantic node type; typed shortcuts unwrap `{Custom: "TYPE"}`. */
     node_type: string;
+    /** Plain semantic relation name. Typed traversal shortcuts normalize the
+     * server's externally tagged `{Custom: "NAME"}` wire form to this string. */
     edge_type: string | null;
     depth: number;
     parent_uid: string | null;
@@ -524,6 +527,13 @@ interface SessionRequest {
     model?: string;
     props?: Record<string, unknown>;
     agent_id?: string;
+    /**
+     * Server-side replay key (`/memory/session` supports it on every action):
+     * the same key with the same payload returns the stored receipt; the same
+     * key with a different payload is a 409. Use a host's operation id so a
+     * re-run compaction capture or trace is byte-identical.
+     */
+    idempotency_key?: string;
 }
 /** Caller-authored content for a governed skill candidate. */
 interface SkillDistillProps {
@@ -559,13 +569,92 @@ interface SkillDistillRequest extends DistillRequestBase {
 }
 type DistillRequest = SummaryOrLessonDistillRequest | SkillDistillRequest;
 interface MemoryConfigRequest {
-    action: "set_preference" | "get_preferences" | "set_policy" | "get_policies";
+    action: "set_preference" | "get_preferences" | "set_policy" | "get_policies" | "set_remember_instructions" | "get_remember_instructions";
     label?: string;
     summary?: string;
     confidence?: number;
     salience?: number;
     props?: Record<string, unknown>;
     agent_id?: string;
+    /** Target Space for the `remember_instructions` actions (default: org space). */
+    space_uid?: string;
+    /** Instruction text for `set_remember_instructions`; empty clears it. */
+    text?: string;
+}
+interface RememberOptions {
+    /**
+     * Caller-owned idempotency and upsert key. Re-sending the same `custom_id`
+     * with new text edits the same node (version bump, history kept); with the
+     * same text it is a no-op.
+     */
+    custom_id?: string;
+    /** Node label; defaults to the first line of `text` (80 chars). */
+    label?: string;
+    props?: Record<string, unknown>;
+    confidence?: number;
+    salience?: number;
+    agent_id?: string;
+    /** Explicit target Space; default is the org space. */
+    space_uid?: string;
+    /**
+     * Without a `custom_id`, what to do on an exact write-time-resolution hit:
+     * `reuse` (default) returns the existing node, `create` inserts anyway.
+     */
+    on_near_duplicate?: "reuse" | "create";
+}
+interface RememberRequest extends RememberOptions {
+    text: string;
+}
+interface RememberResponse {
+    uid: string;
+    custom_id: string | null;
+    /** `inserted` (201) | `updated` | `unchanged` | `reused` (200). */
+    action: "inserted" | "updated" | "unchanged" | "reused";
+    label: string;
+    version: number;
+    space_uid: string;
+    /** True when the vector was stored before this response. */
+    embedded: boolean;
+    searchable: {
+        bm25: boolean;
+        vector: boolean;
+    };
+    near_duplicates: unknown[];
+    /** The Space's `remember_instructions`, if set. */
+    remember_instructions: string | null;
+}
+type ForgetTarget = {
+    uid: string;
+    custom_id?: never;
+} | {
+    custom_id: string;
+    uid?: never;
+};
+interface ForgetOptions {
+    /** Preview the affected edges without changing anything. */
+    dry_run?: boolean;
+    /** Also tombstone connected edges (default true). */
+    cascade?: boolean;
+    reason?: string;
+    agent_id?: string;
+}
+type ForgetRequest = ForgetTarget & ForgetOptions;
+interface ForgetResponse {
+    uid: string;
+    label: string;
+    dry_run: boolean;
+    cascade: boolean;
+    /** Present on a dry run. */
+    would_tombstone_edges?: number;
+    /** Present after execution. */
+    action?: "forgotten";
+    edges_tombstoned?: number;
+    /** Edge uids removed (or that would be); undo each with `/evolve restore_edge`. */
+    edge_uids: string[];
+    undo: {
+        node: string;
+        edges: string;
+    };
 }
 interface MemorySyncRequest {
     action: "scan" | "begin" | "record" | "finalize" | "status" | "abandon";
@@ -690,7 +779,7 @@ interface RetrieveRequest {
      * Retrieval action. Note: `"semantic"` requires a configured embedding
      * provider on the server; for semantic search use `retrieveContext()` instead.
      */
-    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "stale_derivations" | "preferences" | "layer" | "recent";
+    action: "text" | "semantic" | "hybrid" | "active_goals" | "open_questions" | "weak_claims" | "pending_approvals" | "unresolved_contradictions" | "merge_candidates" | "stale_derivations" | "curation_counts" | "preferences" | "layer" | "recent";
     /**
      * Required for `"text"`, `"semantic"`, `"hybrid"`. Optional for
      * `"preferences"`: with a `query` you get topic-relevant preferences (the
@@ -734,6 +823,13 @@ interface RetrieveRequest {
      * provenance for citing "which teammate's notes" (D3). Requires server ≥ 1.8.0.
      */
     include_sources?: boolean;
+    /** Re-admit operational ledger and work-state nodes, excluded by default. */
+    include_ledger?: boolean;
+    /**
+     * Post-filter on how the node was created: `"document"`, `"session"` or
+     * `"agent"`.
+     */
+    source?: "document" | "session" | "agent";
 }
 interface TraverseRequest {
     action: "chain" | "neighborhood" | "path" | "subgraph" | "top_k_paths";
@@ -905,6 +1001,81 @@ interface RetrieveContextRequest {
      * Windowed nodes then carry `valid_at_time` instead of `currently_valid`.
      */
     valid_at?: string;
+    /**
+     * Point-in-time perspective: answer with what had been **stated** by this
+     * ISO-8601 date. A node is admitted when at least one of its source
+     * documents was stated (`occurred_at`, else `publication_date`) on or
+     * before the date; its own fact dates never exclude it (a plan stated in
+     * June about next year is admitted). Nodes stated on both sides of the
+     * date keep only their earlier sources and withhold the merged summary
+     * (`spans_as_of`); undated nodes stay; closed claims stay (annotated
+     * `valid_at_time: false`). Also sets the validity-annotation reference
+     * when `valid_at` is absent. Wiki articles are skipped under a
+     * time-scoped read. The response's `time_filter.axis` is
+     * `statement_time`; use `occurred_from` / `occurred_to` for a fact-time
+     * window. (Server 1.14+: before, `as_of` filtered on fact time.)
+     */
+    as_of?: string;
+    /**
+     * Inclusive occurrence window (ISO-8601, imprecision ok): only nodes and
+     * chunks whose effective interval overlaps it are returned. Undated nodes
+     * are excluded under a window. Either bound may be omitted.
+     */
+    /**
+     * Evidence plan R2 (server 1.14+): `"text"` adds `context_text`,
+     * `used_tokens`, `truncated` and `omitted` — the canonical rendering every
+     * door shares (dated items, supersession and conflict markers, a hard
+     * budget). Default `"json"`.
+     */
+    format?: "json" | "text";
+    /** Token budget for `format: "text"` (minimum 256; default 8000). */
+    max_tokens?: number;
+    /** Order of `graph.nodes` in the JSON: `"rank"` (default) or `"chronological"`. */
+    sort?: "rank" | "chronological";
+    /**
+     * `"exhaustive"` widens retrieval for list/count questions; omitted lets
+     * the server's enumeration cue decide.
+     */
+    retrieval_mode?: "normal" | "exhaustive";
+    occurred_from?: string;
+    occurred_to?: string;
+    /**
+     * Re-admit operational ledger and work-state nodes (sessions, executions,
+     * tasks, plans). Excluded from knowledge retrieval by default.
+     */
+    include_ledger?: boolean;
+    /**
+     * Bound each article's `content` to this many characters by query-aware
+     * excerpting (default 6000; 0 = unlimited). The response flags `excerpted`.
+     */
+    article_char_limit?: number;
+    /** Cosine floor for admitted articles (default 0 = off). */
+    article_min_similarity?: number;
+    /**
+     * Attach per-leg hybrid contributions (`retrieval_legs`) to direct nodes.
+     * Honored only for unscoped callers.
+     */
+    explain?: boolean;
+    /**
+     * Ontology leg control: `mode` `"auto"` (default) or `"off"`, optionally
+     * restricted to one active schema. The leg runs only when the server has it
+     * enabled and the org has an active schema.
+     */
+    ontology?: {
+        mode?: "auto" | "off";
+        schema_id?: string;
+    };
+    /**
+     * What the caller is doing right now (an agent's task, the last turns of a
+     * conversation), at most 2,000 characters. Read only by the question-aware
+     * reranker; never used as a search term and never stored.
+     */
+    intent?: string;
+    /**
+     * Apply the question-aware rerank to graph-expansion candidates. Omitted
+     * uses the server default (off).
+     */
+    rerank?: boolean;
 }
 interface ArticleResult {
     uid: string;
@@ -986,6 +1157,39 @@ interface SeriesContextAnnotation {
     };
 }
 interface RetrieveContextResponse {
+    /**
+     * Present only when the request set `as_of`, `occurred_from` or
+     * `occurred_to`: the echoed filter plus what it excluded. World time only.
+     */
+    time_filter?: {
+        as_of?: string;
+        occurred_from?: string;
+        occurred_to?: string;
+        nodes_excluded: number;
+        chunks_excluded: number;
+        articles_excluded: boolean;
+        /** `statement_time` under `as_of` (server 1.14+), `world_time` under a window. */
+        axis: "world_time" | "statement_time";
+        /** Nodes short of `node_limit` after admission (server 1.14+). */
+        backfill_shortfall?: number;
+    };
+    /** The "now" anchor: `as_of` when given, else the request date (server 1.14+). */
+    now?: string;
+    /** Unresolved contradiction pairs among the returned nodes (server 1.14+). */
+    conflicts?: Array<Record<string, unknown>>;
+    retrieval_mode?: "exhaustive";
+    retrieval_mode_source?: "request" | "cue";
+    /** Present with `format: "text"`. */
+    context_text?: string;
+    used_tokens?: number;
+    truncated?: boolean;
+    omitted?: {
+        nodes: number;
+        chunks: number;
+        articles: number;
+        conflicts: number;
+        injections?: number;
+    };
     articles?: ArticleResult[];
     chunks?: {
         chunk_uid: string;
@@ -1004,6 +1208,10 @@ interface RetrieveContextResponse {
                 ingested_by?: string;
                 /** Display name (else email) of the ingesting teammate. */
                 ingested_by_name?: string;
+                /** When the source conversation or document occurred (ISO-8601). */
+                occurred_at?: string;
+                /** Publication date of the source document (ISO-8601). */
+                publication_date?: string;
             }[];
             source_chunks?: SourceChunk[];
             believed_by?: BelievedBy[];
@@ -1029,10 +1237,17 @@ interface RetrieveContextResponse {
         edges: Record<string, unknown>[];
     };
 }
+/** Safe terminal reason. This does not authorize replaying a whole job. */
+interface JobErrorDetails {
+    code: string;
+    message: string;
+    status: number;
+    retriable: boolean;
+}
 interface Job {
     id: string;
     title: string;
-    status: "pending" | "processing" | "completed" | "failed" | "cancelled";
+    status: "pending" | "processing" | "completed" | "completed_with_errors" | "failed" | "cancelled";
     progress: {
         total_chunks: number;
         processed_chunks: number;
@@ -1041,6 +1256,8 @@ interface Job {
     };
     result: Record<string, unknown> | null;
     error: string | null;
+    /** Absent for older servers or ordinary failures. */
+    error_details?: JobErrorDetails | null;
     created_at: number;
     queue_position?: number;
 }
@@ -1193,10 +1410,18 @@ interface MindGraphConfig {
      * uses this value for authorization or result membership.
      */
     telemetrySurface?: "dashboard" | "mcp";
-    /** Max retries for 503 (server warming up) responses. Default: 3. Set to 0 to disable. */
+    /** Max 503 retries for reviewed reads or keyed work operations. retriable:false stops retries. Default: 3. Set to 0 to disable. */
     maxRetries?: number;
-    /** Initial backoff in ms before first retry. Doubles each attempt. Default: 1000. */
+    /** Initial backoff in ms before first retry. Doubles each attempt, capped at 10 seconds. Default: 1000. */
     retryBackoffMs?: number;
+    /**
+     * Per-request deadline in ms. When set, each HTTP attempt is aborted after
+     * this long and the call rejects with a `MindGraphError` whose `code` is
+     * `"timeout"` (`status` 0, `retriable: false`). Unset (default) keeps the
+     * historical behaviour: no deadline and no AbortSignal on the request.
+     * Fail-open wrappers (agent memory providers) set this to a few seconds.
+     */
+    timeoutMs?: number;
 }
 /** Schema-level behavior for compiled semantic-match diagnostics. */
 type SemanticValidationMode = "off" | "advisory" | "review" | "strict";
@@ -1440,6 +1665,8 @@ interface OntologySchema {
     propose_status?: "pending" | "running" | "ready" | "failed" | null;
     propose_job_id?: string | null;
     propose_error?: string | null;
+    /** Durable terminal reason; absent on older servers. Review partial drafts before retry. */
+    propose_error_details?: OntologyProposeErrorDetails | null;
     created_by?: string | null;
     updated_by?: string | null;
     created_at: string;
@@ -1582,7 +1809,11 @@ interface OntologyProposal {
     approval_uid?: string | null;
     proposed_node_uid?: string | null;
     applied_job_id?: string | null;
+    /** Known result UID, including a partial result that needs reconciliation. */
+    applied_uid?: string | null;
     applied_error?: string | null;
+    /** A terminal execution failure; earlier graph changes may have committed. */
+    applied_error_details?: OntologyApplyErrorDetails | null;
     apply_attempt_count: number;
     edited_by?: string | null;
     edited_at?: string | null;
@@ -1592,6 +1823,14 @@ interface OntologyProposal {
     resolved_at?: string | null;
     resolved_by?: string | null;
 }
+/** Proposal and apply failures share the safe terminal execution metadata. */
+type OntologyProposeErrorDetails = OntologyApplyErrorDetails;
+interface OntologyApplyErrorDetails {
+    code: string;
+    message: string;
+    status: number;
+    retriable: false;
+}
 interface OntologyDuplicateAudit {
     schema_id: string;
     object_groups: Array<{
@@ -1829,6 +2068,8 @@ type DomainObject = GraphNode;
 declare class MindGraphError extends Error {
     status: number;
     body?: unknown | undefined;
+    readonly code?: string;
+    readonly retriable?: boolean;
     constructor(message: string, status: number, body?: unknown | undefined);
 }
 declare class MindGraph {
@@ -1836,9 +2077,17 @@ declare class MindGraph {
     private headers;
     private maxRetries;
     private retryBackoffMs;
+    private timeoutMs?;
     private telemetrySurface?;
     constructor(config: MindGraphConfig);
     private request;
+    /**
+     * One HTTP attempt. With `timeoutMs` set, the attempt is aborted at the
+     * deadline and surfaces as a non-retriable `MindGraphError` (`code:
+     * "timeout"`, `status: 0`). Without it the request is sent unchanged — no
+     * AbortSignal is attached, preserving the pre-0.16 behaviour.
+     */
+    private fetchWithDeadline;
     private get;
     private post;
     private patch;
@@ -1991,6 +2240,35 @@ declare class MindGraph {
     distill(req: DistillRequest): Promise<unknown>;
     memoryConfig(req: MemoryConfigRequest): Promise<unknown>;
     memorySync(req: MemorySyncRequest): Promise<unknown>;
+    /**
+     * Store a small piece of text as a memory, synchronously. The node is
+     * BM25- and vector-searchable when this resolves (`searchable` says which).
+     * Pass `custom_id` to make re-sends an upsert of the same node.
+     */
+    remember(text: string, options?: RememberOptions): Promise<RememberResponse>;
+    /**
+     * Reversibly remove a memory by `uid` or `custom_id` (tombstone plus its
+     * connected edges). `dry_run: true` previews the affected edge uids first.
+     * Undo with `restore(uid)` and `evolve({ action: "restore_edge", uid })`.
+     */
+    forget(target: ForgetTarget, options?: ForgetOptions): Promise<ForgetResponse>;
+    /**
+     * Operator guidance for what agents should remember into a Space; surfaced
+     * on every `remember()` response and on `retrieveContext()`. Empty clears it.
+     */
+    setRememberInstructions(text: string, options?: {
+        space_uid?: string;
+        agent_id?: string;
+    }): Promise<{
+        space_uid: string;
+        remember_instructions: string | null;
+    }>;
+    getRememberInstructions(options?: {
+        space_uid?: string;
+    }): Promise<{
+        space_uid: string;
+        remember_instructions: string | null;
+    }>;
     plan(req: PlanRequest): Promise<unknown>;
     governance(req: GovernanceRequest): Promise<unknown>;
     execution(req: ExecutionRequest): Promise<unknown>;
@@ -2455,4 +2733,4 @@ declare class MindGraph {
     }>;
 }
 
-export { type AggregatePoint, type AnalogyCandidate, type AppendSeriesResponse, type ArgumentRequest, type ArticleResult, type BatchAggregateSeriesResponse, type BatchLatestSeriesResponse, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateDomainObjectRequest, type CreateOntologySchemaRequest, type CreateSeriesResponse, type DecayRequest, type DeleteSeriesResponse, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type DomainObject, type DomainObjectMutationResponse, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type FieldDefinition, type FieldSemantic, type FieldSemanticKind, type FiscalYearEnd, type GovernanceRequest, type GovernanceTarget, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type ListSeriesResponse, type MeasurementPoint, type MemoryConfigRequest, type MemorySyncRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyPredicateOperator, type OntologyProposal, type OntologyQueryPredicate, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OntologySeriesBinding, type OntologyToolDescriptor, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelatedDomainObjectsRequest, type RelationBacking, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SeriesAggregateResponse, type SeriesBacking, type SeriesContextAnnotation, type SeriesLatestResponse, type SeriesNode, type SeriesProps, type SeriesRequest, type SeriesWindowResponse, type SessionRequest, type SignalsQuery, type SignalsResponse, type SkillDistillProps, type SkillDistillRequest, type SourceChunk, type StructureRequest, type StructuredOntologyQueryRequest, type StructuredOntologyQueryResponse, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateDomainObjectRequest, type UpdateOntologySchemaRequest };
+export { type AggregatePoint, type AnalogyCandidate, type AppendSeriesResponse, type ArgumentRequest, type ArticleResult, type BatchAggregateSeriesResponse, type BatchLatestSeriesResponse, type BatchRequest, type BelievedBy, type CanonicalAttachmentAuthority, type CanonicalAttachmentBinding, type CanonicalAttachmentDirection, type CaptureRequest, type ClaimHub, type ClearResponse, type ClusterClaimSample, type ClusteredClaimHub, type CommitmentRequest, type ConceptCluster, type CreateDomainObjectRequest, type CreateOntologySchemaRequest, type CreateSeriesResponse, type DecayRequest, type DeleteSeriesResponse, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, type DomainObject, type DomainObjectMutationResponse, type EnrichedSearchResponse, type EntityBridge, type EntityRequest, type EpistemicCounts, type EventProps, type EvolveRequest, type ExecutionRequest, type FieldDefinition, type FieldSemantic, type FieldSemanticKind, type FiscalYearEnd, type ForgetOptions, type ForgetRequest, type ForgetResponse, type ForgetTarget, type GovernanceRequest, type GovernanceTarget, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type ListArticlesResponse, type ListSeriesResponse, type MeasurementPoint, type MemoryConfigRequest, type MemorySyncRequest, MindGraph, type MindGraphConfig, MindGraphError, type NationProps, type NormativeKind, type ObjectBacking, type OntologicalBaseKind, type OntologyApplyErrorDetails, type OntologyDuplicateAudit, type OntologyObjectType, type OntologyObjectTypeInput, type OntologyPredicateOperator, type OntologyProposal, type OntologyProposeErrorDetails, type OntologyQueryPredicate, type OntologyRelationType, type OntologyRelationTypeInput, type OntologySchema, type OntologySchemaDetail, type OntologySeriesBinding, type OntologyToolDescriptor, type OrganizationProps, type Participant, type ParticipantSlotKind, type PathStep, type PersonProps, type PlaceProps, type PlanRequest, type ProcedureRequest, type ProposalEdits, type PurgeRequest, type RankedClaimHub, type RelatedDomainObjectsRequest, type RelationBacking, type RememberOptions, type RememberRequest, type RememberResponse, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchChunk, type SearchResult, type SemanticDependence, type SemanticEvidenceRef, type SemanticEvidenceSourceKind, type SemanticGeneratorRef, type SemanticIdentityMode, type SemanticMatch, type SemanticMatchAlternative, type SemanticMatchStatus, type SemanticModifier, type SemanticModifierMatch, type SemanticNegativeControl, type SemanticParticipantSlot, type SemanticRelationKind, type SemanticReviewDecision, type SemanticRigidity, type SemanticRuntimeTemplate, type SemanticSignal, type SemanticSignalKind, type SemanticTemplateRef, type SemanticTemporalMode, type SemanticTenantBindings, type SemanticValidationAuthoringMode, type SemanticValidationMode, type SeriesAggregateResponse, type SeriesBacking, type SeriesContextAnnotation, type SeriesLatestResponse, type SeriesNode, type SeriesProps, type SeriesRequest, type SeriesWindowResponse, type SessionRequest, type SignalsQuery, type SignalsResponse, type SkillDistillProps, type SkillDistillRequest, type SourceChunk, type StructureRequest, type StructuredOntologyQueryRequest, type StructuredOntologyQueryResponse, type SynthesisJobResponse, type TextSelector, type TheorySupportGap, type TraverseRequest, type UpdateDomainObjectRequest, type UpdateOntologySchemaRequest };