How to Track and Audit AI Decisions with Semantica: A Complete Technical Guide

Semantica provides a built-in decision-intelligence stack that lets you record, query, trace causal chains, and analyze impact of AI-driven choices using a native knowledge graph that persists to disk for complete audit trails.

Semantica is an open-source decision-intelligence framework that treats every AI choice as a first-class node in a queryable knowledge graph. By leveraging the Model-Control-Plane (MCP) tool architecture implemented in the semantica-agi/semantica repository, you can track and audit AI decisions with Semantica through native functions that capture reasoning, outcomes, and provenance metadata while maintaining atomic persistence guarantees.

Understanding the Decision Intelligence Architecture

The core decision-tracking capabilities are exposed through the DECISION_TOOLS registry defined in semantica_mcp/mcp/tools/decisions.py. This module implements MCP-compatible functions that manage the complete decision lifecycle—from initial recording to downstream impact analysis.

Each decision is stored as a typed node within the Semantica knowledge graph (KG), accessible via the get_graph() utility located in semantica_mcp/mcp/session.py. The architecture separates concerns between graph access, schema validation (handled in semantica_mcp/mcp/schemas.py), and persistence logic (managed by semantica/vector_store/vector_store_provenance.py), ensuring that audit trails remain consistent even during concurrent access.

Recording Decisions with Full Metadata

The record_decision function creates a structured decision node accepting comprehensive metadata fields that satisfy regulatory and debugging requirements. Each recording includes category, scenario, reasoning, outcome, confidence, decision_maker, and temporal bounds (valid_from, valid_until).

When the SEMANTICA_KG_PATH environment variable is configured, the system atomically persists the updated knowledge graph to disk after each successful record operation. The is_persistence_safe() guard in semantica_mcp/mcp/session.py prevents corruption by verifying that the initial graph load succeeded before allowing write operations.

from semantica_mcp.mcp.session import get_graph
from semantica_mcp.mcp.tools.decisions import DECISION_TOOLS

# Example payload

payload = {
    "category": "loan_approval",
    "scenario": "Applicant requests $10k loan with credit score 720",
    "reasoning": "Score above threshold, debt‑to‑income ratio acceptable",
    "outcome": "approved",
    "confidence": 0.94,
    "decision_maker": "loan_approval_service",
    "valid_from": "2024-01-01T00:00:00Z",
    "valid_until": "2025-01-01T00:00:00Z",
}

# Directly call the handler (MCP clients normally dispatch this)

result = DECISION_TOOLS[0]["_handler"](payload)
print(result)

The handler validates the payload against JSON-Schema definitions in semantica_mcp/mcp/schemas.py, writes the decision node into the graph, and triggers persistence when configured.

Querying Historical Decisions and Precedents

Semantica supports two primary retrieval patterns: filtered enumeration and semantic similarity search. The query_decisions function accepts category and outcome filters alongside free-text queries, executing either graph.find_similar_decisions or direct node traversal depending on the query structure.

For precedent analysis, the find_precedents function specializes the similarity search to focus exclusively on the scenario field, enabling case-based reasoning by locating historically similar situations.

# Querying recent decisions by category

payload = {"category": "loan_approval", "limit": 5}
result = DECISION_TOOLS[1]["_handler"](payload)
for d in result["decisions"]:
    print(d["decision_id"], d["outcome"])

# Finding precedents for a new scenario

payload = {"scenario": "Applicant with credit score 610 requests $5k loan"}
precedents = DECISION_TOOLS[2]["_handler"](payload)
print(f"Found {precedents['count']} similar past decisions")

Tracing Causal Chains for Explainability

Regulatory frameworks often require demonstrating why a decision was reached. The get_causal_chain function in semantica_mcp/mcp/tools/decisions.py computes upstream and downstream dependency paths using the CausalChainAnalyzer class imported from semantica/context/causal_analyzer.py.

The function accepts direction (upstream or downstream), max_depth, and depth parameters, delegating to backend-specific causal analysis implementations when available. Results are normalized to a deterministic list of node IDs representing the complete causal pathway.

payload = {"decision_id": "dec-12345", "direction": "upstream", "max_depth": 3}
chain = DECISION_TOOLS[3]["_handler"](payload)
print("Causal chain:", chain["chain"])

Measuring Downstream Impact

Beyond simple lineage tracking, Semantica quantifies decision influence through graph-theoretic metrics. The analyze_decision_impact function invokes backend-specific implementations of analyze_decision_impact (or the legacy analyze_decision_influence interface) to compute PageRank scores, influence radii, and affected entity counts.

These algorithms operate against vector store backends—such as Weaviate, Qdrant, or Milvus—enabling scalable impact analysis across millions of interconnected decisions.

payload = {"decision_id": "dec-12345"}
impact = DECISION_TOOLS[4]["_handler"](payload)
print("Impact report:", impact["impact"])

Summary

• Native MCP Integration: All decision tools are registered in DECISION_TOOLS within semantica_mcp/mcp/tools/decisions.py, making them discoverable by any MCP-compliant client.
• Atomic Persistence: The system uses SEMANTICA_KG_PATH and is_persistence_safe() checks to guarantee that audit trails are durably stored without corruption risk.
• Rich Metadata Model: Decisions capture category, scenario, reasoning, confidence, temporal validity, and decision-maker identity for comprehensive auditing.
• Causal Explainability: The CausalChainAnalyzer in semantica/context/causal_analyzer.py enables root-cause analysis through directional graph traversal.
• Impact Quantification: Backend graph algorithms provide objective metrics (PageRank, influence) for assessing decision significance.

Frequently Asked Questions

What metadata fields are required when recording a decision?

Semantica requires category, scenario, reasoning, outcome, and confidence as core fields, with optional but recommended decision_maker, valid_from, and valid_until timestamps. The JSON-Schema definitions in semantica_mcp/mcp/schemas.py enforce these constraints before persisting to the knowledge graph.

How does Semantica prevent audit trail corruption during persistence?

The framework implements a safety check via is_persistence_safe() in semantica_mcp/mcp/session.py that verifies the knowledge graph loaded successfully at startup. If the initial load failed, persistence operations are blocked to prevent overwriting valid historical data with a corrupted state. When safe, semantica/vector_store/vector_store_provenance.py performs atomic file writes to the path specified by SEMANTICA_KG_PATH.

Can decisions be queried across multiple categories simultaneously?

The query_decisions function supports filtering by single category values and free-text search across all decision content. For complex multi-category queries, implement client-side filtering on the returned results or extend the backend graph implementation to support array-based category filtering.

Is the causal chain analyzer available in all Semantica installations?

The CausalChainAnalyzer is lazily imported from semantica/context/causal_analyzer.py and used when available. If the analyzer module is not present or the active vector store backend implements native causal methods, get_causal_chain falls back to backend-specific traversal signatures (direction, max_depth, depth), ensuring compatibility across different deployment configurations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}