@loredotlink/sdk

Upload agent sessions to Lore from your own apps, plugins, and tools.

If you build on top of coding agents — a Claude Code plugin, an internal dev tool, a product that embeds an agent — this SDK lets you capture the resulting sessions in your Lore workspace, tagged with your own metadata (customer id, deployment, device, …) so you can debug and filter them later.

Installation

npm install @loredotlink/sdk

Requires Node.js 20 or later. The SDK reads session transcripts from the local machine, so it must run where the agent ran (for Claude Code: wherever ~/.claude/projects lives) — for example inside a Claude Code hook.

Authentication

The SDK authenticates with an Upload API key (lore_uak_...). Create one in Lore under Account Settings → Upload API keys. Keys are scoped to your workspace: sessions uploaded with your key are attributed to you and visible to your workspace, regardless of which machine or end user ran the upload.

Treat the raw key as a secret — inject it via an environment variable or your own config; don't hard-code it in distributed source.

Usage

import Lore from '@loredotlink/sdk';

const uploadClient = new Lore.Upload(process.env.LORE_UPLOAD_API_KEY, {
  // Optional; defaults to api.lore.link. Accepts a bare hostname (https
  // assumed) or a full origin such as http://127.0.0.1:4000 for local testing.
  apiHostname: 'api.lore.link',
});

const result = await uploadClient.uploadSessionSnapshot(
  'claude_code',          // harness — only 'claude_code' is implemented today
  sessionId,              // the Claude Code session id
  {
    metadata: {
      customer_id: 'cus_123',
      deployment: 'prod-eu',
    },
  },
);

console.log(result.threadId); // Lore thread id, e.g. th_...
console.log(result.reused);   // true if Lore already had this exact snapshot

uploadSessionSnapshot resolves the session's transcript on disk, snapshots it, uploads it to Lore, and waits until Lore has finished parsing it into a thread. When the returned promise resolves, the thread is ready.

Example: upload from a Claude Code Stop hook

A common integration is a plugin that uploads a session when it ends:

// stopHook.ts — runs on Claude Code's Stop hook
import Lore from '@loredotlink/sdk';

const input = JSON.parse(await readStdin()); // Claude Code passes { session_id, ... }

const uploadClient = new Lore.Upload(process.env.LORE_UPLOAD_API_KEY);
await uploadClient.uploadSessionSnapshot('claude_code', input.session_id, {
  metadata: { customer_id: getCustomerId() },
});

API

new Lore.Upload(uploadApiKey, options?)

| Parameter | Type | Description | | --- | --- | --- | | uploadApiKey | string | Your Upload API key (lore_uak_...). Required. | | options.apiHostname | string | Lore API hostname or origin. Defaults to api.lore.link. |

upload.uploadSessionSnapshot(harness, sessionID, options?)

| Parameter | Type | Description | | --- | --- | --- | | harness | 'claude_code' \| 'codex' \| 'cursor' | Which agent produced the session. Only claude_code is implemented; the others reject with a not-implemented error. | | sessionID | string | The harness's session id. For Claude Code this is the id your hook receives as session_id. | | options.metadata | Record<string, string> | Caller-owned key/value tags stored on the uploaded session and resulting thread. Up to 20 keys; keys are 1–64 chars of letters, digits, _ . : -; values up to 512 chars; 4 KB total. |

Returns Promise<{ threadId: string; reused: boolean }>. reused is true when Lore deduplicated the upload against an identical existing snapshot.

Throws if the session can't be found on disk, the API key is invalid or revoked, the upload fails, or parsing fails.

What gets uploaded

• The SDK includes a client-side scrubber: transcripts are scanned locally before upload, detected secrets are redacted, and a transcript the scrubber can't safely release is held on the local machine and not uploaded (the call rejects with a quarantine error).
• Uploads are snapshots — re-uploading the same session after it grows creates/updates the same Lore thread (deduplicated by content and session id).
• Threads uploaded with an Upload API key use the key's workspace visibility and carry the key's attribution, so the key owner can filter threads by key and by metadata.