Saltar a contenido

Knowledge Cartridges

A knowledge cartridge is a distributable unit of domain knowledge — a packaged corpus of documents, extraction configuration, and pre-extracted graph nodes. Cartridges teach Rai about things it hasn't encountered in your project: a methodology, an external framework, a project-specific architecture.

Why Cartridges Exist

The Knowledge Graph is powerful, but it only knows what it has seen. A fresh project has no patterns, no principles, no architectural decisions in the graph. Without priming, Rai starts every session with zero institutional knowledge.

Cartridges solve this by packaging knowledge that can be shipped, installed, and imported into the graph on any machine. The raise-methodology cartridge — bundled with every RaiSE install — teaches Rai the RaiSE methodology itself. You can create project-specific cartridges to teach Rai your codebase's architecture, or community cartridges to share domain knowledge across teams.

Cartridge Structure

A cartridge is a directory with a manifest and three content areas:

my-cartridge/
├── CARTRIDGE.yaml      ← manifest: name, version, description, schema
├── corpus/             ← source documents (Markdown, text, code)
│   ├── principles.md
│   └── architecture.md
├── extractors/         ← extraction rules (YAML or Python)
│   └── concepts.yaml
└── instances/          ← pre-extracted graph nodes (JSON)
    └── nodes.json

CARTRIDGE.yaml

The manifest declares the cartridge identity and extraction schema:

name: raise-methodology
version: 1.0.0
description: "Core RaiSE methodology — principles, patterns, and workflow"
tier: community
schema:
  node_types: [principle, pattern, guardrail, requirement]
  edge_types: [governed_by, depends_on, learned_from]

corpus/

Raw documents that are the source of truth. These are the texts Rai reads when the cartridge is active. Markdown, plain text, and code files are all valid.

extractors/

Rules for turning corpus documents into graph nodes. Extractors declare what to look for — headings, tagged sections, code symbols — and how to map them to node types.

instances/

Pre-extracted graph nodes in JSON format. These are the result of running the extractors over the corpus. Including pre-extracted instances means installation is fast — no extraction run needed unless you modify the corpus.

Cartridge Lifecycle

init → extract → validate → pack → publish
                                  → install
Phase Command What happens
init rai cartridge init Scaffold CARTRIDGE.yaml and directory structure
extract rai cartridge extract Run extractors over corpus, produce instances/
validate rai cartridge validate Check schema compliance and instance integrity
pack rai cartridge pack Create distributable .cartridge archive
publish rai cartridge publish Push to registry (Pro tier)
install rai cartridge install Import cartridge into the local graph

Tiers

Tier Description
community Bundled with RaiSE or installed from a local path. The raise-methodology cartridge is community tier.
pro Hosted in the RaiSE server registry. Requires a Pro account. Supports versioned distribution to teams.

The raise-methodology Cartridge

This is the canonical example of a cartridge. It ships pre-installed with RaiSE and populates the graph with:

  • RaiSE principles (Jidoka, Kaizen, Poka-yoke, etc.)
  • The Shu-Ha-Ri coaching model
  • Built-in guardrails (TDD, commit discipline, branch model)
  • Skill lifecycle patterns

When you run rai session start, the graph nodes from this cartridge are among the first things loaded into context.

Next Steps