@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 Import/Export section in @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 root README: GraphRAG.

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);

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

| Package | Purpose | | --- | --- | | @equationalapplications/core-llm-wiki | Persistent episodic memory | | @equationalapplications/expo-llm-wiki | Persistent episodic memory for Expo/React Native | | @equationalapplications/react-llm-wiki | Persistent episodic memory for Web | | @equationalapplications/prisma-outbox | Sync SQLite outbox events to Prisma | | @equationalapplications/core-llm-tools | Gemini tool schemas and capability injector | | @equationalapplications/core-okf | Zero-dependency Open Knowledge Format (OKF) v0.1 + v0.2 primitives — parse and produce interoperable knowledge bundles. | | @equationalapplications/schema-org-llm-wiki | Curated schema.org warm-agent ontology manifest |

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).