@nomark-ai/engine

@nomark-ai/engine

The open-core preference resolution engine for AI agents. Learns what humans mean from incomplete input by building a persistent ledger of preferences, meaning maps, and defaults across sessions and platforms.

Install

npm install @nomark-ai/engine

Requires Node.js 18+.

Quick Start

import { createResolver, parseLedger } from '@nomark-ai/engine'

// Parse a NOMARK ledger (JSONL format)
const entries = parseLedger(ledgerContent)

// Create a resolver scoped to a context
const resolver = createResolver({ entries, context: 'code' })

// Resolve all preference dimensions
const result = resolver.resolveAll()

for (const [dim, res] of Object.entries(result.dimensions)) {
  if (res.winner) {
    console.log(`${dim}: ${res.winner.target} (score: ${res.winner._score})`)
  }
}

// Resolve intent from natural language
const input = resolver.resolveInput('make it shorter')
for (const match of input.meaningMaps) {
  console.log(`${match.trigger} -> ${match.intent.join(', ')}`)
}

Modules

Schema

Zod-validated types for all five signal types: pref, map, asn, meta, rub. Enforces ISO dates, valid ranges, and structural correctness at parse time.

Ledger

JSONL parser and writer with per-type capacity constraints. Handles [sig:type] {json} line format with built-in token estimation.

Classifier

Classifies raw user input into tiers: pass-through (no extraction needed), routing (intent only), or extraction (structured preference signals).

Resolver

The core scoring engine. Evaluates preferences using five weighted factors:

• Specificity (0.30) — compound scope > single scope > global
• Evidence (0.25) — signal count normalized to 20
• Recency (0.20) — linear decay over 180 days
• Stability (0.15) — contradiction ratio penalty
• Portability (0.10) — cross-context usage

Unstable dimensions (winner score < 0.4) are flagged with action: 'ask'.

Decay

Time-based weight decay with contradiction acceleration. Preferences that are frequently contradicted decay faster.

Utility

Multi-factor utility scoring for capacity-bounded pruning. When the ledger approaches capacity limits, low-utility entries are pruned first.

Importers

Migrate conversation history from other platforms:

import { parseChatGPTExport, parseClaudeExport, extractSignals, runMigration } from '@nomark-ai/engine'

const conversations = parseChatGPTExport(chatgptJson)
const signals = extractSignals(conversations)
const report = runMigration(signals, existingLedger)

Supported platforms: ChatGPT, Claude.

Sync

Cross-device synchronization with Supabase (optional peer dependency):

import { createSyncClient, OfflineQueue } from '@nomark-ai/engine'

const sync = createSyncClient({
  supabaseUrl: process.env.SUPABASE_URL,
  supabaseKey: process.env.SUPABASE_ANON_KEY,
})

await sync.push(entries)
const remote = await sync.pull()

Includes offline queue, conflict resolution, privacy filtering, and merge strategies.

CLI

npx nomark profile         # Show resolved preference profile
npx nomark import           # Import from ChatGPT/Claude exports
npx nomark review           # Review and manage ledger entries

API Reference

Core

Export	Description
createResolver(config)	Create a resolver instance
parseLedger(content)	Parse JSONL ledger content
writeLedger(entries)	Serialize entries to JSONL
classify(input)	Classify input tier
computeDecay(weight, decay)	Compute decayed weight
utilityScore(entry)	Score entry utility
pruneToCapacity(entries)	Prune entries within capacity

Types

Type	Description
ResolverConfig	Resolver configuration (entries, context, topic)
ResolverResult	Full resolution output (dimensions, meaning maps, defaults)
DimensionResult	Single dimension resolution with winner/runner-up
LedgerEntry	Union of all signal entry types
SigPref / SigMap / SigAsn / SigMeta / SigRub	Individual signal types

License

Apache 2.0