Knowledge register — Context Nexus

What does Knowledge contain?

Domain knowledge · Business glossary · Architecture map · Conventions & patterns · Anti-patterns · Regulatory constraints · Decision Contexts · Observed consequences of past decisions.

Humans vs AI Agents

Human

Refers to it to understand context, judge the relevance of a decision, onboard quickly, avoid repeating past mistakes.

AI Agent

Anchors in the domain to avoid hallucinating, produces code coherent with the existing codebase and respectful of conventions without being reminded.

Asymmetry: judgment vs. coherence.

Consumption modes

System Prompt

Universal conventions and absolute anti-patterns go in the system prompt. Short, unambiguous, always true.

RAG

Decision Contexts, architecture maps, and business glossary go in the vector index. Too voluminous for the system prompt, retrieved by RAG on demand.

Artifact structure

Each Knowledge artifact is a markdown file with a YAML frontmatter block defining its register, level, owner, status, and consumption mode.

---
register: knowledge
level: team
owner: tech-lead
status: active
consumption-mode: rag
last-validated: 2026-06-03
---

# Decision Context — Event-driven indexation

## Situation
P95 latency spikes to 1.8s during mass catalogue updates.
Cause: synchronous writes to Elasticsearch from catalog-updater service.

## Options evaluated

### CQRS with separate read model
Rejected: high maintenance cost for a 7-person team.
Reference incident: similar pattern on project X (2024), two P1s.

## Decision taken
Async event-driven indexation: catalogue updates produce Kafka events
consumed by a dedicated indexer → Elasticsearch.

## Observed consequences
(to be completed after 30 days in production)

RAG indexing

Knowledge artifacts are chunked by atomic concept, then embedded into a vector index.

from langchain.text_splitter import MarkdownHeaderTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import SentenceTransformerEmbeddings

def index_knowledge(nexus_root: str, team: str) -> Chroma:
    splitter = MarkdownHeaderTextSplitter(
        headers_to_split_on=[("##", "section"), ("###", "subsection")]
    )
    docs = []
    for level in ["org", f"intermediate/{team_bu}", f"teams/{team}"]:
        for path in glob(f"{nexus_root}/{level}/knowledge/**/*.md"):
            chunks = splitter.split_text(open(path).read())
            for chunk in chunks:
                chunk.metadata.update({"level": level, "source": path})
            docs.extend(chunks)

    return Chroma.from_documents(
        docs,
        SentenceTransformerEmbeddings(model_name="all-MiniLM-L6-v2"),
        persist_directory=f".chroma/{team}"
    )