mindgraph 0.1.2 → 0.1.7

package/README.md

@@ -50,7 +50,7 @@ new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
 
 | Method | Description |
 |--------|-------------|
-| `ingest(req)` | Ingest a source, snippet, or observation |
+| `capture(req)` | Capture a source, snippet, or observation |
 | `entity(req)` | Create, alias, resolve, or merge entities |
 | `findOrCreateEntity(label, entityType?, agentId?)` | Convenience: create or find an entity by label |
 
@@ -81,6 +81,7 @@ new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
 | Method | Description |
 |--------|-------------|
 | `session(req)` | Open a session, record traces, or close a session |
+| `journal(label, props, options?)` | Record a journal entry linked to an optional session |
 | `distill(req)` | Create a summary that distills multiple source nodes |
 | `memoryConfig(req)` | Set/get preferences and memory policies |
 
@@ -117,6 +118,24 @@ new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
 | `reasoningChain(uid, maxDepth?)` | Follow epistemic edges from a node |
 | `neighborhood(uid, maxDepth?)` | Get all nodes within N hops |
 
+### Ingestion & Retrieval
+
+| Method | Description |
+|--------|-------------|
+| `ingestChunk(req)` | Ingest a single text chunk (sync): stores, embeds, and runs LLM extraction |
+| `ingestDocument(req)` | Ingest a full document (async): chunks text, returns job ID |
+| `ingestSession(req)` | Ingest a session transcript (async): links to session, returns job ID |
+| `retrieveContext(req)` | Retrieve semantically matched chunks + connected graph nodes/edges |
+| `getJob(id)` | Get async job status and progress |
+| `clearGraph()` | Clear all graph data |
+
+### Lifecycle Shortcuts
+
+| Method | Description |
+|--------|-------------|
+| `tombstone(uid, reason?, agentId?)` | Soft-delete a node |
+| `restore(uid, agentId?)` | Restore a tombstoned node |
+
 ### Cross-cutting
 
 | Method | Description |
@@ -132,6 +151,21 @@ new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string })
 | `health()` | Health check |
 | `stats()` | Graph-wide statistics |
 
+### Management (Cloud only)
+
+| Method | Description |
+|--------|-------------|
+| `signup(email, password)` | Create a new account |
+| `login(email, password)` | Login and receive JWT |
+| `createApiKey(name?)` | Create an API key |
+| `listApiKeys()` | List all API keys |
+| `revokeApiKey(id)` | Revoke an API key |
+| `getUsage()` | Get usage statistics |
+
+## Examples
+
+See [`examples/`](examples/) for runnable demos, including a [research continuity](examples/research-continuity.ts) scenario showing cross-session memory retrieval.
+
 ## Error Handling
 
 All methods throw `MindGraphError` on HTTP errors:

package/dist/index.d.mts

@@ -38,7 +38,7 @@ interface PathStep {
     depth: number;
     parent_uid: string | null;
 }
-interface IngestRequest {
+interface CaptureRequest {
     action: "source" | "snippet" | "observation";
     label: string;
     summary?: string;
@@ -250,6 +250,10 @@ interface ExecutionRequest {
     agent_id?: string;
 }
 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" | "layer" | "recent";
     query?: string;
     k?: number;
@@ -286,26 +290,114 @@ interface EvolveRequest {
     version?: number;
     agent_id?: string;
 }
-interface SignupRequest {
-    email: string;
-    password: string;
+interface IngestChunkRequest {
+    content: string;
+    chunk_type?: string;
+    document_uid?: string;
+    chunk_index?: number;
+    label?: string;
+    layers?: string[];
+    agent_id?: string;
+}
+interface IngestChunkResponse {
+    chunk_uid: string;
+    nodes_created: number;
+    nodes_deduplicated: number;
+    edges_created: number;
+    extracted_node_uids: string[];
+    errors: string[];
+}
+interface IngestDocumentRequest {
+    content: string;
+    title?: string;
+    document_type?: string;
+    /** Semantic content type: "article" (default), "meeting_notes", "journal". Drives default extraction layers. */
+    content_type?: string;
+    source_uri?: string;
+    chunk_size?: number;
+    chunk_overlap?: number;
+    layers?: string[];
+    agent_id?: string;
 }
-interface LoginRequest {
-    email: string;
-    password: string;
+interface IngestDocumentResponse {
+    job_id: string;
+    document_uid: string;
 }
-interface CreateOrgRequest {
-    name: string;
-    slug?: string;
+interface IngestSessionRequest {
+    content: string;
+    title?: string;
+    session_uid?: string;
+    chunk_size?: number;
+    chunk_overlap?: number;
+    layers?: string[];
+    agent_id?: string;
+}
+interface RetrieveContextRequest {
+    query: string;
+    k?: number;
+    depth?: number;
+    node_types?: string[];
+    layer?: string;
+    include_chunks?: boolean;
+    include_graph?: boolean;
+    min_similarity?: number;
 }
-interface CreateApiKeyRequest {
-    name?: string;
+interface RetrieveContextResponse {
+    chunks: {
+        chunk_uid: string;
+        content: string;
+        score: number;
+        document_uid: string | null;
+        chunk_index: number | null;
+    }[];
+    graph: {
+        nodes: Record<string, unknown>[];
+        edges: Record<string, unknown>[];
+    };
 }
-interface ApiKeyResponse {
+interface Job {
     id: string;
-    key: string;
-    name: string;
-    prefix: string;
+    title: string;
+    status: "pending" | "processing" | "completed" | "failed" | "cancelled";
+    progress: {
+        total_chunks: number;
+        processed_chunks: number;
+        nodes_created: number;
+        edges_created: number;
+    };
+    result: Record<string, unknown> | null;
+    error: string | null;
+    created_at: number;
+    queue_position?: number;
+}
+interface ClearResponse {
+    cleared: boolean;
+    nodes_removed: number;
+    edges_removed: number;
+    versions_removed: number;
+    aliases_removed: number;
+    embeddings_removed: number;
+}
+interface BatchRequest {
+    nodes?: {
+        label: string;
+        node_type?: string;
+        props?: Record<string, unknown>;
+    }[];
+    edges?: {
+        from_uid: string;
+        to_uid: string;
+        edge_type: string;
+    }[];
+    agent_id?: string;
+}
+interface DecayRequest {
+    half_life_secs: number;
+    min_salience?: number;
+    min_age_secs?: number;
+}
+interface PurgeRequest {
+    before?: number;
 }
 interface MindGraphConfig {
     baseUrl: string;
@@ -331,17 +423,55 @@ declare class MindGraph {
         status: string;
     }>;
     stats(): Promise<Record<string, unknown>>;
-    ingest(req: IngestRequest): Promise<unknown>;
+    capture(req: CaptureRequest): Promise<unknown>;
     entity(req: EntityRequest): Promise<unknown>;
     /** Convenience: create or find an entity by label. */
     findOrCreateEntity(label: string, props?: Record<string, unknown>, agentId?: string): Promise<GraphNode & {
         created: boolean;
     }>;
+    /**
+     * Resolve text to an existing entity via alias matching.
+     * Returns `{ uid: string | null }`.
+     */
+    resolveEntity(text: string, agentId?: string): Promise<{
+        uid: string | null;
+    }>;
+    /**
+     * Fuzzy-match text against existing entities.
+     * Returns `{ matches: [{ uid, label, score }] }`.
+     */
+    fuzzyResolveEntity(text: string, limit?: number, agentId?: string): Promise<{
+        matches: {
+            uid: string;
+            label: string;
+            score: number;
+        }[];
+    }>;
     argue(req: ArgumentRequest): Promise<unknown>;
     inquire(req: InquiryRequest): Promise<unknown>;
     structure(req: StructureRequest): Promise<unknown>;
     commit(req: CommitmentRequest): Promise<unknown>;
     deliberate(req: DeliberationRequest): Promise<unknown>;
+    /** Open a new decision for deliberation. Returns the Decision node. */
+    openDecision(label: string, opts?: {
+        summary?: string;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    /** Add an option to an open decision. Returns the Option node. */
+    addOption(decisionUid: string, label: string, opts?: {
+        summary?: string;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    /**
+     * Resolve a decision by choosing an option.
+     * `chosenOptionUid` must be the uid of an option added via `addOption()`.
+     */
+    resolveDecision(decisionUid: string, chosenOptionUid: string, opts?: {
+        summary?: string;
+        agent_id?: string;
+    }): Promise<unknown>;
     procedure(req: ProcedureRequest): Promise<unknown>;
     risk(req: RiskRequest): Promise<unknown>;
     session(req: SessionRequest): Promise<unknown>;
@@ -358,10 +488,18 @@ declare class MindGraph {
     plan(req: PlanRequest): Promise<unknown>;
     governance(req: GovernanceRequest): Promise<unknown>;
     execution(req: ExecutionRequest): Promise<unknown>;
-    retrieve(req: RetrieveRequest): Promise<unknown>;
+    /** Returns an array of results. Shape varies by action. */
+    retrieve(req: RetrieveRequest): Promise<unknown[]>;
     traverse(req: TraverseRequest): Promise<unknown>;
     evolve(req: EvolveRequest): Promise<unknown>;
     getNode(uid: string): Promise<GraphNode>;
+    /**
+     * Create a node via the low-level CRUD endpoint.
+     *
+     * The server requires `props._type` to determine the node variant.
+     * If `node_type` is provided and `_type` is not already in `props`,
+     * it is injected automatically.
+     */
     addNode(body: {
         label: string;
         node_type?: string;
@@ -376,16 +514,50 @@ declare class MindGraph {
         agent_id?: string;
     }): Promise<GraphNode>;
     deleteNode(uid: string): Promise<void>;
+    getNodeHistory(uid: string): Promise<unknown[]>;
+    getNodeAtVersion(uid: string, version: number): Promise<GraphNode>;
     addLink(body: {
         from_uid: string;
         to_uid: string;
         edge_type: string;
         agent_id?: string;
     }): Promise<unknown>;
+    /**
+     * Create an edge via the low-level CRUD endpoint.
+     *
+     * The server requires `props._type` to determine the edge variant.
+     * If `edge_type` is provided and `_type` is not already in `props`,
+     * it is injected automatically.
+     */
+    addEdge(body: {
+        from_uid: string;
+        to_uid: string;
+        edge_type: string;
+        weight?: number;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    updateEdge(uid: string, body: {
+        weight?: number;
+        props?: Record<string, unknown>;
+        agent_id?: string;
+    }): Promise<unknown>;
+    deleteEdge(uid: string): Promise<void>;
+    getEdgeHistory(uid: string): Promise<unknown[]>;
+    /**
+     * List edges filtered by source and/or target node.
+     * At least one of `from_uid` or `to_uid` is **required** —
+     * the server returns 400 if neither is provided.
+     */
     getEdges(params: {
         from_uid?: string;
         to_uid?: string;
     }): Promise<GraphEdge[]>;
+    getEdgeBetween(params: {
+        from_uid: string;
+        to_uid: string;
+        edge_type?: string;
+    }): Promise<GraphEdge[]>;
     search(query: string, opts?: {
         node_type?: string;
         layer?: string;
@@ -397,18 +569,79 @@ declare class MindGraph {
         node_types?: string[];
         layer?: string;
     }): Promise<SearchResult[]>;
+    getNodes(params?: {
+        node_type?: string;
+        layer?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    getAgentNodes(agentId: string): Promise<GraphNode[]>;
+    batch(req: BatchRequest): Promise<unknown>;
+    configureEmbeddings(body: {
+        model: string;
+        dimensions: number;
+        distance_metric?: string;
+    }): Promise<unknown>;
+    embeddingSearch(body: {
+        vector: number[];
+        k?: number;
+        node_types?: string[];
+        threshold?: number;
+    }): Promise<unknown>;
+    embeddingSearchText(body: {
+        text: string;
+        k?: number;
+        node_types?: string[];
+        threshold?: number;
+    }): Promise<unknown>;
+    getEmbedding(uid: string): Promise<unknown>;
+    setEmbedding(uid: string, vector: number[]): Promise<void>;
+    deleteEmbedding(uid: string): Promise<void>;
+    mergeEntities(body: {
+        keep_uid: string;
+        merge_uid: string;
+        agent_id?: string;
+    }): Promise<unknown>;
+    addAlias(body: {
+        text: string;
+        canonical_uid: string;
+        score?: number;
+    }): Promise<unknown>;
+    getAliases(uid: string): Promise<unknown>;
+    resolveAlias(text: string): Promise<unknown>;
+    exportGraph(): Promise<unknown>;
+    importGraph(data: unknown): Promise<unknown>;
+    decay(req: DecayRequest): Promise<unknown>;
+    purge(req?: PurgeRequest): Promise<unknown>;
     reasoningChain(uid: string, maxDepth?: number): Promise<PathStep[]>;
     neighborhood(uid: string, maxDepth?: number): Promise<PathStep[]>;
+    subgraph(uid: string, opts?: {
+        max_depth?: number;
+        direction?: "outgoing" | "incoming" | "both";
+        edge_types?: string[];
+        weight_threshold?: number;
+    }): Promise<{
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    }>;
     tombstone(uid: string, reason?: string, agentId?: string): Promise<unknown>;
     restore(uid: string, agentId?: string): Promise<unknown>;
-    signup(email: string, password: string): Promise<unknown>;
-    login(email: string, password: string): Promise<unknown>;
-    createApiKey(name?: string): Promise<ApiKeyResponse>;
-    listApiKeys(): Promise<{
-        api_keys: unknown[];
-    }>;
-    revokeApiKey(id: string): Promise<void>;
-    getUsage(): Promise<unknown>;
+    getGoals(): Promise<GraphNode[]>;
+    getOpenDecisions(): Promise<GraphNode[]>;
+    getOpenQuestions(): Promise<GraphNode[]>;
+    getWeakClaims(): Promise<GraphNode[]>;
+    getContradictions(): Promise<unknown[]>;
+    getPendingApprovals(): Promise<GraphNode[]>;
+    ingestChunk(req: IngestChunkRequest): Promise<IngestChunkResponse>;
+    ingestDocument(req: IngestDocumentRequest): Promise<IngestDocumentResponse>;
+    ingestSession(req: IngestSessionRequest): Promise<IngestDocumentResponse>;
+    retrieveContext(req: RetrieveContextRequest): Promise<RetrieveContextResponse>;
+    listJobs(): Promise<Job[]>;
+    getJob(id: string): Promise<Job>;
+    cancelJob(id: string): Promise<unknown>;
+    cleanupOrphans(): Promise<unknown>;
+    embedAll(): Promise<unknown>;
+    clearGraph(): Promise<ClearResponse>;
 }
 
-export { type ApiKeyResponse, type ArgumentRequest, type CommitmentRequest, type CreateApiKeyRequest, type CreateOrgRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestRequest, type InquiryRequest, type LoginRequest, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type PathStep, type PlanRequest, type ProcedureRequest, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type SignupRequest, type StructureRequest, type TraverseRequest };
+export { type ArgumentRequest, type BatchRequest, type CaptureRequest, type ClearResponse, type CommitmentRequest, type DecayRequest, type DeliberationRequest, type DistillRequest, type EntityRequest, type EvolveRequest, type ExecutionRequest, type GovernanceRequest, type GraphEdge, type GraphNode, type IngestChunkRequest, type IngestChunkResponse, type IngestDocumentRequest, type IngestDocumentResponse, type IngestSessionRequest, type InquiryRequest, type Job, type MemoryConfigRequest, MindGraph, type MindGraphConfig, MindGraphError, type PathStep, type PlanRequest, type ProcedureRequest, type PurgeRequest, type RetrieveContextRequest, type RetrieveContextResponse, type RetrieveRequest, type RiskRequest, type SearchResult, type SessionRequest, type StructureRequest, type TraverseRequest };