pentatonic-ai-agent-sdk 0.4.0b1

AI Agent SDK — observability, memory, and analytics for LLM applications. Provider-agnostic. Tracks token usage, tool calls, conversations, and enables shared team memory.

AI Agent SDK

Observability, memory, and analytics for LLM applications.
Run locally or use hosted TES. JavaScript & Python.

---

Table of Contents

• Overview
• Local Memory (self-hosted)
• Hosted TES
• Claude Code Plugin
• SDK: Wrap Your LLM Client
• Supported Providers
• API Reference
• Architecture

Overview

Two ways to use the SDK:

Local Memory -- Run a fully private memory system on your own machine. PostgreSQL + pgvector + Ollama in Docker. No API keys, no cloud. Your agent gets persistent, searchable memory backed by multi-signal retrieval and HyDE query expansion.

Hosted TES -- Connect to Pentatonic's Thing Event System for production-grade observability, higher-dimensional embeddings, conversation analytics, and team-wide shared memory.

Both paths use the same Claude Code plugin. The hooks auto-search on every prompt and auto-store every conversation turn.

Local Memory (self-hosted)

Run the full memory stack locally. Requires Docker and ~4GB disk for models.

1. Set up

npx @pentatonic-ai/ai-agent-sdk memory

This starts PostgreSQL + pgvector, Ollama, and the memory server. It pulls embedding and chat models, and writes the local config.

2. Install the Claude Code plugin

/plugin marketplace add Pentatonic-Ltd/ai-agent-sdk
/plugin install tes-memory@pentatonic-ai

That's it. The plugin hooks automatically search memories on every prompt and store every conversation turn. Fully local, fully private.

What you get

• Automatic memory -- every conversation turn is stored with embeddings and HyDE query expansion
• Semantic search -- multi-signal retrieval combining vector similarity, BM25 full-text, recency decay, and access frequency
• Memory layers -- episodic (recent), semantic (consolidated), procedural (how-to), working (temporary)
• Decay and consolidation -- memories fade over time; frequently accessed ones get promoted

Change models

EMBEDDING_MODEL=mxbai-embed-large LLM_MODEL=qwen2.5:7b npx @pentatonic-ai/ai-agent-sdk memory

Raspberry Pi

Pi 5 with 8GB RAM runs the full stack. nomic-embed-text (~300MB) + llama3.2:3b (~2GB) leaves plenty of headroom.

Use as a library

import { createMemorySystem } from '@pentatonic-ai/ai-agent-sdk/memory';

const memory = createMemorySystem({
  db: pgPool,
  embedding: { url: 'http://localhost:11434/v1', model: 'nomic-embed-text' },
  llm: { url: 'http://localhost:11434/v1', model: 'llama3.2:3b' },
});

await memory.migrate();
await memory.ensureLayers('my-app');
await memory.ingest('User prefers dark mode', { clientId: 'my-app' });
const results = await memory.search('preferences', { clientId: 'my-app' });

Hosted TES

Connect to Pentatonic's hosted infrastructure for production use.

1. Create an account

npx @pentatonic-ai/ai-agent-sdk init

This walks you through account creation, email verification, and API key generation. You'll get:

TES_ENDPOINT=https://your-company.api.pentatonic.com
TES_CLIENT_ID=your-company
TES_API_KEY=tes_your-company_xxxxx

2. Install

npm install @pentatonic-ai/ai-agent-sdk

pip install pentatonic-ai-agent-sdk

What you get (in addition to local features)

• Higher-dimensional embeddings -- NV-Embed-v2 (4096d) for better retrieval accuracy
• Conversation analytics -- session metrics, search attribution, dead-end detection
• Team-wide shared memory -- semantic search across your team's AI interactions
• Admin dashboard -- visualize conversations, token usage, and memory explorer
• Multi-tenancy -- isolated databases per client

Claude Code Plugin

Works with both local and hosted setups. Install once, switch modes via config.

Install via marketplace

/plugin marketplace add Pentatonic-Ltd/ai-agent-sdk
/plugin install tes-memory@pentatonic-ai

Set up

For hosted TES:

/tes-memory:tes-setup

For local memory:

npx @pentatonic-ai/ai-agent-sdk memory

What it tracks

• Every conversation turn -- user messages, assistant responses, tool calls, duration
• Automatic memory search -- relevant memories injected as context on every prompt
• Automatic memory storage -- every turn stored with embeddings and HyDE queries
• Token usage -- input, output, cache read, cache creation tokens per turn

SDK: Wrap Your LLM Client

JavaScript

import { TESClient } from "@pentatonic-ai/ai-agent-sdk";

const tes = new TESClient({
  clientId: process.env.TES_CLIENT_ID,
  apiKey: process.env.TES_API_KEY,
  endpoint: process.env.TES_ENDPOINT,
});

const ai = tes.wrap(new OpenAI(), { sessionId: "conv-123" });
const result = await ai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

Python

from pentatonic_agent_events import TESClient

tes = TESClient(
    client_id=os.environ["TES_CLIENT_ID"],
    api_key=os.environ["TES_API_KEY"],
    endpoint=os.environ["TES_ENDPOINT"],
)

ai = tes.wrap(OpenAI(), session_id="conv-123")
result = ai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

Supported Providers

Provider	Detection	Intercepted Method
OpenAI	client.chat.completions.create	chat.completions.create()
Anthropic	client.messages.create	messages.create()
Workers AI	client.run (JS only)	run()

All other methods pass through unchanged.

API Reference

TESClient(config)

Param	Type	Default	Description
clientId	string	required	Your tenant identifier
apiKey	string	required	TES API key
endpoint	string	required	TES instance URL
userId	string	null	User identifier for attribution
captureContent	boolean	true	Include message content in events
maxContentLength	number	4096	Truncate content beyond this length

tes.wrap(client, opts?)

Returns an instrumented proxy. Every intercepted call emits a CHAT_TURN event.

Option	Type	Default	Description
sessionId	string	auto-generated UUID	Links events from the same conversation
metadata	object	{}	Custom fields on every event

tes.session(opts?)

Returns a Session for manual event emission.

session.emitChatTurn({ userMessage, assistantResponse, turnNumber? })

Emits a CHAT_TURN event with accumulated data, then resets.

normalizeResponse(raw)

Standalone utility to normalize any LLM response:

import { normalizeResponse } from "@pentatonic-ai/ai-agent-sdk";

const { content, model, usage, toolCalls } = normalizeResponse(openaiResponse);

Architecture

                    +-----------------------+
                    |   Claude Code Plugin  |
                    |   (hooks: auto-search |
                    |    + auto-store)      |
                    +-----------+-----------+
                                |
                    +-----------+-----------+
                    |                       |
              Local Memory            Hosted TES
              (Docker)                (Cloud)
                    |                       |
         +----+----+----+          +---+----+---+
         |    |    |    |          |   |    |   |
        PG  Ollama MCP HTTP      PG  R2  Queue Workers
        pgvector        API     pgvector       Modules

License

MIT