@getbourdon/participants

The external-agent → L5 reader layer of Bourdon (BUSL-1.1).

A participant normalizes a foreign agent's native memory store into a visibility-filtered, redacted L5 manifest. It is the bridge between an agent's private, vendor-specific state and the cross-machine federation library.

Python (pip install bourdon) is the oracle; this TS mirror asserts against the @getbourdon/conformance native_stores fixtures (output shape only).

Reader examples

| Reader | Category | Native store | |---|---|---| | HermesParticipant | SQLite (read-only) | ~/.hermes/ — state.db sessions + memories/*.md | | ClaudeCodeParticipant | file / convention | ~/agent-brain/ + ~/.claude/projects/*/memory/ + KG JSONL | | GitHubCopilotParticipant | network (TTL cache) | api.github.com PR activity → ~/.cache/bourdon/github-copilot/ | | CursorParticipant | SQLite | Cursor state.vscdb workspace state | | CopilotCliParticipant | SQLite | ~/.copilot/session-store.db | | OpenClawParticipant | local HTTP API | OpenClaw's local instance |

These are examples; FIRST_PARTY in src/registry.ts is the current reader roster. The full Codex turn-compiler reader is deferred. The Codex automation reader and session-index title lookup are narrower integrations already present.

ClaudeCodeParticipant resolves its knowledge repo in this order: the AGENT_BRAIN env var, then $HOME/agent-brain/, then ./agent-brain/. No other folder name is ever scanned.

The four invariants (enforced in code, not by trust)

1. Visibility filter BEFORE emission — every entity passes filterForFederation; private_tags always win. A PRIVATE entity never lands in a manifest.
2. Deterministic / idempotent exportL5 — same store → byte-identical toDict (L6 hashes it for change detection).
3. healthCheck NEVER throws — a diagnostic must never crash bourdon doctor.
4. Every native string through @getbourdon/redaction before it enters L5.

Usage

import { discoverParticipants, toDict } from "@getbourdon/participants";

for (const p of discoverParticipants()) {
  const health = p.healthCheck(); // never throws
  if (health.status === "blocked") continue;
  const manifest = p.exportL5(); // visibility-filtered, redacted, deterministic
  console.log(p.agentId, toDict(manifest));
}

Discovery is a static registry (FIRST_PARTY), not a filesystem package scan — it preserves the Python oracle's agentId-sorted output, first-wins dedupe, and log-and-skip-on-construction-failure resilience. Third-party plugins are gated behind BOURDON_PLUGINS=1 (a no-op stub today).

Native addon note

The SQLite readers use better-sqlite3, a native addon. It is loaded lazily: if the addon fails to build on a given toolchain, sqliteAvailable() returns false, the SQLite readers degrade gracefully, and the rest of the package (file + network readers) keeps working. The SQLite-reader parity tests are gated on sqliteAvailable().

License

BUSL-1.1 — see LICENSE and LICENSE_FAQ.md.