context-rainbow

Color-aware OKF context routing for progressively loading repository knowledge.

context-rainbow keeps an OKF bundle as a small map of a repository. An agent matches a task against that map, follows the relevant branch, and reads only the source files that the selected OKF documents point to. Source code is not duplicated inside the knowledge bundle.

Why

Task: "Fix refresh token expiry"
                 |
                 v
        Read compact OKF map
                 |
                 v
        Match auth / refresh-token
                 |
                 v
        Follow existing OKF relationships
                 |
                 v
        Read only referenced source files

The package adds one routing convention to OKF: a top-level color field. Existing OKF paths and relationships remain the navigation structure.

Installation

pip install context-rainbow

OKF color convention

Color belongs directly in the document frontmatter:

---
type: Index
title: Authentication
description: Authentication architecture and implementation
tags: [okf, auth]
status: stable
color: amber
relationships:
  - type: applies_to
    target: /repositories/example.md
---

Colors identify sibling branches. Direct children of one splitter/index must have different colors. A color may be reused in a different branch.

Supported colors:

blue · green · amber · red · violet · cyan · pink · orange

Python API

from context_rainbow import ContextRainbow, OkfDocument

documents = [
    OkfDocument(
        id="auth.refresh-token",
        type="code-context",
        title="Refresh token",
        color="red",
        tags=("auth", "refresh", "token"),
        relationships=({"type": "applies_to", "target": "/backend/auth"},),
    ),
]

selected = ContextRainbow(documents).route("Fix refresh token expiry")

for match in selected:
    print(match.document.id, match.reasons)

Routing is deterministic and body-free: matching uses document IDs, titles, tags, and existing relationship targets. The selected document body is loaded only by the caller after routing.

Optional Clinotes integration

Clinotes is not a required dependency. If a repository has committed .clinotes/INDEX.md and detail/*.md files, the adapter exposes those details as project-memory documents:

from context_rainbow.sources.clinotes import load_clinotes

project_memory = load_clinotes("C:/work/my-repo")
selected = ContextRainbow(project_memory).route("refresh token decision")

This adapter is read-only and filesystem-based. Clinotes remains responsible for writing decisions and learnings through its own API/MCP server.

Design boundaries

OKF                  → meaning, architecture, relationships, navigation
Context Rainbow      → color validation and deterministic selection
Repository source    → exact implementation files
Clinotes             → optional project decisions and learnings

Development

python -m pip install -e ".[dev]"
python -m pytest -q
python -m build

Project

• Repository: https://github.com/karthyick/context-rainbow
• Issues: https://github.com/karthyick/context-rainbow/issues
• Author: Karthick Raja M — Karthickrajam18@gmail.com
• License: MIT