heart-layer-seed

Seed tooling for ai-heart-layer — extraction modes, prompts, cross-validation, and the HeartSeedBundle → review → import rails.

This package is the candidate-production side of the Heart ecosystem. Core ai-heart-layer is a runtime substrate; heart-layer-seed is the offline tooling that turns source material (writing corpora, LLM-extracted memories, memory-layer knowledge) into reviewable Heart proposal bundles.

Install

npm install heart-layer-seed ai-heart-layer

ai-heart-layer is a peer dependency — install it alongside. Optional: install ai-memory-layer (v4+) to enable the memory-bridge seed mode.

Modes

• seedFromMemory — extract candidates from a pre-serialized memory transcript via an injected LLM provider.
• seedFromCorpus — multi-pass analysis of a writing corpus (per-piece → cross-piece synthesis → invisible heart → channel profiles → tensions).
• seedCombined — cross-validated bundle merging memory and corpus extractions.
• seedFromMemoryBridge — map ai-memory-layer v4 KnowledgeMemory items to Heart candidates through the knowledge-class mapper registry. Factual classes (project_fact, episodic_fact, procedure, strategy) produce ZERO candidates per the "factual memory never becomes Heart" doctrine.

Failure taxonomy

Seed output distinguishes three cases so operators do not confuse provider failures with genuine absence of Heart signals:

• Recoverable warnings — partial extraction failures that still leave enough successful evidence to continue. Example: one corpus piece fails in Pass 1, but at least three pieces analyze successfully.
• Fatal precondition/provider failures — unreliable extraction states throw and the CLI exits non-zero. Examples: fewer than three corpus pieces, all Pass 1 calls fail, or Pass 1 failures leave fewer than three successful analyses.
• Genuine empty extraction — analysis completed on enough source material but found no signals. This returns a valid empty bundle with a warning such as "No signals extracted from any piece in pass 1".

Review pipeline

Every mode produces a HeartSeedBundle with status: 'pending' candidates. The pipeline is:

extract → reviewSeedBundle (operator decisions) → buildExportBundle → heart.importBundle

No mode writes accepted candidates directly — review is inviolable.

CLI

npx heart-layer-seed --help

Authentication

Provide your LLM provider key through the environment — this is the only recommended path:

• ANTHROPIC_API_KEY for the claude provider (default)
• OPENAI_API_KEY for the openai provider

export ANTHROPIC_API_KEY=sk-ant-...
npx heart-layer-seed corpus --files essay.md --export-output out/bundle.json --audit-output out/audit.json

The --api-key <key> flag still works but is deprecated: keys passed on the command line leak into shell history and process listings (ps). It emits a warning to stderr; prefer the environment variables above.

Architecture

• src/modes/ — one orchestrator per mode
• src/prompts/ — LLM extraction prompts (opt-in per mode)
• src/mappers/ — knowledge-class mapper registry (memory_bridge mode)
• src/cross-validation/ — corpus↔memory signal merging for seedCombined
• src/review.ts — decision application; produces a reviewed bundle
• src/bundle-builder.ts — converts a reviewed bundle into a HeartExportBundle
• src/validation.ts — validateBundle schema guard mirroring core importBundle preflight

License

MIT