Building a Source Adapter

You can connect anything to Trove by building a source adapter — a small project (manifest.json + index.ts) that fetches content from an upstream and pushes it into your knowledge base. Trove stores, indexes, and searches what you send; it never reaches out to the upstream itself, so credentials and scheduling stay entirely on your side (the Trove Mac app).

This guide has moved

The full source-adapter documentation now lives in the Sources series. This page is a short pointer kept in place so existing links don’t break.

Start here

• Sources Overview — what a source is, the collect-vs-serve framing, and the two-file model.
• Quickstart — build your first source adapter in about 10 minutes with a real public feed.
• SDK Reference — the @ontrove/sdk API: TroveSource, sync(ctx), the ctx object, the document shape, and audio transcription.
• manifest.json Reference — every manifest field, with examples.
• Cursors and Feeds — multi-feed sources, watermark types, and the cursor compare-and-swap protocol.

The contract, in one breath

Your sync(ctx) returns an array of documents. Each has a stable id, some text (or an audioUrl for transcription), and optional title, url, author, and date. Trove deduplicates by id, tracks a per-feed cursor, embeds and indexes the text, and serves it to Claude.

index.ts

import type { TroveSource } from "@ontrove/sdk";

export default {
  async sync(ctx) {
    const res = await ctx.fetch(ctx.config.feedUrl as string);
    return parseFeed(await res.text()).map((item) => ({
      id: item.guid,
      title: item.title,
      text: item.body,
      url: item.link,
      author: item.author,
      date: item.published,
    }));
  },
} satisfies TroveSource;

If you want to push documents directly over the wire (from your own client, not the Mac app), see the Sync API and the ingestDocuments mutation that source adapters map onto.