Skip to content
AgentCTX

@agentctx/client

@agentctx/client

Section titled “@agentctx/client”

A lightweight client library for connecting to a running AgentCTX gateway. Use this when you want to send CTX operations from your application without running the full gateway locally.

Installation

Section titled “Installation”
Terminal window
npm install @agentctx/client

Usage

Section titled “Usage”

Connect via HTTP/SSE

Section titled “Connect via HTTP/SSE”
import { AgentCTXClient } from '@agentctx/client';


const client = new AgentCTXClient({
  url: 'http://localhost:3100',
  transport: 'sse'
});


await client.connect();

Send Operations

Section titled “Send Operations”
// Search tools
const tools = await client.query('?t github');
// { ok: true, data: { results: [...] } }


// Store a memory
await client.query('+m "decision" #arch "Use PASETO"');


// Search knowledge
const results = await client.query('?k "auth patterns" #code ^3');


// Call a tool
const issues = await client.query('>t github.issues.list state="open" ^5');

Subscribe to Events

Section titled “Subscribe to Events”
// Live memory updates
client.subscribe('?m #team #live', (event) => {
  console.log('Memory updated:', event);
});


// Live knowledge changes
client.subscribe('?k #live', (event) => {
  console.log('Knowledge updated:', event);
});

Disconnect

Section titled “Disconnect”
await client.disconnect();

Configuration

Section titled “Configuration”
interface ClientConfig {
  url: string;              // Gateway URL
  transport: 'sse' | 'http'; // Transport type
  auth?: {
    token: string;          // JWT for authentication
  };
  timeout?: number;         // Request timeout in ms (default: 30000)
  retries?: number;         // Auto-retry count (default: 3)
}

Error Handling

Section titled “Error Handling”
try {
  const result = await client.query('>t invalid.tool');
} catch (err) {
  if (err.code === 'TOOL_NOT_FOUND') {
    // Handle missing tool
  }
}

See Also

Section titled “See Also”