Open Knowledge Catalog (OKC)

A local-first tool that allows AI agents to safely browse, parse, search, and reason over an Open Knowledge Format (OKF) repository — via CLI, MCP server, or filesystem watcher.

Overview

The Open Knowledge Catalog transforms a filesystem-based collection of Markdown documents with YAML front matter into a structured, searchable knowledge base that AI agents can query through a small set of deterministic operations.

Why This Tool?

OKF gives knowledge a portable, human-readable representation, but it doesn't provide fast retrieval, structured querying, validation, or an AI tool interface. Without a dedicated tool, an AI agent would need to:

• Recursively inspect the filesystem
• Open many files individually
• Repeatedly parse front matter
• Search raw Markdown text
• Resolve relative links
• Infer directory structure
• Manage its own context limits

This tool moves those responsibilities into deterministic software, giving the AI a controlled view:

OKF files → scanner & parser → structured index → bounded AI tool calls → relevant source context → AI answer

Benefits

• Performance: Repository parsed once, updated incrementally; unchanged files skipped
• Accuracy: YAML metadata queried as structured data, not plain text search
• Context Efficiency: AI receives only relevant metadata, headings, excerpts, or sections
• Navigability: Directory hierarchy supports progressive disclosure; document graph supports link-following
• Safety: Restricts accessible directories, file types, sizes, traversal depth, output size
• Source Traceability: Every result includes repository path and source location

Features

OKC provides a comprehensive set of tools for browsing, parsing, searching, and reasoning over OKF repositories. See docs/features.md for the full feature reference.

Quick Reference

Installation

From crates.io (recommended)

cargo install okc

From GitHub Releases

Download the pre-built binary for your platform from the latest release:

Build from source

git clone https://github.com/guifelix/Open-Knowledge-Catalog
cd open-knowledge-catalog
cargo build --release
# Binary at target/release/okc

Quick Start

# Create a knowledge repository
mkdir -p my-knowledge/{metrics,datasets}

# Scan and index it
okc scan --root my-knowledge

# Browse the hierarchy
okc browse

# Search
okc search "revenue recognition"

# Retrieve a document
okc get metrics/monthly-revenue.md --include metadata,headings,body

# Retrieve the document and its graph context in one call
okc get metrics/monthly-revenue.md --include metadata,custom,content_hash,parent_path,links,backlinks

# Extract a section
okc section metrics/monthly-revenue.md "Definition"

# Structured query
okc metadata --filter type=Metric --filter tags_contains=finance

# Link navigation
okc links metrics/monthly-revenue.md
okc backlinks metrics/monthly-revenue.md

# Graph traversal
okc traverse metrics/monthly-revenue.md --max-depth 3

# Validate
okc validate

# Statistics
okc stats

# Start MCP server
# Local MCP clients such as OpenCode start the stdio child process automatically.
# Use HTTP only when you need a manually hosted remote/shared server.
okc serve --transport stdio

# Watch for changes
okc watch

Configuration

OKC reads a TOML config file from ~/.config/okc/config.toml, ./okc.toml, or a path specified via --config:

[scanner]
roots = ["./knowledge"]
exclude_patterns = [".git/", "node_modules/"]
max_file_size = 2097152           # 2 MB
max_front_matter_size = 65536     # 64 KB
max_yaml_input_size = 8388608    # 8 MB
follow_symlinks = false

[indexer]
max_scan_results = 1000
max_graph_depth = 5
max_graph_nodes = 100
max_response_chars = 500000

[validation]
require_index_files = false

Global CLI flags: --root, --config, --db-path.

See docs/configuration.md for full details.

Documentation

Technology Stack

Development

# Run tests
cargo test

# Check formatting
cargo fmt --check

# Lint
cargo clippy -- -D warnings

# Run benchmarks
cargo bench --features benchmarks

# Run fuzz targets (requires nightly)
cargo +nightly fuzz run frontmatter

# Generate docs
cargo doc --no-deps --open

Roadmap Status

See docs/roadmap.md for details.

License

MIT License — see LICENSE for details.

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.