CIR Substrate

CIR -- Cognitive Infrastructure Retrieval -- is the knowledge substrate at the heart of mentu. It tracks not just what you know, but when you learned it, how confident you are, and whether it contradicts something else.

Why CIR exists

Traditional tools treat knowledge as static. A config file is true until someone changes it. A document is current until someone updates it. But real knowledge has a time dimension:

An observation from last week may be contradicted by new evidence today
A high-confidence classification may decay as the underlying system evolves
Two independent analyses may reach conflicting conclusions

CIR makes this explicit. Every piece of knowledge is a signal with metadata: type, confidence, source, timestamp, tags. Signals connect through relations. Patterns emerge from recurring structures. And when two signals conflict, CIR surfaces the contradiction rather than silently picking one.

ℹ️

For the conceptual introduction to CIR and why it exists, see What is CIR?. This page covers the technical mechanics.

Signals

The atomic unit of knowledge. A signal is a single observation, classification, inference, or fact captured into CIR.

interface CIRSignal {
  id: string;           // Unique identifier
  type: string;         // 'observation', 'classification', 'generation', 'embedding', 'model_load'
  body: string;         // The actual content
  domain?: string;      // Knowledge domain (e.g., 'infrastructure', 'security')
  confidence?: number;  // 0.0 to 1.0
  source?: string;      // What produced this signal
  created_at?: string;  // ISO 8601 timestamp
  tags?: string[];      // Categorization tags
}

Signals are immutable once captured. You do not update a signal. You capture a new one with a higher confidence or a different observation, and CIR tracks both.

A concrete example:

{
  "id": "sig_a7f3b2c1",
  "type": "observation",
  "body": "API latency exceeded 500ms threshold at 14:32 UTC",
  "domain": "infrastructure",
  "confidence": 0.95,
  "source": "health-script",
  "created_at": "2026-04-04T14:32:00Z",
  "tags": ["latency", "alert", "api"]
}

type describes what kind of knowledge this is. observation is something directly measured. classification is a categorization. generation is something produced by an LLM.
confidence is a score between 0 and 1. A direct measurement might be 0.95. An inference from indirect evidence might be 0.6. Confidence is metadata, not a filter. Low-confidence signals are still valuable as context.
source identifies what produced the signal. This can be a script name, a sequence, or a manual capture.

Relations

Signals connect through relations (supports, contradicts, extends, and others). Relations form a directed graph over the signal corpus. They determine how trust flows between signals. When a supporting signal is weakened, dependent signals adjust accordingly.

Embeddings

Vector representations of signals for semantic search. When you call mentu.cir.search('authentication failure'), the search runs against embeddings to find signals whose meaning matches, not just signals whose text contains the words.

Patterns

Recurring structures detected across signals. A pattern emerges when CIR observes the same type of signal from the same domain with similar content appearing repeatedly. Patterns are the substrate's way of saying "this keeps happening."

Contradictions

When two signals conflict -- one says the API is healthy, another says it is down -- CIR surfaces the contradiction. Contradictions are not errors. They are evidence that the world is more complex than a single observation suggests.

Querying CIR

Via CLI

# Recent signals
mentu cir query --type observation --since 24h --limit 10
 
# Search by content
mentu cir search "authentication failure"
 
# Aggregate stats
mentu cir stats
 
# Check for contradictions
mentu cir contradictions

Via SDK (in scripts)

// Query with filters
const signals = mentu.cir.query({ type: 'observation', since: '24h', limit: 50 });
 
// Full-text search
const matches = mentu.cir.search('authentication failure', { limit: 5 });
 
// Aggregate stats
const stats = mentu.cir.stats();
 
// Contradiction check
const contradictions = mentu.cir.contradictions();

Via MCP tools

AI models with mentu-mcp configured can access CIR through the mcp_do tool with CIR-related intents.

Capturing signals

Signals enter CIR through three paths:

SDK capture -- scripts call mentu.cir.capture() to record observations
CLI capture -- mentu cir capture "some observation" from the terminal
System signals -- mentu itself emits signals for model loads, embeddings, and other system events

// Capture from a script
mentu.cir.capture('Deployment completed successfully', {
  type: 'observation',
  domain: 'deployment',
  confidence: 1.0,
  source: 'deploy-script',
  tags: ['deploy', 'success'],
});

Learning from execution

Every execution feeds back into CIR. When a sequence completes, mentu observes what happened (how many steps succeeded, whether contradictions appeared) and adjusts trust scores accordingly. This is mechanical, not self-assessed. The system looks at outcomes, not opinions.

Over time, recurring patterns crystallize into reusable structures. A pattern that appears consistently with high confidence can be promoted to a named recipe, committed, scheduled, and composed with other recipes.

Why CIR matters

CIR is what makes mentu more than a task runner. Without CIR, a health check script runs, prints output, and the output disappears. With CIR, the script captures its observations as signals. The next run can query what happened last time. A temporal can trend observations over days. A contradiction surfaces when two health checks disagree.

Knowledge compounds. CIR is the compound interest mechanism.