Codex Overview

Codex: Knowledge Management Platform

Centralized knowledge management and distribution for organizations.

Codex is a knowledge management platform that enables organizations to maintain a single source of truth for documentation, AI tools, and organizational knowledge across all projects.

Core SDK

The Codex Core SDK (@fractary/codex) is a TypeScript library that provides the foundational business logic for the Codex system.

npm install @fractary/codex

Key Features

📚 Metadata Parsing

Extract and validate YAML frontmatter from markdown files with automatic schema validation.

🔍 Pattern Matching

Glob-based pattern matching for intelligent file routing and distribution.

🎯 Smart Routing

Determine which files should sync to which repositories based on metadata rules.

⚙️ Configuration Management

Multi-source configuration with sensible defaults and organization-agnostic design.

🔒 Type-Safe

Full TypeScript support with strict typing and comprehensive error handling.

✅ Well-Tested

Comprehensive unit test coverage ensuring reliability.

Quick Start

import {
  parseMetadata,
  shouldSyncToRepo,
  loadConfig
} from '@fractary/codex'

// 1. Load configuration
const config = loadConfig({
  organizationSlug: 'fractary'
})

// 2. Parse frontmatter from a markdown file
const fileContent = await readFile('docs/api-guide.md', 'utf-8')
const { metadata, content } = parseMetadata(fileContent)

// 3. Determine if file should sync to a target repository
const shouldSync = shouldSyncToRepo({
  filePath: 'docs/api-guide.md',
  fileMetadata: metadata,
  targetRepo: 'api-gateway',
  sourceRepo: 'codex.fractary.com',
  rules: config.rules
})

console.log(`Sync to api-gateway: ${shouldSync}`)

Core Concepts

Metadata-Driven Sync

Codex uses YAML frontmatter in markdown files to control distribution:

---
org: fractary
system: api-gateway
codex_sync_include: ['api-*', 'core-*']
codex_sync_exclude: ['*-test', '*-dev']
visibility: internal
tags: [api, rest]
---

# API Documentation

Pattern Matching

Glob patterns determine which repositories receive which files:

import { matchPattern, matchAnyPattern } from '@fractary/codex'

// Single pattern
matchPattern('api-*', 'api-gateway')  // true
matchPattern('api-*', 'web-app')      // false

// Multiple patterns
matchAnyPattern(['api-*', 'core-*'], 'api-gateway')  // true

Organization-Agnostic

Works for any organization, not just Fractary:

const config = loadConfig({
  organizationSlug: 'acme-corp'
})

Architecture

The Codex SDK is organized into four core modules:

Metadata Parsing - Extract and validate YAML frontmatter
Pattern Matching - Evaluate glob patterns for routing
Routing & Distribution - Determine sync targets
Configuration - Load and resolve configuration

Use Cases

Multi-repo documentation sync - Maintain docs in one place, distribute to many
AI agent context management - Share agent contexts across projects
Company standards distribution - Push standards and playbooks to all repos
Selective knowledge sharing - Control what goes where with patterns

Status

Current Version: 0.1.0 Status: Active Development License: MIT

The SDK is complete and published to npm. Additional tooling and integrations are in development.

Next Steps

fractary-cli - Unified CLI for all Fractary tools
forge-bundle-codex-github-core - GitHub Actions workflows for codex sync
forge-bundle-codex-claude-agents - Claude Code agents for codex management