mindgraph
v0.17.0
Published
TypeScript client for the MindGraph Cloud API
Downloads
556
Maintainers
Readme
mindgraph
TypeScript client for the MindGraph Cloud API — a structured semantic memory graph for AI agents.
Install
npm install mindgraphQuick Start
import { MindGraph } from "mindgraph";
const graph = new MindGraph({
baseUrl: "https://api.mindgraph.cloud",
apiKey: "mg_...",
});
// 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 (BM25 + vector)
const results = await graph.search("what does the user prefer?");
// 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",
edge_type: "BelongsTo",
});API Reference
Constructor
new MindGraph({ baseUrl: string, apiKey?: string, jwt?: string, timeoutMs?: number })Reality Layer
| Method | Description |
|--------|-------------|
| capture(req) | Capture a source, snippet, or observation |
| entity(req) | Create, alias, resolve, or merge entities |
| series(req) | Call the typed time-series action surface directly |
| createSeries / appendSeries / seriesWindow | Create a Series, append sourced points, and page through a bounded time window |
| aggregateSeries / latestSeries / listSeriesForEntity | Read bounded aggregates, cached latest values, and an entity's Series |
| batchLatestSeries / batchAggregateSeries / deleteSeries | Compare Series across entities or tombstone a Series and its points |
| findOrCreateEntity(label, props?, agentId?) | Convenience: create or find an entity by label (generic fallback) |
| findOrCreatePerson(label, props?, agentId?) | Find or create a Person entity |
| findOrCreateOrganization(label, props?, agentId?) | Find or create an Organization entity |
| findOrCreateNation(label, props?, agentId?) | Find or create a Nation entity |
| findOrCreateEvent(label, props?, agentId?) | Find or create an Event entity |
| findOrCreatePlace(label, props?, agentId?) | Find or create a Place entity |
| findOrCreateConcept(label, props?, agentId?) | Find or create a Concept entity |
| addClaim(label, content, confidence?, agentId?) | Add a Claim node via the argument endpoint |
| addEvidence(label, description, agentId?) | Add an Evidence node attached to a claim |
| addObservation(label, description, agentId?) | Add an Observation node |
Typed entity example:
const person = await graph.findOrCreatePerson("Marie Curie", { nationality: "Polish" });
const org = await graph.findOrCreateOrganization("CERN", { org_type: "intergovernmental" });
const concept = await graph.findOrCreateConcept("Nuclear Physics");
// findOrCreateEntity() still works as a generic fallback for any entity type
const entity = await graph.findOrCreateEntity("Some Entity");Epistemic Layer
| Method | Description |
|--------|-------------|
| argue(req) | Construct a full argument: claim + evidence + warrant + edges |
| inquire(req) | Add hypothesis, theory, paradigm, anomaly, assumption, or question |
| structure(req) | Add concept, pattern, mechanism, model, analogy, theorem, etc. |
Intent Layer
| Method | Description |
|--------|-------------|
| commit(req) | Create a goal, project, or milestone |
| deliberate(req) | Open decisions, add options/constraints, resolve decisions |
| resolveDecision(decisionUid, optionUid, opts) | Resolve with optional dated context and session/retrieval-trace linkage |
Action Layer
| Method | Description |
|--------|-------------|
| procedure(req) | Build flows, add steps, affordances, and controls |
| risk(req) | Assess risk or retrieve existing assessments |
Memory Layer
| 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 |
| 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 |
output_type: "skill" requires caller-authored SKILL.md content and at
least one provenance field. It always creates a candidate for review:
await graph.distill({
label: "Recover a malformed import",
output_type: "skill",
work_uid: "work_import_42",
props: {
name: "recover-malformed-import",
description: "Use after a spreadsheet import fails schema validation.",
content: "# Recovery\n\nValidate headers, normalize dates, then retry.",
},
});Agent Layer
| Method | Description |
|--------|-------------|
| plan(req) | Create tasks, plans, plan steps, update status |
| governance(req) | Create policies, set safety budgets, request/resolve approvals |
| execution(req) | Track execution lifecycle and register agents |
Synthesis (Projects)
Scope a corpus to a Project (via commit({ action: "project", ... }) then link documents with PartOfProject), then mine cross-document signals and generate synthesis articles.
| Method | Description |
|--------|-------------|
| signals(projectUid, opts?) | Mine cross-document structural signals for a project (entity bridges, claim hubs, theory gaps, concept clusters, analogies, dialectical pairs) |
| runSynthesis(projectUid) | Spawn an async synthesis job that turns top clusters into Article nodes; returns a job_id to poll via getJob() |
const project = await graph.commit({ action: "project", label: "Q2 China strategy" });
// ...link documents to the project via PartOfProject edges...
const signals = await graph.signals(project.uid, { signals: "clustered_claim_hubs,dialectical_pairs" });
const { job_id } = await graph.runSynthesis(project.uid);
const job = await graph.getJob(job_id);Operational Ontology (Layer 7)
Define typed domain objects (Customer, Order, Contract…) as a semantic contract and either bind them to a SQL database or extract them from documents — fused onto one object. Connecting a database (credentials/sync) is done in the dashboard; the SDK proposes/reviews schemas, queries, and lists the generated agent read tools.
| Method | Description |
|--------|-------------|
| proposeOntologySchema(req) | Draft a schema from a description (+ optional sample docs); returns { schema_id, job_id } |
| activateOntologySchema(id) / getOntologySchema(id) / listOntologySchemas() | Schema lifecycle |
| createOntologySeriesBinding / syncOntologySeriesBinding / archiveOntologySeriesBinding | Manage SQL-backed dense-measurement bindings |
| listOntologyProposals(opts?) / approveOntologyProposal(id) / rejectOntologyProposal(id) | Review extracted-object proposals |
| queryOntology({ query, include_cognitive_context }) | Typed retrieval with the cognitive overlay fused in |
| listOntologyTools() | The generated read-tool manifest (search_/get_/summarize_<obj>) the MCP server renders |
const { schema_id } = await graph.proposeOntologySchema({ description: "Clients, orders, contracts." });
await graph.activateOntologySchema(schema_id);
const { tools } = await graph.listOntologyTools();
const ctx = await graph.queryOntology({ query: "Which customers are a churn risk?", include_cognitive_context: true });See the Operational Ontology and Connect a database docs.
CRUD
| Method | Description |
|--------|-------------|
| getNode(uid) | Get a node by UID |
| addNode({ label, node_type?, props?, agent_id? }) | Add a generic node |
| updateNode(uid, { label?, summary?, confidence?, salience? }) | Update node fields |
| deleteNode(uid) | Tombstone a node and all connected edges |
| addLink({ from_uid, to_uid, edge_type, agent_id? }) | Add a typed edge |
| getEdges({ from_uid?, to_uid? }) | Get edges by source or target |
Search
| Method | Description |
|--------|-------------|
| search(query, { node_type?, layer?, limit? }) | Full-text search |
| hybridSearch(query, { k?, node_types?, layer?, explain? }) | BM25 + vector search with rank fusion; explain: true attaches per-leg contributions (legs: which legs surfaced each result, the within-leg rank the fusion used, and the leg's raw score) |
| getMergeCandidates() | Pending duplicate pairs recorded by the dedup pipeline, awaiting merge/dismiss |
Traversal
| Method | Description |
|--------|-------------|
| 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) | Direct retrieval plus optional cheapest-first graph expansion (graph_expansion_limit, graph_max_depth) |
| 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 |
|--------|-------------|
| retrieve(req) | Unified retrieval: text search, active goals, open questions, weak claims |
| traverse(req) | Budgeted min-cost traversal; depth is the selected witness hop count |
| evolve(req) | Lifecycle mutations: update, tombstone, restore, decay, history |
Health & Stats
| Method | Description |
|--------|-------------|
| health() | Health check |
| stats() | Graph-wide statistics |
Account sign-up, login, and API key management live in the MindGraph dashboard — not the SDK. Get your API key there, then pass it to the
MindGraphconstructor.
Examples
See examples/ for runnable demos, including a research continuity scenario showing cross-session memory retrieval.
Error Handling
All methods throw MindGraphError on HTTP errors:
import { MindGraphError } from "mindgraph";
try {
await graph.getNode("nonexistent");
} catch (err) {
if (err instanceof MindGraphError) {
console.error(err.status, err.body);
}
}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.
