@equationalapplications/core-okf

Overview

A zero-dependency library for parsing and producing Open Knowledge Format (OKF) v0.1 and v0.2 bundles. This package provides the raw primitives to work with OKF frontmatter, concept documents, and index/log files, completely decoupled from any specific database or data model.

For a ready-made MemoryDump ⇄ OKF bundle adapter, see the OKF guide for @equationalapplications/core-llm-wiki.

For the llm-wiki interoperability profiles (llm-wiki/1 and llm-wiki/2), see docs/okf-profile.md. Conformance fixtures live in fixtures/.

GraphRAG compatibility: core-okf is database-agnostic. The adapter that can populate llm_wiki_edges for traverseGraph() lives in @equationalapplications/core-llm-wiki. See GraphRAG guide.

Installation

npm install @equationalapplications/core-okf

API Reference

serializeFrontmatter / parseFrontmatter

Produces and parses YAML frontmatter for OKF concept documents.

const yaml = serializeFrontmatter({ type: 'fact', id: 'fact_123' });
const { frontmatter, rest } = parseFrontmatter(fileContent);

buildConceptDocument / parseConcept

Combines frontmatter and markdown body into a single string, or splits an existing OKF file into its component parts.

const markdown = buildConceptDocument({ type: 'task', id: 'task_1' }, '# Buy groceries');
const { frontmatter, body } = parseConcept(markdown);

buildIndexMd / buildRootIndexMd

Generates directory index lists or root OKF catalog manifests.

const sections = [{ heading: 'Facts', entries: [{ path: 'facts/fact_123.md', title: 'Fact 123' }] }];
const dirIndex = buildIndexMd(sections);
const rootIndex = buildRootIndexMd('0.1', sections);

buildLogMd / parseLogMd

Serializes chronological append-only events or parses them back into discrete entries.

const log = buildLogMd([{ date: '2026-06-23', text: 'Observation made' }]);
const events = parseLogMd(logContent);

deriveEventId

Computes the deterministic id an OKF consumer gives a log.md line that has no <!-- id: … --> comment (profile §7). The same line in the same entity always gets the same id, so importing the log again skips it while the earlier copy is stored.

const id = deriveEventId({
  entityId: 'demo',
  date: '2026-07-05',        // the heading text
  eventType: 'observation',
  summary: 'Linked to alpha',
  occurrence: 0,             // earlier id-less lines with the same date, type and summary
});
// 'evt_okf1_02dd42bf329719f258ab93b373f44506'

createEventIdDeriver({ entityId, date, eventType, summary }) returns (occurrence) => id with the same results, hashing the summary only once. Use it when you need many occurrences of one line.

extractMarkdownLinks

Parses relative markdown cross-links to map knowledge graph edges.

const links = extractMarkdownLinks('See [preferences](facts/fact_abc.md) for more.');
// links: [{ text: 'preferences', path: 'facts/fact_abc.md' }]

Monorepo Ecosystem

OKF v0.2 conformance

This package conforms to OKF v0.2. New helpers for v0.2:

• deriveTrustTier(verified) — derive 'unverified' | 'machine-confirmed' | 'human-reviewed'.
• isStaleAfter(staleAfter, now) — staleness check against an absolute YYYY-MM-DD cutoff.
• parseVerifiedFlexible(value) — accept either an array or a bare { by, at } mapping.
• extractFootnotes(body) / serializeFootnotes(footnotes) — preserve footnote attribution verbatim.
• parseFlowMapping(text) / parseFlowSequence(text) — flow parsing with at most one level of mapping-value nesting (no anchors/aliases outside quoted strings).

The serializeFrontmatter function emits plain objects as flow mappings and actor strings (containing / or :) via serializeActorString. Anchor/alias expansion is rejected; only unquoted & or * characters are treated as opaque (quoted spans are excluded from the scan, so URL query strings like "https://x/a?p=1&q=2" remain valid).