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

> Learn to track and audit AI decisions with Semantica. Use its decision-intelligence stack to record, query, and analyze AI choices for complete audit trails. Get the technical guide.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py). The architecture separates concerns between graph access, schema validation (handled in [`semantica_mcp/mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/schemas.py)), and persistence logic (managed by [`semantica/vector_store/vector_store_provenance.py`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py) prevents corruption by verifying that the initial graph load succeeded before allowing write operations.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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.

```python

# 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`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py) computes upstream and downstream dependency paths using the `CausalChainAnalyzer` class imported from [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/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.

```python
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.

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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.