@memofs/connectors API

API reference for @memofs/connectors: ingestion pipelines, connector registry, deterministic note ID generation, and third-party sources.

The @memofs/connectors package manages ingestion pipelines from external sources (GitHub, Notion, and custom connectors) into MemoFS memory.

Orchestrates loading .memofs/connectors.json, resolving credentials through SecretResolver, executing enabled ingestion connectors, deduplicating records against existing event logs, and committing notes to MemoFS memory.

function runConnectors(options: RunConnectorsOptions): Promise<RunConnectorsResult>;

`createConnectorRegistry`

Creates a new ConnectorRegistry seeded with the built-in connectors (GitHubConnector and NotionConnector), plus any optional extra connectors.

function createConnectorRegistry(extras?: readonly Connector[]): ConnectorRegistry;

`connectorNoteId`

Computes the deterministic conn_<16 hex chars> note ID for a ConnectorRecord using sha256(externalId + ":" + content).slice(0, 16). Pure computation with zero wall-clock dependency.

function connectorNoteId(record: ConnectorRecord): Promise<string>;

`readConnectorsFile`

Reads and validates .memofs/connectors.json for a given project root. A missing file degrades gracefully to EMPTY_CONNECTORS_FILE ({ connectors: [] }) rather than throwing. Malformed files or files violating secret guardrails throw ConnectorConfigError.

function readConnectorsFile(rootDir: string): Promise<ConnectorsFile>;

`validateConnectorsFile`

Runs structural and secret-leak validation against a parsed connectors.json JSON payload. Rejects forbidden token keys, recursive substring matches, and credential pattern matches.

function validateConnectorsFile(raw: unknown): ConnectorsFile;

`selectConnectors`

Filters a ConnectorsFile by enabled state and/or connector type.

function selectConnectors(
  file: ConnectorsFile,
  opts?: { enabled?: boolean; type?: string }
): ConnectorConfig[];

Classes

`ConnectorRegistry`

Mutable registry mapping a connector type identifier to a Connector implementation instance.

class ConnectorRegistry {
  constructor(builtins?: readonly Connector[]);
  register(connector: Connector): this;
  get(type: string): Connector | undefined;
  has(type: string): boolean;
  types(): readonly string[];
}

`GitHubConnector`

Built-in connector for GitHub issues, pull requests, and discussions (type: "github"). Implements Connector.

class GitHubConnector implements Connector {
  readonly type = "github";
  readonly displayName = "GitHub";
  ingest(ctx: ConnectorIngestContext): Promise<readonly ConnectorRecord[]>;
}

`NotionConnector`

Built-in connector for Notion database rows and workspace search pages (type: "notion"). Implements Connector.

class NotionConnector implements Connector {
  readonly type = "notion";
  readonly displayName = "Notion";
  ingest(ctx: ConnectorIngestContext): Promise<readonly ConnectorRecord[]>;
}

`EnvSecretResolver`

Dev/local fallback resolver. Reads { "secretRef": "token" } maps from .memofs/secrets.json on disk (cached in memory). Implements SecretResolver.

class EnvSecretResolver implements SecretResolver {
  constructor(options: FileSecretResolverOptions);
  resolve(secretRef: string): Promise<string>;
}

`StaticSecretResolver`

In-memory secret resolver for tests and programmatic embedding. Implements SecretResolver.

class StaticSecretResolver implements SecretResolver {
  constructor(entries: Record<string, string>);
  resolve(secretRef: string): Promise<string>;
}

`CloudSecretResolver`

Production secret resolver that calls the MemoFS Cloud API endpoint GET {cloudBaseUrl}/projects/:projectId/connectors/secret?ref=:secretRef. Implements SecretResolver.

class CloudSecretResolver implements SecretResolver {
  constructor(options: CloudSecretResolverOptions);
  resolve(secretRef: string): Promise<string>;
}

Interfaces & Types

`SecretResolver`

Credential plane contract. Implementations resolve an opaque secretRef to a live plaintext token in memory.

interface SecretResolver {
  resolve(secretRef: string): Promise<string>;
}

`Connector`

Provider-neutral plugin interface for data sources.

interface Connector {
  readonly type: string;
  readonly displayName: string;
  ingest(ctx: ConnectorIngestContext): Promise<readonly ConnectorRecord[]>;
}

`ConnectorConfig`

Single connector instance row stored in .memofs/connectors.json.

interface ConnectorConfig {
  readonly id: string;
  readonly type: string;
  readonly enabled: boolean;
  readonly schedule?: string;
  readonly sourceMapping?: JsonObject;
  readonly secretRef: string;
}

`ConnectorsFile`

The parsed on-disk shape of .memofs/connectors.json (the 11th canonical sync unit).

interface ConnectorsFile {
  readonly connectors: readonly ConnectorConfig[];
}

`ConnectorRecord`

A normalized external item produced by Connector.ingest().

interface ConnectorRecord {
  readonly externalId: string;
  readonly title: string;
  readonly content: string;
  readonly url?: string;
  readonly occurredAt?: string;
  readonly metadata?: JsonObject;
}

`ConnectorIngestContext`

Runtime context passed into Connector.ingest().

interface ConnectorIngestContext {
  readonly config: ConnectorConfig;
  readonly token: string;
  readonly memo: MemoFS;
  readonly signal?: AbortSignal;
}

`RunConnectorsOptions`

Configuration options passed to runConnectors().

interface RunConnectorsOptions {
  readonly rootDir: string;
  readonly memo: MemoFS;
  readonly secretResolver: SecretResolver;
  readonly connectorRegistry?: ConnectorRegistry;
  readonly onlyType?: string;
  readonly signal?: AbortSignal;
}

`RunConnectorsResult`

Aggregated result returned by runConnectors().

interface RunConnectorsResult {
  readonly written: readonly string[];
  readonly skipped: readonly string[];
  readonly errors: readonly ConnectorIngestError[];
  readonly ran: readonly string[];
}

`ConnectorIngestResult`

Result of a single connector pass before aggregation.

interface ConnectorIngestResult {
  readonly written: readonly string[];
  readonly skipped: readonly string[];
  readonly errors: readonly ConnectorIngestError[];
}

`ConnectorIngestError`

A recoverable error encountered during a connector pass.

interface ConnectorIngestError {
  readonly connectorType: string;
  readonly message: string;
  readonly externalId?: string;
  readonly cause?: unknown;
}

`FileSecretResolverOptions`

Constructor options for file-backed secret resolvers (EnvSecretResolver).

interface FileSecretResolverOptions {
  readonly rootDir: string;
}

`CloudSecretResolverOptions`

Constructor options for CloudSecretResolver.

interface CloudSecretResolverOptions {
  readonly projectId: string;
  readonly apiKey: string;
  readonly cloudBaseUrl: string;
}

Error Classes

All connector errors inherit from ConnectorError and provide a stable .code string:

class ConnectorError extends Error {
  readonly code: string;
  constructor(code: string, message: string, options?: { cause?: unknown });
}

Class	Base	`.code`	Properties	Thrown When
`ConnectorConfigError`	`ConnectorError`	`"CONNECTOR_CONFIG_ERROR"`	—	`.memofs/connectors.json` is missing required structure, contains malformed rows, or violates token guardrails.
`ConnectorSecretError`	`ConnectorError`	`"CONNECTOR_SECRET_ERROR"`	`readonly secretRef: string`	A `SecretResolver` fails to resolve a `secretRef`.

Constants

`EMPTY_CONNECTORS_FILE`

A frozen { connectors: [] } default returned when .memofs/connectors.json is absent.

const EMPTY_CONNECTORS_FILE: ConnectorsFile;