@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-filenpm · 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 > 0Works 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.tsJSDoc, 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.