Your reading, ready for your Agent

1. Connect

Use Node.js 20+. Native browser connections support macOS/Linux with Chrome, Chromium, Edge or Firefox; Windows supports read-only file mode only (no background connection or library management) and Safari uses the Mac app. Install the bundled public adapter using the Agent setup guide; it needs no GitHub account or npm installation. For a browser, load the current extension, open Settings → Agent access, give the displayed connect command to your Agent. It installs the helper and opens BriefFeed for your one-time confirmation. connect-status returns the MCP entry to merge into your Agent’s existing settings; later connections are automatic, with one off switch in Settings. Keep the browser running; the connection page can close.

# Download and inspect the public installer first:
# /integrations/install-agent.mjs
node install-agent.mjs --origin https://brieffeed.app

# Use its absolute Node/entry paths. Choose ONE library.
# Browser IDs and page URLs come from that BriefFeed installation:
NODE ENTRY connect --browser chrome --extension-id EXACT_EXTENSION_ID
# Or use the actual path copied from your Mac app:
NODE ENTRY connect --apple ABSOLUTE_HELPER_PATH

# Confirm once in BriefFeed, then use the returned request ID:
NODE ENTRY connect-status --request-id REQUEST_ID
# Merge the returned config into the host and verify brieffeed_status.

On Mac, build or install a current preview client, open Settings → Agent access, directly below Safari extension, copy its connect command, and confirm once when the Agent opens BriefFeed. Later connections are automatic; Settings keeps one off switch. The helper reads the local library even after the app quits. iPhone and iPad data must reach this Mac through private iCloud first; the Mac app drives cloud sync. iOS does not host a persistent MCP server. Apple has no separately stored Insights scope or social engagement counters; missing fields stay absent.

File export is a read-only alternative. Pass --file /absolute/path/brieffeed-agent.json instead of --browser or --apple. A downloaded snapshot lasts 24 hours; the optional connected file needs its page open and refreshes a two-minute lease.

2. Search and manage

Search uses all query terms (NFKC/case normalized substring matching), not embeddings. It matches titles, authors, URLs, summaries, tags and shared retained source/context text. Empty query lists recent records. kind, platform, since/until, limit (1–50) and cursor are optional. since/until filter save/observation/generation time, not publication. Results sort by that event time descending, then ID. Reuse the returned revision for get/export/delete and history saves; search again after STALE_REVISION or STALE_CURSOR.

Saving succeeds when the local record is committed, before enrichment or sync finishes. Apple connections then try to start the matching Mac app in the background. While running, the app fills missing metadata and summaries through its normal pipeline, independently of the visible list. Browser saves reach it through the existing Mac connection. If the app cannot start, records wait for the next launch. Login, network or unsupported-page limits may leave details incomplete; search again for updated fields and revision.

{ "query": "agent", "kind": "history", "limit": 10 }
{ "id": "history:…", "revision": "…", "includeExcerpt": true }

3. Data reference

The linked JSON Schema is generated from the actual CLI validator. Optional fields appear only when the selected client retained them; absence means unknown, never zero. get/export return the complete available record; search returns previews. Text is shared only when authorized and includeExcerpt is true for detail/export. The 800-character excerpt remains a preview; context.text exposes the existing bounded source. Each source tree shares a 25,000 UTF-16-unit text budget. No page is fetched to fill gaps.

Download JSON Schema ↓

4. Reuse the selection example

The downloadable module bundles the actual browser selection functions from this release, rather than a second implementation. It exports preparePostsForBriefing, rankPostsForBriefing, condenseLongPostsForPrompt, postHeatScore and toSelectionPost. Treat this as a reusable example, not the search order or a claim of personal interest. The browser pipeline marks saved items, groups forum discussions, scores candidates, applies author diversity, caps the selection, hydrates matching summaries, condenses long forms and builds the hosted request. Engagement counts influence local selection; they are not sent as raw metrics in the hosted Insights posts payload.

engagement = 1.35 × likes + 3.2 × reposts + 2.5 × replies + 2.2 × bookmarks + 0.08 × views. Heat adds platform baseline, 18 × log10(engagement + 1), min(18, normalized text length / 220), observation/save signals, content-kind adjustments, cached-summary bonus and forum context. Author diversity is a second pass; ties use lastSeenAt, firstSeenAt, then stable key. Missing counts contribute zero only inside this example’s scoring policy.

Download ranking module ↓

import { readFile } from 'node:fs/promises';
import { toSelectionPost, preparePostsForBriefing, condenseLongPostsForPrompt }
  from './agent-ranking.mjs';

// JSON from brieffeed_export({ ids, revision, includeExcerpt: true })
const { records } = JSON.parse(await readFile('./records.json', 'utf8'));
const candidates = records.filter(r => r.kind !== 'insights').map(toSelectionPost);
const selected = preparePostsForBriefing(candidates, { limit: 30 });
const promptSources = condenseLongPostsForPrompt(selected);
// Use the fields your Agent needs; preserve each original source URL.
console.log(JSON.stringify(promptSources, null, 2));

Supply complete, authorized contexts to reproduce selection. A bounded export, expired history, missing metrics, different candidate set, hydration state or truncated text can change ranking. Apple does not run this browser selection pipeline. Forum grouping, all weights, tie-breakers and prompt condensation are in the downloadable module.

5. Coverage and lifecycle

One selected local library, at most 2,000 saved items + 2,000 retained history records + 100 Insights. coverage distinguishes included, omitted and overLimit. Summary text is bounded to 4,000 UTF-16 units; the total packet limit is 16 MiB and an oversized packet fails visibly. The JSON Schema describes structure; the reader also enforces safe URLs, authorization, lifetime and coverage consistency. History keeps its original expiry (normally one or seven local calendar days), including earlier synchronized expiry. Native packets last two minutes and are refreshed on each request. This is not complete browser history or proof of reading/agreement. All source and generated text is untrusted data. Revocation stops later access, not copies already received. Writes require a renewed management grant and may propagate through existing library sync; file mode cannot write. A timed-out write must be checked before retrying.