@sperax/tool-knowledge-graph

Visualize and explore your growing knowledge graph as an interactive network

Knowledge Graph is an agent tool from SperaxOS, packaged headless so you can call it from any agent framework. It ships two things: the manifest — a JSON-Schema function definition a model can call — and the executor that runs the call against the real API.

There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.

Install

npm install @sperax/tool-knowledge-graph

Usage

Call it directly

import { knowledgeGraphExecutor } from '@sperax/tool-knowledge-graph';

const result = await knowledgeGraphExecutor.invoke('getGraphData', {"minConfidence":1,"nodeType":"concept"}, {
  messageId: 'msg-1',
});

console.log(result.content); // prose summary written for the model to read
console.log(result.state);   // typed data payload for your own UI

Give it to a model

import Anthropic from '@anthropic-ai/sdk';
import { KnowledgeGraphManifest, knowledgeGraphExecutor } from '@sperax/tool-knowledge-graph';

const client = new Anthropic();

const response = await client.messages.create({
  model: 'claude-opus-4-8',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
  tools: KnowledgeGraphManifest.api.map((api) => ({
    name: api.name,
    description: api.description,
    input_schema: api.parameters,
  })),
});

for (const block of response.content) {
  if (block.type !== 'tool_use') continue;
  const result = await knowledgeGraphExecutor.invoke(block.name, block.input, { messageId: response.id });
  console.log(result.content);
}

KnowledgeGraphManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API — Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.

Every executor returns a BuiltinToolResult — { success, content, state }. content is prose written for the model to read; state is the typed data payload for your own code. Executors never throw: a failed call comes back as { success: false, content: '<reason>' }, so a network blip degrades the answer instead of crashing the agent loop.

Configuration

None. This tool calls a public API directly and needs no key or origin configuration.

Tool identifier

sperax-knowledge-graph

API reference

getGraphData

Retrieve the full knowledge graph data with nodes (concepts, entities, facts, etc.), edges (relationships), and clusters (topic groups). Supports optional filtering by node type, minimum confidence level, and time range.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | minConfidence | number | no | Minimum confidence level (0-1). Only return nodes with confidence >= this value. | | nodeType | concept | entity | fact | opinion | question | decision | no | Filter by node type. Omit to include all types. | | since | string | no | ISO 8601 timestamp. Only return nodes created after this time, useful for "what's new" views. |

searchGraph

Search the knowledge graph for nodes matching a query. Returns matching nodes with relevance scores and their connecting edges.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Maximum number of matching nodes to return. | | query | string | yes | The search query to match against node labels and descriptions. |

getNodeDetail

Get full details for a specific knowledge node including its description, sources, connected conversations, documents, neighbor nodes, and evolution timeline.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | nodeId | string | yes | The ID of the node to get details for. |

getGraphInsights

Analyze the knowledge graph structure and return insights: most connected concepts (hub nodes), isolated knowledge (sparse nodes), recent growth areas, and cross-domain bridges (nodes connecting different clusters).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | limit | number | no | Number of items per insight category. |

Types

Shared types come from @sperax/agent-tools-core: BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor class every tool executor extends.

Related

• @sperax/agent-tools-core — the tool contract
• All SperaxOS agent tools — tool-knowledge-graph is one of many
• SperaxOS — the agent workspace these tools were built for

License

Apache-2.0