@threadbase/JS

Official TypeScript/JavaScript SDK for Threadbase

Threadbase is a developer-first memory intelligence tracing layer for LLM-powered applications.

This SDK lets you Track, debug, and version what your AI Agent remembers, and detect whether memory was actually used—without modifying your LLM runtime.

Use it to gain full visibility into how your agents think, recall, and behave across sessions.

📦 Features

• 📊 Trace logging for every user-agent interaction
• 🧠 Memory tracking across sessions and versions
• 🔍 Insightful diffs between memory states
• 📚 Session-based trace retrieval
• 🔧 Metadata and tool usage annotation
• ⚡ Simple, fast, and fully typed API

🚀 Installation

Install via your preferred package manager:

npm install @threadbase/js
# or
yarn add @threadbase/js

🛠️ Quick Start

import { ThreadbaseClient } from '@threadbase/js';

// Initialize the Threadbase client
const client = new ThreadbaseClient({
  apiKey: 'your-api-key', // required
  baseUrl: 'https://api.threadbase.dev' // optional
});

// Example 1: Create a trace with implicit memory usage
const trace1 = await client.trace({
  user_id: '555',
  agent_id: '8a219d38-3d88-48b3-969e-adf8ede035e1',
  session_id: '99949',
  user_prompt: 'Where should I go next weekend?',
  agent_response: 'Since you like hiking, you might enjoy Banff National Park.',
  memory: null
});

// Example 2: Create a trace with explicit memory injection
const trace2 = await client.trace({
  user_id: 'user_555',
  agent_id: '8a219d38-3d88-48b3-969e-adf8ede035e1',
  session_id: 'session_99949',
  user_prompt: 'I changed my mind — I prefer beach vacations now.',
  agent_response: 'Got it. I'll update your preferences to beach destinations like Maldives.',
  memory: {
    preference: 'beach vacations'
  }
});

📘 API Reference

new ThreadbaseClient(config)

new ThreadbaseClient({
  apiKey: string;       // required
  baseUrl?: string;     // optional
});

| Option | Type | Required | Description | |------------|----------|----------|---------------------------------| | apiKey | string | ✅ | Your Threadbase API key | | baseUrl | string | ❌ | Override the API base URL |

trace(options): Promise<TraceResponse>

Create a new trace.

Required fields:

• agent_id (string)
• user_id (string)
• session_id (string)
• user_prompt (string)
• agent_response (string)

Optional fields:

• trace_type (string)
• tools_used (string[])
• metadata (Record<string, any>)
• memory (Record<string, any> | null)

getTraceById(id: string): Promise<TraceResponse>

Fetch a trace by its unique ID.

getTracesBySession(sessionId: string, page?: number, limit?: number): Promise<TraceResponse>

Get all traces for a session, with optional pagination.

getMemoryDiff(sessionId: string, fromVersion: number, toVersion: number): Promise<TraceResponse>

Get the difference between two memory versions in a session.

Example:

// Get memory changes between versions 10 and 11
const diff = await client.getMemoryDiff('99949', 10, 11);

Response:

{
    "meta": {
        "statusCode": 200,
        "message": "Success"
    },
    "data": {
        "added": {},
        "removed": {},
        "changed": {
            "implicit": {
                "from": {
                    "user_interest": "hiking"
                },
                "to": {}
            },
            "injected": {
                "from": {},
                "to": {
                    "preference": "beach vacations"
                }
            }
        },
        "final": {
            "implicit": {},
            "injected": {
                "preference": "beach vacations"
            }
        }
    }
}

The response shows:

• added: New memory entries added
• removed: Memory entries removed
• changed: Memory entries that were modified, showing both the old (from) and new (to) values
• final: The final state of the memory after all changes

getMemoriesBySession(sessionId: string): Promise<TraceResponse>

Retrieve all memory payloads associated with a session.

🧠 Example Responses

Example 1: Implicit Memory Usage

{
  "meta": {
    "statusCode": 201,
    "message": "Success"
  },
  "data": {
    "trace": {
      "id": "b47748bf-5b61-47fb-9b9b-c9d22578afbe",
      "llm_summary": "The user asked for a recommendation for next weekend, and the agent suggested Banff National Park based on the user's interest in hiking.",
      "possible_issue": null,
      "memory_injected_used": false,
      "memory_implicit_used": true,
      "memory": [
        {
          "payload": {
            "implicit": {
              "user_interest": "hiking"
            },
            "injected": {}
          },
          "version": 10
        }
      ],
      "agent": {
        "id": "8a219d38-3d88-48b3-969e-adf8ede035e1",
        "name": "chatgpt",
        "model": "4o"
      }
    }
  }
}

Example 2: Explicit Memory Injection

{
  "meta": {
    "statusCode": 201,
    "message": "Success"
  },
  "data": {
    "trace": {
      "id": "ee448b99-55ce-4745-91fb-b5c21e2e0b4d",
      "llm_summary": "The user updated their vacation preference from hiking to beach vacations, which the agent acknowledged and adjusted accordingly.",
      "possible_issue": "The previous memory indicating a user interest in hiking was not addressed or acknowledged, which may lead to confusion if the user has not completely abandoned that interest.",
      "error": null,
      "memory_injected_used": true,
      "memory_implicit_used": false,
      "memory": [
        {
          "payload": {
            "implicit": {},
            "injected": {
              "preference": "beach vacations"
            }
          },
          "version": 11
        }
      ],
      "agent": {
        "id": "8a219d38-3d88-48b3-969e-adf8ede035e1",
        "name": "chatgpt",
        "model": "4o"
      }
    }
  }
}

📄 License

MIT — feel free to use, modify, and contribute!

🤝 Contributing

We welcome issues, feature requests, and pull requests. If you have feedback or ideas, please open an issue or submit a PR.

📫 Support

Need help? Join our community or contact us at [email protected]