Skip to content

Project Knowledge

Project knowledge is factual context that belongs to the consuming repository rather than reusable EmbrAIon Core.

Typical examples:

  • product architecture;
  • domain terminology;
  • hardware or platform constraints;
  • supported compatibility contracts;
  • source-of-truth locations;
  • decisions that should survive across AI sessions.

Core vs project knowledge

Keep reusable engineering behavior in Core and product-specific truth in the project.

EmbrAIon Core Project repository
roles product facts
reusable skills domain rules
model-agnostic routing architecture
hard gates compatibility and source-of-truth details

A practical rule is:

If a fact is true because of this product, customer, repository, device, or domain, it probably belongs in project knowledge.

Reusable engineering procedures and universal EmbrAIon safety rules belong in Core instead.

Keep knowledge in ordinary project files

A common layout is:

knowledge/
├── project.md
├── architecture.md
└── compatibility.md

.embraion/knowledge.yaml references those files; it does not duplicate their contents.

Shortest form:

project: knowledge/project.md
architecture: knowledge/architecture.md

Structured form:

architecture:
  path: knowledge/architecture.md
  data-class: PRIVATE
  trust: project
  roles:
    - architect
    - lead
  triggers:
    - architecture

When to create a knowledge file

Create project knowledge when a fact should remain available across AI sessions and belongs to the repository rather than to one transient task.

Do not put executable validation commands in knowledge files. Those belong in .embraion/validation.yaml. Knowledge can document why a compatibility or architecture constraint exists; validation defines the commands that prove it still holds.

Context selection

Structured entries can declare:

  • data-class — PUBLIC, PRIVATE, or CONFIDENTIAL;
  • trust — project, external, or generated;
  • roles — which roles are eligible to receive the knowledge;
  • triggers — task terms that make the knowledge relevant.

Build a context selection record with:

embraion context build \
  --task "Review architecture boundaries" \
  --role architect \
  --data PRIVATE \
  --max-chars 20000

The runtime state stores provenance and hashes, not a second copy of the knowledge content.

Verify

embraion doctor

EmbrAIon validates declared knowledge references.

For the complete schema, see Project Configuration Files.