SDKs

npm install mindgraph

import { MindGraph } from "mindgraph"

const graph = new MindGraph({
  baseUrl: "https://api.mindgraph.cloud",
  apiKey: process.env.MINDGRAPH_API_KEY!,
})

// Quick journal note (lowest friction)
await graph.journal("User prefers dark mode", {
  content: "Explicitly requested dark theme across all devices",
})

// Capture a source and extract snippets
const src = await graph.capture({
  action: "source",
  label: "Product meeting notes",
  props: { source_type: "meeting_notes" },
})
await graph.capture({
  action: "snippet",
  label: "Dark mode is top priority",
  source_uid: src.uid,
  props: { content: "Team agreed dark mode should ship this sprint" },
})

// Structured knowledge: claim + evidence
await graph.argue({
  claim: { label: "Dark mode improves UX", props: { content: "Reduces eye strain at night" } },
  evidence: [{ label: "User feedback", props: { description: "3 users mentioned it this week" } }],
  agent_id: "ux-agent",
})

// Set a goal
await graph.commit({
  action: "goal",
  label: "Ship dark mode",
  props: { description: "Implement dark mode", priority: "high", success_criteria: ["Theme toggle in settings"] },
})

// Session management
const session = await graph.session({ action: "open", label: "Dark mode sprint" })
await graph.journal("Started dark mode implementation", {
  content: "Using CSS custom properties for theme switching",
}, { session_uid: session.uid })
await graph.session({ action: "close", session_uid: session.uid })

// Search by keyword or meaning
const results = await graph.search("dark mode")
const semantic = await graph.hybridSearch("user theme preferences", { k: 10 })

// Retrieve current status
const goals = await graph.retrieve({ action: "active_goals" })
const questions = await graph.retrieve({ action: "open_questions" })
const recent = await graph.retrieve({ action: "recent", limit: 20 })

// Explore the graph
const chain = await graph.reasoningChain("clm_dark_mode", 5)
const neighbors = await graph.neighborhood("goal_dark_mode", 2)

// Extract a subgraph for context
const subgraph = await graph.traverse({
  action: "subgraph",
  start_uid: "goal_dark_mode",
  max_depth: 3,
})

import { MindGraphError } from "mindgraph"

try {
  await graph.getNode("bad-uid")
} catch (err) {
  if (err instanceof MindGraphError) {
    console.error(err.status) // 404
    console.error(err.body)   // { error: "not found" }
  }
}

// Configure embeddings
await graph.configureEmbeddings({ model: "text-embedding-3-small", dimensions: 1536 })

// Vector search
const results = await graph.embeddingSearchText({ text: "dark mode preferences", k: 5 })

// Convenience methods for first-class entity types
const person = await graph.findOrCreatePerson("Ada Lovelace", {
  description: "Mathematician and first computer programmer",
})
const org = await graph.findOrCreateOrganization("Acme Corp", {
  org_type: "company",
  description: "Enterprise SaaS startup",
})
const nation = await graph.findOrCreateNation("United Kingdom")
const event = await graph.findOrCreateEvent("AI Summit 2026", {
  event_date: "2026-06-15",
})
const place = await graph.findOrCreatePlace("London")
const concept = await graph.findOrCreateConcept("Machine Learning")

// Add claims, evidence, and observations
await graph.addClaim("TypeScript improves productivity", {
  content: "Static types catch bugs at compile time",
})
await graph.addEvidence("Type safety study", {
  description: "2024 study showed 15% fewer bugs",
})
await graph.addObservation("Users prefer dark mode", {
  content: "3 out of 5 users requested dark theme",
})

// findOrCreateEntity still works as a fallback for other types
const tech = await graph.findOrCreateEntity("TypeScript", { entity_type: "technology" })

// Batch create nodes + edges
await graph.batch({
  nodes: [
    { label: "Ada Lovelace", node_type: "Person" },
    { label: "Acme Corp", node_type: "Organization" },
    { label: "Machine Learning", node_type: "Concept" },
  ],
  edges: [
    { from_uid: "uid_a", to_uid: "uid_b", edge_type: "WorksFor" },
  ],
})

// Epistemic queries
const goals = await graph.getGoals()
const decisions = await graph.getOpenDecisions()
const questions = await graph.getOpenQuestions()
const weakClaims = await graph.getWeakClaims()
const contradictions = await graph.getContradictions()
const approvals = await graph.getPendingApprovals()

// Subgraph extraction
const sub = await graph.subgraph("node_uid", { max_depth: 2, direction: "both" })

// Ingest a single text chunk (synchronous)
await graph.ingestChunk({
  content: "Dark mode reduces eye strain and improves readability at night.",
  chunk_type: "note",
})

// Ingest a full document (async — returns a job ID)
const job = await graph.ingestDocument({
  content: meetingTranscript,
  title: "Product meeting 2026-03-10",
  content_type: "meeting_notes",
  source_uri: "https://docs.google.com/...",
})
console.log(job.job_id) // "job_abc123"

// Ingest a session transcript (async — returns a job ID)
const sessionJob = await graph.ingestSession({
  content: chatHistory,
  session_uid: "ses_sprint_review",
})

// Poll job status until complete
const status = await graph.getJob(job.job_id)
console.log(status.status) // "pending" | "processing" | "completed" | "failed"

// Retrieve articles + graph context with provenance
const ctx = await graph.retrieveContext({
  query: "What did we decide about dark mode?",
  node_limit: 10,
  article_limit: 3,
})
console.log(ctx.articles)     // synthesized wiki articles
console.log(ctx.graph.nodes)  // knowledge nodes (with source_documents)
console.log(ctx.graph.edges)  // connecting edges

// Batch fetch multiple nodes or edges by UID
const nodes = await graph.getNodesBatch(["uid_1", "uid_2", "uid_3"])
const edges = await graph.getEdgesBatch(["uid_1", "uid_2"])

// List all ingestion jobs
const jobs = await graph.listJobs()

// Resume a failed document ingestion
await graph.resumeDocument("doc_uid_123")

// Delete a document and all its extracted content
await graph.deleteDocument("doc_uid_123")

// Batch delete nodes by UID or agent
await graph.batchDeleteNodes({ uids: ["uid_1", "uid_2"] })
await graph.batchDeleteNodes({ agentId: "my-agent" })

// Clean up orphaned chunks with no parent document
await graph.cleanupOrphans()

// Generate embeddings for all nodes missing one
await graph.embedAll()

// Clear all graph data
await graph.clearGraph()

pip install mindgraph-sdk

from mindgraph import MindGraph

graph = MindGraph("https://api.mindgraph.cloud", api_key="mg_...")

# Quick journal note (lowest friction)
graph.journal("User prefers dark mode", props={
    "content": "Explicitly requested dark theme across all devices",
})

# Capture a source and extract snippets
src = graph.capture(action="source", label="Product meeting notes",
    props={"source_type": "meeting_notes"})
graph.capture(action="snippet", label="Dark mode is top priority",
    source_uid=src["uid"],
    props={"content": "Team agreed dark mode should ship this sprint"})

# Structured knowledge: claim + evidence
graph.argue(
    claim={"label": "Dark mode improves UX",
           "props": {"content": "Reduces eye strain at night"}},
    evidence=[{"label": "User feedback",
               "props": {"description": "3 users mentioned it this week"}}],
    agent_id="ux-agent",
)

# Set a goal
graph.commit(action="goal", label="Ship dark mode", props={
    "description": "Implement dark mode", "priority": "high",
    "success_criteria": ["Theme toggle in settings"],
})

# Session management
session = graph.session(action="open", label="Dark mode sprint")
graph.journal("Started dark mode implementation", props={
    "content": "Using CSS custom properties for theme switching",
}, session_uid=session["uid"])
graph.session(action="close", session_uid=session["uid"])

# Search by keyword or meaning
results = graph.search("dark mode")
semantic = graph.hybrid_search("user theme preferences", k=10)

# Retrieve current status
goals = graph.retrieve(action="active_goals")
questions = graph.retrieve(action="open_questions")
recent = graph.retrieve(action="recent", limit=20)

# Explore the graph
chain = graph.reasoning_chain("clm_dark_mode", max_depth=5)
neighbors = graph.neighborhood("goal_dark_mode", max_depth=2)

# Extract a subgraph for context
subgraph = graph.traverse(
    action="subgraph",
    start_uid="goal_dark_mode",
    max_depth=3,
)

from mindgraph import MindGraphError

try:
    graph.get_node("bad-uid")
except MindGraphError as e:
    print(e.status)  # 404
    print(e.body)    # {"error": "not found"}

# Configure embeddings
graph.configure_embeddings(model="text-embedding-3-small", dimensions=1536)

# Vector search
results = graph.embedding_search_text(text="dark mode preferences", k=5)

# Convenience methods for first-class entity types
person = graph.find_or_create_person("Ada Lovelace", props={
    "description": "Mathematician and first computer programmer",
})
org = graph.find_or_create_organization("Acme Corp", props={
    "org_type": "company",
    "description": "Enterprise SaaS startup",
})
nation = graph.find_or_create_nation("United Kingdom")
event = graph.find_or_create_event("AI Summit 2026", props={
    "event_date": "2026-06-15",
})
place = graph.find_or_create_place("London")
concept = graph.find_or_create_concept("Machine Learning")

# Add claims, evidence, and observations
graph.add_claim("TypeScript improves productivity", props={
    "content": "Static types catch bugs at compile time",
})
graph.add_evidence("Type safety study", props={
    "description": "2024 study showed 15% fewer bugs",
})
graph.add_observation("Users prefer dark mode", props={
    "content": "3 out of 5 users requested dark theme",
})

# find_or_create_entity still works as a fallback for other types
tech = graph.find_or_create_entity("TypeScript", props={"entity_type": "technology"})

# Batch create nodes + edges
graph.batch(
    nodes=[
        {"label": "Ada Lovelace", "node_type": "Person"},
        {"label": "Acme Corp", "node_type": "Organization"},
        {"label": "Machine Learning", "node_type": "Concept"},
    ],
    edges=[
        {"from_uid": "uid_a", "to_uid": "uid_b", "edge_type": "WorksFor"},
    ],
)

# Epistemic queries
goals = graph.get_goals()
decisions = graph.get_open_decisions()
questions = graph.get_open_questions()
weak_claims = graph.get_weak_claims()
contradictions = graph.get_contradictions()
approvals = graph.get_pending_approvals()

# Subgraph extraction
sub = graph.subgraph("node_uid", max_depth=2, direction="both")

# Ingest a single text chunk (synchronous)
graph.ingest_chunk(
    content="Dark mode reduces eye strain and improves readability at night.",
    chunk_type="note",
)

# Ingest a full document (async — returns a job ID)
job = graph.ingest_document(
    content=meeting_transcript,
    title="Product meeting 2026-03-10",
    content_type="meeting_notes",
    source_uri="https://docs.google.com/...",
)
print(job["job_id"])  # "job_abc123"

# Ingest a session transcript (async — returns a job ID)
session_job = graph.ingest_session(
    content=chat_history,
    session_uid="ses_sprint_review",
)

# Poll job status until complete
status = graph.get_job(job["job_id"])
print(status["status"])  # "pending" | "processing" | "completed" | "failed"

# Retrieve articles + graph context with provenance
ctx = graph.retrieve_context(
    query="What did we decide about dark mode?",
    node_limit=10,
    article_limit=3,
)
print(ctx["articles"])           # synthesized wiki articles
print(ctx["graph"]["nodes"])     # knowledge nodes (with source_documents)
print(ctx["graph"]["edges"])     # connecting edges

# Batch fetch multiple nodes or edges by UID
nodes = graph.get_nodes_batch(["uid_1", "uid_2", "uid_3"])
edges = graph.get_edges_batch(["uid_1", "uid_2"])

# List all ingestion jobs
jobs = graph.list_jobs()

# Resume a failed document ingestion
graph.resume_document("doc_uid_123")

# Delete a document and all its extracted content
graph.delete_document("doc_uid_123")

# Batch delete nodes by UID or agent
graph.batch_delete_nodes(uids=["uid_1", "uid_2"])
graph.batch_delete_nodes(agent_id="my-agent")

# Clean up orphaned chunks with no parent document
graph.cleanup_orphans()

# Generate embeddings for all nodes missing one
graph.embed_all()

# Clear all graph data
graph.clear_graph()