GitHub - CognitiveLayers/clayers: Where teams and AI build shared understanding

by Inferal

A structured knowledge base your AI agents can actually use.
Not another pile of markdown files. A layered, schema-validated, content-addressed
specification format with machine-verifiable traceability to code.

Why clayers?

AI agents working with your codebase deserve better than grepping through scattered docs. Clayers gives them a structured knowledge model where every concept has a definition, every definition links to implementing code, and every link is machine-verified against content hashes.

For AI/LLM tooling builders - Your agents get XPath-queryable specifications with typed layers (prose, terminology, relations, plans) instead of unstructured text. Every node carries an LLM description layer purpose-built for machine consumption.

For teams fighting documentation drift - Content hashes on both sides (spec and code) mean drift is detected automatically, not discovered during an incident. Run clayers artifact --drift in CI and know immediately when specs and code diverge.

For spec-first developers - Write the spec, implement the code, map one to the other. Coverage analysis tells you what's specified but unbuilt, what's built but unspecified, and what's drifted since last review.

See it in action

clayers doc generates a single-file knowledge explorer from any spec, with navigable concepts, artifact coverage badges, inline code fragments, and an interactive knowledge graph:

Quick start

# Install via Cargo
cargo install clayers

# Or via pip (includes CLI)
pip install clayers

# Bootstrap clayers in your project
clayers adopt .

# Validate your specification
clayers validate clayers/my-project/

# Check for drift between spec and code
clayers artifact --drift clayers/my-project/

# Generate browsable documentation
clayers doc clayers/my-project/

How it works

A clayers spec is a set of XML documents. Each document can mix content from independent layers, each with its own namespace and schema. Layers are orthogonal: editing prose doesn't require touching artifact mappings.

The layer model is open: clayers ships with a set of built-in layers, but anyone can define new ones. Add a namespace, write a schema, and your custom layer works alongside the built-ins with full validation, querying, and tooling support.

Built-in layers:

All layers share a common ID space enforced by the index. Nodes reference each other by ID across files and layers. Custom layers participate in the same ID space and can reference or be referenced by any built-in layer.

Key features

Drift detection

Both spec nodes and code ranges carry SHA-256 content hashes. When either side changes, --drift catches it:

$ clayers artifact --drift clayers/my-project/
drift: my-project (23 mappings, 1 drifted)

  map-auth-handler: ARTIFACT DRIFTED
    file: src/auth/handler.rs:42-98
    stored:  sha256:d4ca047eaa97...
    current: sha256:abc123def456...

Coverage analysis

See what's specified but unbuilt, and what's built but unspecified:

clayers artifact --coverage clayers/my-project/
clayers artifact --coverage clayers/my-project/ --code-path src/

Connectivity analysis

Graph metrics across your knowledge model: density, hubs, bridges, isolated nodes, cycles.

clayers connectivity clayers/my-project/

XPath queries

Query the assembled spec as a structured knowledge base:

# Find a term's definition
clayers query clayers/my-project/ '//trm:term[@id="term-drift"]/trm:definition' --text

# Locate code implementing a concept
clayers query clayers/my-project/ '//art:mapping[art:spec-ref/@node="auth-flow"]/art:artifact/@path'

# Get the LLM description for a node
clayers query clayers/my-project/ '//llm:node[@ref="auth-flow"]' --text

Content-addressed version control

A purpose-built VCS that understands XML structure. Documents are decomposed into a Merkle DAG of XML Infoset nodes, enabling structural diffs, element-level deduplication, and meaningful merge operations.

clayers init
clayers add *.xml
clayers commit -m "initial specification"
clayers checkout -b feature-auth
# ... edit, commit, merge ...
clayers merge main --strategy auto

Remote collaboration

Push and pull specs over WebSocket. One server hosts multiple named repositories with per-user authentication and daisy-chain proxying.

clayers serve init --repo myspec:/path/to/myspec.db -o server.yaml
clayers serve run server.yaml
clayers clone ws://server:9100/myspec --token <token>

Architecture

Four Rust crates, each with a clear responsibility:

crates/
  clayers-xml/     XML utilities: C14N, content hashing, OASIS catalog, RNC export
  clayers-repo/    Content-addressed Merkle DAG with async SQLite storage
  clayers-spec/    Spec-aware tooling: validation, drift, coverage, connectivity
  clayers/         CLI combining spec and repository commands

Storage is a single .clayers.db SQLite file per repository.

Python bindings

The clayers PyPI package provides the full CLI plus a Python API via PyO3:

pip install clayers
clayers validate clayers/my-project/

Commands

Development

cargo build --workspace
cargo test --workspace
cargo install --path crates/clayers

Links

• Website
• Changelog
• License (Apache-2.0)

Built by Inferal