@lore-co/sdk

The customer library for applications and integrations that call Lore programmatically. It provides a typed client for learnings, activity, audited context delivery, observations, and turns.

Install

pnpm add @lore-co/sdk

import { LoreClient } from "@lore-co/sdk";

const lore = new LoreClient({
  baseUrl: process.env.LORE_API_URL!,
  headers: {
    authorization: `Bearer ${process.env.LORE_WORKSPACE_TOKEN!}`,
  },
});

const result = await lore.processTurn({
  connector: "incident-bot",
  eventId: "incident-42:reply-3",
  agent: "incident-bot",
  sessionId: "incident-42",
  previousAssistant: { content: "Restart the service." },
  currentUser: { content: "No, fail over first." },
}, "incident-42:reply-3");

observeEvent calls POST /v1/observations; deliverContext calls audited POST /v1/context/deliveries; and processTurn calls POST /v1/turns and forwards the optional idempotency key. The client also exposes learning inspection and lifecycle methods, activity listing, workspace-token management, and Devin session registration. observe, getContext, and the memory-named methods remain available for compatibility.

searchWorkspace({ query, type?, repo?, agent?, since?, includeOlder?, sort?, limit?, offset? }) searches saved learnings and recorded session messages in the authenticated workspace. Results include matching excerpts, source event links, status, and counts. Search uses indexed text matching and stemming; it does not deliver context or create delivery receipts. Replaced, marked-wrong, and forgotten learnings appear only with includeOlder: "true". Use searchOptions() for repository and agent suggestions. These methods call GET /v1/search and GET /v1/search/options.

Use @lore-co/adapter-generic instead when the customer owns an agent runtime and wants a higher-level prepare/observe bridge. CLI users should install @lore-co/cli globally; they do not need this package.

Context for scanners and tools

Create a repository-scoped token in Connect → Connect a tool, then:

import { connectLore } from "@lore-co/sdk";

const lore = connectLore({ token: process.env.LORE_WORKSPACE_TOKEN! });
const result = await lore.context({ task: "Check authentication for bugs", files: ["src/auth.ts"] });
// Add result.context to your tool's prompt or supported context input.

The token supplies the repository. For self-hosting, pass apiUrl too. connectLore uses a 15-second deadline and HTTPS (HTTP is allowed for local development). Errors throw; a successful empty match has status: "no_matches". The response includes Markdown, structured sources, and omission indicators. Existing LoreClient users can call prepareContext with the same input. See tool connections for HTTP, MCP, scope, and response options.

Image attachments

Attach an image after its observation or paired turn is recorded:

const image = await client.attachEventImage(
  { connector: "my-agent", eventId: "turn-42", sessionId: "session-1", role: "user" },
  new Blob([pngBytes], { type: "image/png" }),
  "screenshot.png",
);

The event ID here is the connector's external event ID. The multipart upload returns metadata; session evidence includes images alongside their event. GET /v1/event-images/:id returns the original bytes and requires workspace authentication. Identical uploads to the same event and role are idempotent. PNG, JPEG, WebP, and GIF are accepted up to 5 MiB and 40 megapixels, with six images per event. Images are separate from learning text and are not sent to extraction.

The SDK and all adapters expose the same attachEventImage operation, including custom agents and Bedrock AgentCore. The connector identifies provenance; it does not select a different storage path. inlineEventImages(parts, role) normalizes embedded Claude, OpenAI-compatible, OpenCode, and MCP image parts before upload. File reads and authenticated remote downloads remain the integration's job.

If you already have a Lore event UUID (for example learning.source.eventId), use client.attachSourceImage(eventId, blob, name, role) and client.listSourceImages(eventId). These use the same workspace checks and storage.

Production guidance

• Requests have a 60-second deadline covering connection setup, headers, and the complete response body. Responses are limited to 8 MiB of received (decompressed) bytes, including error responses. Override with timeoutMs and maxResponseBytes on LoreClient; both must be positive integers.
• Handle LoreTransportError codes timeout and response_too_large separately from API errors. Requests are aborted and response streams cancelled at the limit. The SDK does not automatically retry writes; reuse an idempotency key when explicitly retrying supported operations. A timeout does not prove that the server rolled back the operation.
• Successful responses must match their endpoint schema; an unexpected empty success response is rejected. Error details are redacted before exposure.
• Use an HTTPS API URL and keep workspace tokens in server-side secrets.
• Reuse stable connector, event, and session IDs when retrying requests.
• Handle LoreApiError for non-2xx responses and log its status without exposing credentials.

Node.js 22 or newer is required. See the API and SDK reference for the complete API surface.

Private links

Use lore share learning <id>, lore share session <id> --event <event-id>, or lore share delivery <id> --learning <learning-id> to return an existing workspace link. The anchor flags are optional. Add --json for structured output. IDs come from Lore results, such as lore ask --json.

MCP exposes the read-only share_lore tool with kind, id, and optional eventId or learningId. The SDK offers client.share(...). These resolve the resource using the current credential before returning a link. They do not publish content or grant access; recipients must sign in to the same workspace.

Hosted connections use https://uselore.co. For self-hosting, connect with --dashboard-url https://lore.example.com, set LORE_DASHBOARD_URL for MCP, or pass dashboardUrl to the SDK. The URL must be an HTTP(S) origin.