AI Reasoning Systems —
Context Architecture

Two Models. One is Wrong.

# What most devs build
prompt = "Extract signals. Don't 
hallucinate. No solutioning."
LLM(prompt + raw_data)

# What the system actually is
context_packet = assemble(
  global_context.yaml
  + step_overlay.yaml
  + session_data
  + artifact_summaries
)
LLM(prompt_template 
    + context_packet)

The Sentence to Memorize

What Goes Wrong When Devs Miss This

The Thin Prompt Rule

Prompts should define exactly two things:

Decision Framework

Storage decisions are not arbitrary. Each storage type has a distinct query model that maps to a distinct retrieval need. Wrong choice = retrieving the wrong kind of context at runtime.

MESH System Storage Map

Vectorgraph: The Emerging Pattern

Standard vector search finds what is semantically similar. Standard graph traversal finds how things relate. In complex reasoning systems, you need both simultaneously.

Production implementations: Weaviate (vector with graph-like cross-references), Neo4j with vector index extension, Qdrant with payload filtering for relationship metadata. This space is moving fast — evaluate against your specific query patterns before committing.

MVP Storage Guidance

Artifact Inventory

Context Architecture Document — Required Sections

This is the document your developers implement against. It is not a prompt. It is a behavioral specification.

• System purpose and reasoning environment description
• Global context: governance rules with rationale
• Signal hierarchy definition: tier definitions with examples
• Step map: list of steps, what each step can and cannot do
• Session schema: field definitions, types, constraints
• Context assembly spec: exactly how the context packet is built
• LLM call structure: system / user / task template format
• Observability requirements: what gets logged, how outputs trace to inputs
• Known failure modes and mitigations
• Version history and change rationale

YAML File Requirements

Assembly Pattern

# Parse both files before building context
global_rules = yaml.safe_load(open("00_global_context.yaml"))
step_rules   = yaml.safe_load(open(f"01_step{step}_setup.yaml"))

# Hard rule enforcement — NOT in the prompt
if global_rules["block_processing_if_agreement_missing"]:
    if not session_data.get("agreement_confirmed"):
        raise GovernanceViolation("Agreement required")

{
  "global_rules":  parsed_global_context,
  "step_rules":    parsed_step_overlay,
  "session_data":  session_record,
  "signals":       signal_list_with_metadata,
  "artifacts":     step_artifacts
}

# Correct injection structure
SYSTEM:
  You are operating under the following system rules:
  {global_context}
  {step_overlay}

USER:
  Here is the session context:
  {assembled_context_packet}

TASK:
  {task_template}  # thin — defines task + output format only

provenance_log.append({
  "session_id":      session_id,
  "step":            step,
  "timestamp":       now(),
  "context_packet":  context_packet,   # full packet
  "llm_response":    response,
  "model_version":   model_id          # track model changes
})

Identifying What Needs to Be Tracked

Not everything needs the same visibility. Use these questions to identify your system's specific tracking requirements:

Required Tracking — Minimum Viable Observability

Drift Detection

Drift can come from three sources. Each requires different detection:

These patterns are not random. They cluster into recognizable shapes that emerge when systems synthesize multiple inputs. Once named, they become testable.

Anthropic Research Anchors

For teams wanting to connect these patterns to published research:

Test Design Principles

Expected behavior must be defined before running tests. If you don't know what the system should do, you can't evaluate what it actually does.

Test Script Template

## Test: [Pattern Name] — [Step]

Target distortion:  [pattern from taxonomy]
Step under test:    [step_0 / step_1 / etc.]
Config active:      [yaml version]
Model version:      [model identifier]

Input setup:
  [Describe the inputs, including any deliberate manipulations]

Expected behavior:
  [Exactly what the system should do — before running]

Pass criteria:
  □ [Observable criterion 1]
  □ [Observable criterion 2]

Fail signals:
  □ [What would indicate the distortion occurred]

Result:       [ PASS / FAIL / PARTIAL ]
Observed:     [What actually happened]
Root cause:   [Prompt / Config / Data / Architecture / Model]

Core Test Scenarios — By Distortion

Source Hierarchy Collapse

Narrative Completion Bias

Confidence Inflation

Step Boundary Drift

Provenance Loss

Rule Enforcement

Context Assembly Verification Test

Architecture Review

• Global context YAML exists and is versioned in source control
• Step overlay YAMLs exist for each step and are versioned
• Session schema is defined with no placeholder fields
• Context Architecture Doc exists and is current
• Context assembler service exists as code (not file reference)
• Hard governance rules are enforced in backend code before LLM call
• Prompt templates are thin (task + format only)
• Governance / hierarchy / behavioral rules are NOT in prompts

Implementation Verification

• Can point to the exact code that merges global context + step overlay + session data
• Context packet is logged alongside every LLM response
• Model version / identifier is logged per call
• Config file version is logged per call
• Signal tier is stored per signal
• Provenance log is append-only and queryable
• Step boundary events are logged with timestamps

Storage Verification

• Session records are in SQL with stable schema
• Signals are in SQL (structured fields) — optionally also vectorized for semantic retrieval
• YAML files are on file system / object store, not in database
• Storage schema was not normalized before session flow was proven end-to-end
• No over-normalized tables for fields that could live in JSONB during MVP

QA Readiness

• QA test scripts exist for each step
• Expected behavior is defined before each test run
• Tests include adversarial inputs (conflicting sources, degraded evidence, ambiguous signals)
• Tests cover all 7 distortion patterns
• Rule enforcement tests have been run (prohibited behavior check)
• Assembly verification test has been run and passed
• Baseline test suite exists for drift detection

Separation of Concerns

You're building correctly if you can demonstrate separation of: