TypeScript SDK

The official TypeScript client for LocusGraph — store events, retrieve knowledge, and generate insights from your wisdom graph.

Installation

npm install @locusgraph/client

Configuration

import { LocusGraphClient } from '@locusgraph/client';
 
const client = new LocusGraphClient({
  serverUrl: 'https://api.locusgraph.com',  // optional, default
  agentSecret: 'your-agent-secret',
  graphId: 'default',  // optional default graph
});

Set LOCUSGRAPH_SERVER_URL and LOCUSGRAPH_AGENT_SECRET as environment variables to avoid hardcoding credentials. The client reads these automatically when no explicit values are provided.

Store Event

Use storeEvent to add knowledge to your wisdom graph. Each event captures a fact, action, decision, or observation.

const response = await client.storeEvent({
  graph_id: 'default',
  event_kind: 'fact',
  source: 'onboarding-flow',
  context_id: 'user-preferences',
  payload: 'User prefers dark mode and weekly email digests.',
  reinforces: ['ctx-abc123'],
  extends: [],
  contradicts: [],
  related_to: ['ctx-def456'],
  timestamp: '2025-01-15T10:30:00Z',
});
 
// Response
// {
//   eventId: 'evt-789',
//   contextId: 'user-preferences',
//   status: 'stored'
// }

Field	Required	Description
`graph_id`	Yes	Target graph identifier
`event_kind`	Yes	Event type: `fact`, `action`, `decision`, `observation`, `feedback`
`payload`	Yes	The knowledge content
`source`	No	Origin of the event
`context_id`	No	Group events under a context
`reinforces`	No	Array of context IDs this event reinforces
`extends`	No	Array of context IDs this event extends
`contradicts`	No	Array of context IDs this event contradicts
`related_to`	No	Array of related context IDs
`timestamp`	No	ISO 8601 timestamp string

Retrieve Knowledge

Use retrieveMemories to run semantic search across your wisdom graph.

const result = await client.retrieveMemories({
  graphId: 'default',
  query: 'What are the user preferences for notifications?',
  limit: 5,
  contextIds: ['user-preferences'],
  contextTypes: ['fact', 'decision'],
});
 
// Response
// {
//   memories: [
//     {
//       contextId: 'user-preferences',
//       content: 'User prefers weekly email digests.',
//       score: 0.92,
//       contextType: 'fact',
//       timestamp: '2025-01-15T10:30:00Z'
//     }
//   ]
// }

Field	Required	Description
`graphId`	No	Uses default from config if omitted
`query`	Yes	Natural language search query
`limit`	No	Max results to return
`contextIds`	No	Filter by specific context IDs
`contextTypes`	No	Filter by context types

Get Context

Fetch a single context by its ID. Throws Error('Context not found') on 404.

try {
  const context = await client.getContext({
    context_id: 'user-preferences',
    graph_id: 'default',
  });
 
  // Response
  // {
  //   contextId: 'user-preferences',
  //   contextType: 'fact',
  //   content: 'User prefers dark mode and weekly email digests.',
  //   createdAt: '2025-01-15T10:30:00Z',
  //   updatedAt: '2025-01-15T10:30:00Z'
  // }
} catch (err) {
  console.error(err.message); // 'Context not found'
}

List Contexts

Browse context types, list contexts by type, or search by name.

// List all context types
const types = await client.listContexts({ graph_id: 'default' });
 
// List contexts by type
const facts = await client.listContexts({
  graph_id: 'default',
  context_type: 'fact',
});
 
// Search contexts by name
const results = await client.listContexts({
  graph_id: 'default',
  query: 'preferences',
});

Generate Insights

Use generateInsights to reason over your wisdom graph and produce synthesized answers.

const insight = await client.generateInsights({
  graphId: 'default',
  task: 'Summarize this user preferences and suggest personalization strategies.',
  locusQuery: 'user preferences and settings',
  limit: 10,
  contextIds: ['user-preferences'],
  contextTypes: ['fact', 'decision'],
});
 
// Response
// {
//   insight: 'Based on stored knowledge, the user prefers dark mode...',
//   sources: ['ctx-abc123', 'ctx-def456'],
//   confidence: 0.89
// }

Field	Required	Description
`graphId`	No	Uses default from config if omitted
`task`	Yes	The reasoning task or question
`locusQuery`	No	Optional query to scope relevant knowledge
`limit`	No	Max source contexts to consider
`contextIds`	No	Filter by specific context IDs
`contextTypes`	No	Filter by context types

Environment Variables

Variable	Description
`LOCUSGRAPH_SERVER_URL`	API server URL (default: `https://api.locusgraph.com`)
`LOCUSGRAPH_AGENT_SECRET`	Your agent secret key

Python SDK

Use LocusGraph with Python.

LangChain Integration

Connect LocusGraph to LangChain agents.