mindgraph 0.15.0 → 0.16.0

package/README.md

@@ -21,16 +21,23 @@ const graph = new MindGraph({
   apiKey: "mg_...",
 });
 
-// Add a node
-const node = await graph.addNode({
-  label: "User prefers dark mode",
-  node_type: "Preference",
+// Remember something — searchable the moment this resolves
+const memory = await graph.remember("User prefers dark mode in every editor", {
+  custom_id: "pref:theme", // re-sending this key updates the same memory
 });
 
-// Search
+// Search (BM25 + vector)
 const results = await graph.search("what does the user prefer?");
 
-// Connect knowledge
+// Forget it later — preview first, then tombstone (reversible)
+await graph.forget({ custom_id: "pref:theme" }, { dry_run: true });
+await graph.forget({ custom_id: "pref:theme" });
+
+// Or build structure explicitly
+const node = await graph.addNode({
+  label: "User prefers dark mode",
+  node_type: "Preference",
+});
 await graph.addLink({
   from_uid: node.uid,
   to_uid: "user_abc",
@@ -43,7 +50,7 @@ await graph.addLink({
 ### Constructor
 
 ```typescript
-new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
+new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string, timeoutMs?: number })
 ```
 
 ### Reality Layer
@@ -107,6 +114,9 @@ const entity = await graph.findOrCreateEntity("Some Entity");
 |--------|-------------|
 | `session(req)` | Open a session, record traces, or close a session |
 | `journal(label, props, options?)` | Record a journal entry linked to an optional session |
+| `remember(text, options?)` | Small-text fast path: synchronous write, BM25- and vector-searchable on return; `custom_id` makes re-sends an upsert |
+| `forget(target, options?)` | Reversible removal by `{ uid }` or `{ custom_id }`; `dry_run` previews the affected edge uids |
+| `setRememberInstructions(text, options?)` / `getRememberInstructions()` | Per-Space guidance for what agents should remember; surfaced on `remember()` and `retrieveContext()` |
 | `distill(req)` | Create a Summary, Lesson, or governed Skill candidate with source provenance |
 | `memoryConfig(req)` | Set/get preferences and memory policies |
 
@@ -257,3 +267,21 @@ try {
 ## License
 
 MIT
+
+### Retry and engine-error contract
+
+HTTP 503 retries are bounded and apply only to reviewed reads (including selected
+POST query actions) and keyed `/agent/plan` work operations: `claim_task`,
+`heartbeat`, `start_iteration`, `checkpoint_iteration`, `block_task`,
+`complete_task`, and `abandon_iteration`. These work operations atomically store
+their mutation and idempotency receipt. A nonempty `idempotency_key` must stay
+unchanged across attempts. Other writes are not retried automatically; supplying
+a key or telemetry request ID on an unsupported route does not change that.
+
+`MindGraphError` preserves the response `status` and `body` and exposes optional
+`code` and `retriable` fields. Explicit `retriable: false` always stops retries,
+including admission failures and index maintenance. Memory limits, timeouts,
+and cancellation remain failures; they do not become empty search results.
+Older responses without retry guidance retain retries only for the reviewed
+operations above. Each delay, including fallback backoff, is capped at 10 seconds.
+Network exceptions and other HTTP statuses are not automatically retried.

package/dist/index.d.mts

@@ -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";
@@ -1193,10 +1282,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";
@@ -1627,7 +1724,7 @@ interface ProposalEdits {
 }
 interface ProposeOntologySchemaRequest {
     description?: string;
-    template_hint?: "client_services" | "healthcare" | "supply_chain" | "research_intel" | "custom";
+    template_hint?: "client_services" | "healthcare" | "supply_chain" | "research_intel" | "product_intelligence" | "investment_dealflow" | "custom";
     source_uids?: string[];
     source_documents?: Array<{
         content: string;
@@ -1681,8 +1778,14 @@ interface StructuredOntologyQueryRequest {
         offset?: number;
     };
     aggregate?: {
-        op: "count" | "customer_demand_rank";
+        op: "count" | "customer_demand_rank" | "weighted_scorecard";
         group_by?: string;
+        criteria?: Array<{
+            field: string;
+            weight: number;
+            direction: "higher_is_better" | "lower_is_better";
+        }>;
+        missing?: "exclude_candidate" | "zero";
     };
 }
 interface StructuredOntologyQueryResponse {
@@ -1791,9 +1894,28 @@ interface CreateDomainObjectRequest {
     aliases?: string[];
     identity?: Record<string, unknown>;
     confidence?: number;
-    /** Skip the same-type + same-name duplicate guard (default false). */
+    /** Skip the same-type + same-name guard. Schema identity is still enforced. */
     allow_duplicate?: boolean;
 }
+interface UpdateDomainObjectRequest {
+    canonical_name?: string;
+    /** Field patch. Use `unset_fields` rather than null to remove a field. */
+    fields?: Record<string, unknown>;
+    unset_fields?: string[];
+    /** Additive aliases; existing aliases and source provenance are preserved. */
+    aliases?: string[];
+    confidence?: number;
+    /** Optimistic-concurrency guard from the current object's `version`. */
+    expected_version: number;
+    /** Human-readable reason retained in the ontology proposal audit ledger. */
+    reason: string;
+}
+interface DomainObjectMutationResponse {
+    uid: string;
+    proposal_id: string;
+    /** Present on update responses. */
+    version?: number;
+}
 interface ExtractOntologyRequest {
     ontology_schema_id: string;
     source_uids: string[];
@@ -1804,6 +1926,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 {
@@ -1811,9 +1935,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;
@@ -1966,6 +2098,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>;
@@ -2413,12 +2574,15 @@ declare class MindGraph {
     /**
      * Create a domain object by hand (auto-approved). Returns the created node
      * uid + the audit proposal id. Throws 409 if an object of the same type +
-     * canonical_name already exists, unless `allow_duplicate` is set.
+     * canonical_name already exists, unless `allow_duplicate` is set. The
+     * schema's identity key is always enforced.
      */
-    createDomainObject(req: CreateDomainObjectRequest): Promise<{
-        uid: string;
-        proposal_id: string;
-    }>;
+    createDomainObject(req: CreateDomainObjectRequest): Promise<DomainObjectMutationResponse>;
+    /**
+     * Schema-validated authored update with optimistic concurrency. Identity
+     * fields are immutable; create and explicitly merge when identity changes.
+     */
+    updateDomainObject(uid: string, req: UpdateDomainObjectRequest): Promise<DomainObjectMutationResponse>;
     linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
         edge_uid: string;
     }>;
@@ -2427,4 +2591,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 CreateOntologySchemaRequest, type CreateSeriesResponse, type DecayRequest, type DeleteSeriesResponse, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, 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 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 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 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 };

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";
@@ -1193,10 +1282,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";
@@ -1627,7 +1724,7 @@ interface ProposalEdits {
 }
 interface ProposeOntologySchemaRequest {
     description?: string;
-    template_hint?: "client_services" | "healthcare" | "supply_chain" | "research_intel" | "custom";
+    template_hint?: "client_services" | "healthcare" | "supply_chain" | "research_intel" | "product_intelligence" | "investment_dealflow" | "custom";
     source_uids?: string[];
     source_documents?: Array<{
         content: string;
@@ -1681,8 +1778,14 @@ interface StructuredOntologyQueryRequest {
         offset?: number;
     };
     aggregate?: {
-        op: "count" | "customer_demand_rank";
+        op: "count" | "customer_demand_rank" | "weighted_scorecard";
         group_by?: string;
+        criteria?: Array<{
+            field: string;
+            weight: number;
+            direction: "higher_is_better" | "lower_is_better";
+        }>;
+        missing?: "exclude_candidate" | "zero";
     };
 }
 interface StructuredOntologyQueryResponse {
@@ -1791,9 +1894,28 @@ interface CreateDomainObjectRequest {
     aliases?: string[];
     identity?: Record<string, unknown>;
     confidence?: number;
-    /** Skip the same-type + same-name duplicate guard (default false). */
+    /** Skip the same-type + same-name guard. Schema identity is still enforced. */
     allow_duplicate?: boolean;
 }
+interface UpdateDomainObjectRequest {
+    canonical_name?: string;
+    /** Field patch. Use `unset_fields` rather than null to remove a field. */
+    fields?: Record<string, unknown>;
+    unset_fields?: string[];
+    /** Additive aliases; existing aliases and source provenance are preserved. */
+    aliases?: string[];
+    confidence?: number;
+    /** Optimistic-concurrency guard from the current object's `version`. */
+    expected_version: number;
+    /** Human-readable reason retained in the ontology proposal audit ledger. */
+    reason: string;
+}
+interface DomainObjectMutationResponse {
+    uid: string;
+    proposal_id: string;
+    /** Present on update responses. */
+    version?: number;
+}
 interface ExtractOntologyRequest {
     ontology_schema_id: string;
     source_uids: string[];
@@ -1804,6 +1926,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 {
@@ -1811,9 +1935,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;
@@ -1966,6 +2098,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>;
@@ -2413,12 +2574,15 @@ declare class MindGraph {
     /**
      * Create a domain object by hand (auto-approved). Returns the created node
      * uid + the audit proposal id. Throws 409 if an object of the same type +
-     * canonical_name already exists, unless `allow_duplicate` is set.
+     * canonical_name already exists, unless `allow_duplicate` is set. The
+     * schema's identity key is always enforced.
      */
-    createDomainObject(req: CreateDomainObjectRequest): Promise<{
-        uid: string;
-        proposal_id: string;
-    }>;
+    createDomainObject(req: CreateDomainObjectRequest): Promise<DomainObjectMutationResponse>;
+    /**
+     * Schema-validated authored update with optimistic concurrency. Identity
+     * fields are immutable; create and explicitly merge when identity changes.
+     */
+    updateDomainObject(uid: string, req: UpdateDomainObjectRequest): Promise<DomainObjectMutationResponse>;
     linkDomainObjects(req: LinkDomainObjectsRequest): Promise<{
         edge_uid: string;
     }>;
@@ -2427,4 +2591,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 CreateOntologySchemaRequest, type CreateSeriesResponse, type DecayRequest, type DeleteSeriesResponse, type DeliberationRequest, type DialecticalPair, type DistillRequest, type DocumentRef, 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 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 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 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 };

package/dist/index.js

@@ -25,16 +25,120 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/retry.ts
+var READ_POSTS = /* @__PURE__ */ new Set([
+  "/search",
+  "/retrieve/context",
+  "/nodes/batch",
+  "/edges/batch",
+  "/subgraph",
+  "/embeddings/search",
+  "/embeddings/search-text",
+  "/ontology/query",
+  "/ontology/query/structured",
+  "/ontology/objects/search"
+]);
+var READ_ACTIONS = {
+  "/retrieve": [
+    "text",
+    "semantic",
+    "hybrid",
+    "active_goals",
+    "open_questions",
+    "preferences",
+    "weak_claims",
+    "pending_approvals",
+    "unresolved_contradictions",
+    "merge_candidates",
+    "stale_derivations",
+    "curation_counts",
+    "layer",
+    "recent"
+  ],
+  "/traverse": ["chain", "top_k_paths", "neighborhood", "path", "subgraph"],
+  "/reality/series": ["window", "aggregate", "latest", "list_for_entity", "batch_latest", "batch_aggregate"],
+  "/intent/deliberation": ["get_open"],
+  "/action/risk": ["get_assessments"],
+  "/action/skill": ["get", "list"],
+  "/memory/config": ["get_preferences", "get_policies"],
+  "/memory/sync": ["status"],
+  "/agent/plan": ["get_plan", "resume_work"],
+  "/agent/governance": ["get_pending", "check"],
+  "/agent/execution": ["get_executions"],
+  "/evolve": ["history", "snapshot"]
+};
+var IDEMPOTENT_WORK = /* @__PURE__ */ new Set([
+  "claim_task",
+  "heartbeat",
+  "start_iteration",
+  "checkpoint_iteration",
+  "block_task",
+  "complete_task",
+  "abandon_iteration"
+]);
+function errorFields(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const fields = body;
+  return {
+    ...typeof fields.code === "string" ? { code: fields.code } : {},
+    ...typeof fields.retriable === "boolean" ? { retriable: fields.retriable } : {}
+  };
+}
+function canRetryRequest(method, path, body) {
+  if (method === "GET" || method === "HEAD") return true;
+  if (method !== "POST") return false;
+  if (READ_POSTS.has(path)) return true;
+  const fields = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+  if (typeof fields.action !== "string") return false;
+  if (Object.prototype.hasOwnProperty.call(READ_ACTIONS, path) && READ_ACTIONS[path].includes(fields.action)) return true;
+  return path === "/agent/plan" && IDEMPOTENT_WORK.has(fields.action) && typeof fields.idempotency_key === "string" && fields.idempotency_key.trim().length > 0;
+}
+function permitsRetry(fields) {
+  return fields.retriable !== false && ![
+    "query_memory_budget_exceeded",
+    "query_timeout",
+    "query_cancelled",
+    "vector_index_rebuilding"
+  ].includes(fields.code ?? "");
+}
+function retryDelayMs(header, backoff, attempt) {
+  const hint = Number(header);
+  return Number.isFinite(hint) && hint > 0 ? Math.min(hint * 1e3, 1e4) : Math.min(backoff * 2 ** Math.min(attempt, 32), 1e4);
+}
+
 // src/client.ts
 function seg(value) {
   return encodeURIComponent(String(value));
 }
+function pathSteps(response) {
+  const wrapped = response && typeof response === "object" && !Array.isArray(response) ? response : void 0;
+  const raw = wrapped?.steps ?? response;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+    const step = value;
+    const taggedName = (tagged) => {
+      if (typeof tagged === "string") return tagged;
+      if (!tagged || typeof tagged !== "object" || Array.isArray(tagged)) return null;
+      const custom = tagged.Custom;
+      return typeof custom === "string" ? custom : null;
+    };
+    return [{
+      ...step,
+      node_type: taggedName(step.node_type) ?? "Unknown",
+      edge_type: taggedName(step.edge_type)
+    }];
+  });
+}
 var MindGraphError = class extends Error {
   constructor(message, status, body) {
     super(message);
     this.status = status;
     this.body = body;
     this.name = "MindGraphError";
+    const fields = errorFields(body);
+    this.code = fields.code;
+    this.retriable = fields.retriable;
   }
 };
 var MindGraph = class {
@@ -52,6 +156,18 @@ var MindGraph = class {
     this.telemetrySurface = config.telemetrySurface;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
+    if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+      throw new RangeError("maxRetries must be a non-negative safe integer");
+    }
+    if (!Number.isFinite(this.retryBackoffMs) || this.retryBackoffMs < 0) {
+      throw new RangeError("retryBackoffMs must be finite and non-negative");
+    }
+    if (config.timeoutMs !== void 0) {
+      if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {
+        throw new RangeError("timeoutMs must be a positive finite number of milliseconds");
+      }
+      this.timeoutMs = config.timeoutMs;
+    }
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
@@ -68,9 +184,14 @@ var MindGraph = class {
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
+    const retrySafe = canRetryRequest(
+      method,
+      path,
+      typeof init.body === "string" ? JSON.parse(init.body) : void 0
+    );
     let lastError;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      const res = await fetch(url, init);
+      const res = await this.fetchWithDeadline(url, init, method, path);
       if (!res.ok) {
         const text2 = await res.text().catch(() => "");
         let parsed;
@@ -84,10 +205,9 @@ var MindGraph = class {
           res.status,
           parsed
         );
-        if (res.status === 503 && attempt < this.maxRetries) {
+        if (res.status === 503 && retrySafe && permitsRetry(err) && attempt < this.maxRetries) {
           lastError = err;
-          const retryAfterSecs = Number(res.headers.get("retry-after"));
-          const delay = Number.isFinite(retryAfterSecs) && retryAfterSecs > 0 ? Math.min(retryAfterSecs * 1e3, 1e4) : this.retryBackoffMs * 2 ** attempt;
+          const delay = retryDelayMs(res.headers.get("retry-after"), this.retryBackoffMs, attempt);
           await new Promise((r) => setTimeout(r, delay));
           continue;
         }
@@ -99,6 +219,33 @@ var MindGraph = class {
     }
     throw lastError;
   }
+  /**
+   * 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.
+   */
+  async fetchWithDeadline(url, init, method, path) {
+    if (this.timeoutMs === void 0) {
+      return fetch(url, init);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new MindGraphError(
+          `${method} ${path} timed out after ${this.timeoutMs}ms`,
+          0,
+          { error: "timeout", code: "timeout", retriable: false }
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   get(path) {
     return this.request("GET", path);
   }
@@ -348,6 +495,40 @@ var MindGraph = class {
   async memorySync(req) {
     return this.post("/memory/sync", req);
   }
+  // ---- Memory (fast path) ----
+  /**
+   * 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.
+   */
+  async remember(text, options = {}) {
+    return this.post("/memory/remember", { text, ...options });
+  }
+  /**
+   * 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 })`.
+   */
+  async forget(target, options = {}) {
+    return this.post("/memory/forget", { ...target, ...options });
+  }
+  /**
+   * Operator guidance for what agents should remember into a Space; surfaced
+   * on every `remember()` response and on `retrieveContext()`. Empty clears it.
+   */
+  async setRememberInstructions(text, options = {}) {
+    return this.post("/memory/config", {
+      action: "set_remember_instructions",
+      text,
+      ...options
+    });
+  }
+  async getRememberInstructions(options = {}) {
+    return this.post("/memory/config", {
+      action: "get_remember_instructions",
+      ...options
+    });
+  }
   // ---- Agent Layer ----
   async plan(req) {
     return this.post("/agent/plan", req);
@@ -570,7 +751,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async neighborhood(uid, maxDepth = 1) {
     const r = await this.post("/traverse", {
@@ -578,7 +759,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async subgraph(uid, opts) {
     return this.post("/subgraph", { start_uids: [uid], ...opts });
@@ -949,11 +1130,19 @@ var MindGraph = class {
   /**
    * Create a domain object by hand (auto-approved). Returns the created node
    * uid + the audit proposal id. Throws 409 if an object of the same type +
-   * canonical_name already exists, unless `allow_duplicate` is set.
+   * canonical_name already exists, unless `allow_duplicate` is set. The
+   * schema's identity key is always enforced.
    */
   async createDomainObject(req) {
     return this.post("/v1/ontology/objects", req);
   }
+  /**
+   * Schema-validated authored update with optimistic concurrency. Identity
+   * fields are immutable; create and explicitly merge when identity changes.
+   */
+  async updateDomainObject(uid, req) {
+    return this.patch(`/v1/ontology/objects/${seg(uid)}`, req);
+  }
   async linkDomainObjects(req) {
     return this.post("/ontology/relation", { action: "create", ...req });
   }

package/dist/index.mjs

@@ -1,13 +1,117 @@
+// src/retry.ts
+var READ_POSTS = /* @__PURE__ */ new Set([
+  "/search",
+  "/retrieve/context",
+  "/nodes/batch",
+  "/edges/batch",
+  "/subgraph",
+  "/embeddings/search",
+  "/embeddings/search-text",
+  "/ontology/query",
+  "/ontology/query/structured",
+  "/ontology/objects/search"
+]);
+var READ_ACTIONS = {
+  "/retrieve": [
+    "text",
+    "semantic",
+    "hybrid",
+    "active_goals",
+    "open_questions",
+    "preferences",
+    "weak_claims",
+    "pending_approvals",
+    "unresolved_contradictions",
+    "merge_candidates",
+    "stale_derivations",
+    "curation_counts",
+    "layer",
+    "recent"
+  ],
+  "/traverse": ["chain", "top_k_paths", "neighborhood", "path", "subgraph"],
+  "/reality/series": ["window", "aggregate", "latest", "list_for_entity", "batch_latest", "batch_aggregate"],
+  "/intent/deliberation": ["get_open"],
+  "/action/risk": ["get_assessments"],
+  "/action/skill": ["get", "list"],
+  "/memory/config": ["get_preferences", "get_policies"],
+  "/memory/sync": ["status"],
+  "/agent/plan": ["get_plan", "resume_work"],
+  "/agent/governance": ["get_pending", "check"],
+  "/agent/execution": ["get_executions"],
+  "/evolve": ["history", "snapshot"]
+};
+var IDEMPOTENT_WORK = /* @__PURE__ */ new Set([
+  "claim_task",
+  "heartbeat",
+  "start_iteration",
+  "checkpoint_iteration",
+  "block_task",
+  "complete_task",
+  "abandon_iteration"
+]);
+function errorFields(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const fields = body;
+  return {
+    ...typeof fields.code === "string" ? { code: fields.code } : {},
+    ...typeof fields.retriable === "boolean" ? { retriable: fields.retriable } : {}
+  };
+}
+function canRetryRequest(method, path, body) {
+  if (method === "GET" || method === "HEAD") return true;
+  if (method !== "POST") return false;
+  if (READ_POSTS.has(path)) return true;
+  const fields = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+  if (typeof fields.action !== "string") return false;
+  if (Object.prototype.hasOwnProperty.call(READ_ACTIONS, path) && READ_ACTIONS[path].includes(fields.action)) return true;
+  return path === "/agent/plan" && IDEMPOTENT_WORK.has(fields.action) && typeof fields.idempotency_key === "string" && fields.idempotency_key.trim().length > 0;
+}
+function permitsRetry(fields) {
+  return fields.retriable !== false && ![
+    "query_memory_budget_exceeded",
+    "query_timeout",
+    "query_cancelled",
+    "vector_index_rebuilding"
+  ].includes(fields.code ?? "");
+}
+function retryDelayMs(header, backoff, attempt) {
+  const hint = Number(header);
+  return Number.isFinite(hint) && hint > 0 ? Math.min(hint * 1e3, 1e4) : Math.min(backoff * 2 ** Math.min(attempt, 32), 1e4);
+}
+
 // src/client.ts
 function seg(value) {
   return encodeURIComponent(String(value));
 }
+function pathSteps(response) {
+  const wrapped = response && typeof response === "object" && !Array.isArray(response) ? response : void 0;
+  const raw = wrapped?.steps ?? response;
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+    const step = value;
+    const taggedName = (tagged) => {
+      if (typeof tagged === "string") return tagged;
+      if (!tagged || typeof tagged !== "object" || Array.isArray(tagged)) return null;
+      const custom = tagged.Custom;
+      return typeof custom === "string" ? custom : null;
+    };
+    return [{
+      ...step,
+      node_type: taggedName(step.node_type) ?? "Unknown",
+      edge_type: taggedName(step.edge_type)
+    }];
+  });
+}
 var MindGraphError = class extends Error {
   constructor(message, status, body) {
     super(message);
     this.status = status;
     this.body = body;
     this.name = "MindGraphError";
+    const fields = errorFields(body);
+    this.code = fields.code;
+    this.retriable = fields.retriable;
   }
 };
 var MindGraph = class {
@@ -25,6 +129,18 @@ var MindGraph = class {
     this.telemetrySurface = config.telemetrySurface;
     this.maxRetries = config.maxRetries ?? 3;
     this.retryBackoffMs = config.retryBackoffMs ?? 1e3;
+    if (!Number.isSafeInteger(this.maxRetries) || this.maxRetries < 0) {
+      throw new RangeError("maxRetries must be a non-negative safe integer");
+    }
+    if (!Number.isFinite(this.retryBackoffMs) || this.retryBackoffMs < 0) {
+      throw new RangeError("retryBackoffMs must be finite and non-negative");
+    }
+    if (config.timeoutMs !== void 0) {
+      if (!Number.isFinite(config.timeoutMs) || config.timeoutMs <= 0) {
+        throw new RangeError("timeoutMs must be a positive finite number of milliseconds");
+      }
+      this.timeoutMs = config.timeoutMs;
+    }
   }
   // ---- HTTP helpers ----
   async request(method, path, body) {
@@ -41,9 +157,14 @@ var MindGraph = class {
     if (body !== void 0) {
       init.body = JSON.stringify(body);
     }
+    const retrySafe = canRetryRequest(
+      method,
+      path,
+      typeof init.body === "string" ? JSON.parse(init.body) : void 0
+    );
     let lastError;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      const res = await fetch(url, init);
+      const res = await this.fetchWithDeadline(url, init, method, path);
       if (!res.ok) {
         const text2 = await res.text().catch(() => "");
         let parsed;
@@ -57,10 +178,9 @@ var MindGraph = class {
           res.status,
           parsed
         );
-        if (res.status === 503 && attempt < this.maxRetries) {
+        if (res.status === 503 && retrySafe && permitsRetry(err) && attempt < this.maxRetries) {
           lastError = err;
-          const retryAfterSecs = Number(res.headers.get("retry-after"));
-          const delay = Number.isFinite(retryAfterSecs) && retryAfterSecs > 0 ? Math.min(retryAfterSecs * 1e3, 1e4) : this.retryBackoffMs * 2 ** attempt;
+          const delay = retryDelayMs(res.headers.get("retry-after"), this.retryBackoffMs, attempt);
           await new Promise((r) => setTimeout(r, delay));
           continue;
         }
@@ -72,6 +192,33 @@ var MindGraph = class {
     }
     throw lastError;
   }
+  /**
+   * 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.
+   */
+  async fetchWithDeadline(url, init, method, path) {
+    if (this.timeoutMs === void 0) {
+      return fetch(url, init);
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw new MindGraphError(
+          `${method} ${path} timed out after ${this.timeoutMs}ms`,
+          0,
+          { error: "timeout", code: "timeout", retriable: false }
+        );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   get(path) {
     return this.request("GET", path);
   }
@@ -321,6 +468,40 @@ var MindGraph = class {
   async memorySync(req) {
     return this.post("/memory/sync", req);
   }
+  // ---- Memory (fast path) ----
+  /**
+   * 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.
+   */
+  async remember(text, options = {}) {
+    return this.post("/memory/remember", { text, ...options });
+  }
+  /**
+   * 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 })`.
+   */
+  async forget(target, options = {}) {
+    return this.post("/memory/forget", { ...target, ...options });
+  }
+  /**
+   * Operator guidance for what agents should remember into a Space; surfaced
+   * on every `remember()` response and on `retrieveContext()`. Empty clears it.
+   */
+  async setRememberInstructions(text, options = {}) {
+    return this.post("/memory/config", {
+      action: "set_remember_instructions",
+      text,
+      ...options
+    });
+  }
+  async getRememberInstructions(options = {}) {
+    return this.post("/memory/config", {
+      action: "get_remember_instructions",
+      ...options
+    });
+  }
   // ---- Agent Layer ----
   async plan(req) {
     return this.post("/agent/plan", req);
@@ -543,7 +724,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async neighborhood(uid, maxDepth = 1) {
     const r = await this.post("/traverse", {
@@ -551,7 +732,7 @@ var MindGraph = class {
       start_uid: uid,
       max_depth: maxDepth
     });
-    return r?.steps ?? r;
+    return pathSteps(r);
   }
   async subgraph(uid, opts) {
     return this.post("/subgraph", { start_uids: [uid], ...opts });
@@ -922,11 +1103,19 @@ var MindGraph = class {
   /**
    * Create a domain object by hand (auto-approved). Returns the created node
    * uid + the audit proposal id. Throws 409 if an object of the same type +
-   * canonical_name already exists, unless `allow_duplicate` is set.
+   * canonical_name already exists, unless `allow_duplicate` is set. The
+   * schema's identity key is always enforced.
    */
   async createDomainObject(req) {
     return this.post("/v1/ontology/objects", req);
   }
+  /**
+   * Schema-validated authored update with optimistic concurrency. Identity
+   * fields are immutable; create and explicitly merge when identity changes.
+   */
+  async updateDomainObject(uid, req) {
+    return this.patch(`/v1/ontology/objects/${seg(uid)}`, req);
+  }
   async linkDomainObjects(req) {
     return this.post("/ontology/relation", { action: "create", ...req });
   }

package/package.json

@@ -1,20 +1,33 @@
 {
   "name": "mindgraph",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "TypeScript client for the MindGraph Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
+    "prepare": "npm run build",
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "lint": "tsc --noEmit",
     "test": "vitest run",
     "test:offline": "vitest run src/offline.test.ts",
     "test:e2e": "vitest run src/integration.test.ts"
   },
-  "keywords": ["mindgraph", "knowledge-graph", "cognitive", "ai", "agent"],
+  "keywords": [
+    "mindgraph",
+    "knowledge-graph",
+    "cognitive",
+    "ai",
+    "agent"
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shuruheel/mindgraph-ts.git"
+  },
   "devDependencies": {
     "@types/node": "^25.4.0",
     "tsup": "^8.0.0",