@molecule/api-paracrine-file

Provider bond · paracrine · API (Node) · v1.3.1 · Apache-2.0

Zero-config file-backed paracrine store — messages between the AI agents on one machine in one directory (PARACRINE_DIR or ~/.agents/paracrine), with a paracrine CLI any harness can use.

npm install @molecule/api-paracrine-file

npm · Source on GitHub · Implements @molecule/api-paracrine

How it works

@molecule/api-paracrine-file is a provider bond on the API (Node) side: it implements the paracrine core interface (@molecule/api-paracrine) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { setProvider, requireProvider } from '@molecule/api-paracrine'
import { createProvider } from '@molecule/api-paracrine-file'

setProvider(createProvider()) // ~/.agents/paracrine
const asked = await requireProvider().send({
  from: 'claude-code-1',
  to: 'codex-2',
  subject: 'images',
  body: 'May I delete the archived benchmark images?',
})
// …the other side, in any harness:
//   paracrine recv --for codex-2 --unread
//   paracrine ack --for codex-2 <id>
const seen = (await requireProvider().reads(asked.id)).length > 0

Works with: @molecule/api-paracrine

Reference

File-backed paracrine store — messages between the AI agents on one machine.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setProvider, requireProvider } from '@molecule/api-paracrine'
import { createProvider } from '@molecule/api-paracrine-file'

setProvider(createProvider()) // ~/.agents/paracrine
const asked = await requireProvider().send({
  from: 'claude-code-1',
  to: 'codex-2',
  subject: 'images',
  body: 'May I delete the archived benchmark images?',
})
// …the other side, in any harness:
//   paracrine recv --for codex-2 --unread
//   paracrine ack --for codex-2 <id>
const seen = (await requireProvider().reads(asked.id)).length > 0

Type

provider

Installation

npm install @molecule/api-paracrine-file @molecule/api-paracrine

API

Interfaces

ParacrineFileConfig

Configuration for the file store.

interface ParacrineFileConfig {
  /** The root directory; defaults to `PARACRINE_DIR` or `~/.agents/paracrine`. */
  rootDir?: string
}

Functions

runCli(argv, config)

Run the CLI. Exports for tests; bin/paracrine.mjs calls this with process.argv.slice(2).

function runCli(argv: string[], config?: ParacrineFileConfig): Promise<string[]>
  • argv — The arguments after the command name.
  • config — Store configuration override (tests).

Returns: The lines to print.

createProvider(config?)

Create the transactional paracrine store.

function createProvider(config?: ParacrineFileConfig): ParacrineFileProvider

Core Interface

Implements @molecule/api-paracrine interface.

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-paracrine ^1.0.0

Runtime Dependencies

  • @molecule/api-paracrine

Zero config, zero daemon. One private SQLite database in ~/.agents/paracrine (or PARACRINE_DIR) holds messages, per-recipient delivery state, and receipts. WAL transactions make sends, bounded claims, acknowledgements, and retries atomic across bonded processes and the CLI.

Bonds as the paracrine singleton. setProvider(createProvider()) at startup; requireProvider() from @molecule/api-paracrine everywhere else. Explicit rootDir config when a test or a platform wants an isolated store. On the first open, an existing plain-file store is imported in one SQLite transaction and left untouched. Every provider call therefore sees the complete imported state. Transient I/O failures and JSON modified within the last minute fail that open for retry; older malformed JSON is preserved under legacy-unreadable/ and listed by status() or paracrine status.

Interoperability is the point. A harness with no bond support participates through the CLI (npx @molecule/api-paracrine-file -- … via the paracrine bin). Tool-boundary callers can claim pending deliveries, emit them, acknowledge successful claims, or release them for immediate retry. A claim lease permits recovery after a killed process.