# How to Record and Analyze AI Decisions in Semantica: A Complete Developer Guide

> Learn to record and analyze AI decisions in Semantica. Our guide shows how to use the dual-layer intelligence stack for causal tracing and semantic similarity search. Boost your AI development.

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

---

**Semantica provides a dual-layer decision intelligence stack that persists AI decisions in a Knowledge Graph for causal tracing and indexes them in a Vector Store for semantic similarity search, precedent analysis, and impact assessment.**

Recording and analyzing AI decisions in Semantica relies on a unique architecture that combines graph-based persistence with vector embedding search. According to the semantica-agi/semantica source code, the system captures every decision as a first-class node in a Knowledge Graph while simultaneously embedding decisions for fast, hybrid retrieval via the Vector Store layer.

## Understanding Semantica's Dual-Layer Architecture

Semantica splits decision intelligence across two specialized layers that work in tandem to provide both durable persistence and fast analytical queries.

### Knowledge Graph Layer (Persistence)

The Knowledge Graph (KG) layer persists every decision as a node linked to entities, policies, and causal relationships. Implementation lives primarily in [`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py), where the `handle_record_decision` function orchestrates the persistence flow. This layer handles input validation, node creation, and conditional persistence based on the `SEMANTICA_KG_PATH` environment variable.

### Vector Store Layer (Analysis)

The Vector Store layer provides fast hybrid similarity search, batch processing, and explanation capabilities through embedded decision vectors. High-level convenience functions such as `find_precedents`, `explain`, and `quick_decision` reside in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py) and delegate to configurable backends like FAISS or Weaviate.

## Recording AI Decisions

When recording a decision, Semantica validates required fields, creates a graph node, and optionally persists to disk. The `handle_record_decision` function in [`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py) enforces mandatory fields: `category`, `scenario`, `reasoning`, `outcome`, and `confidence`.

The workflow proceeds through four stages:

1. **Input validation** – checks required fields
2. **Graph acquisition** – `get_graph()` retrieves the singleton KG instance
3. **Node creation** – `graph.record_decision()` stores the decision and returns a unique `decision_id`
4. **Persistence** – if `SEMANTICA_KG_PATH` is set and `is_persistence_safe()` returns true, the graph saves to disk; otherwise the mutation rolls back to maintain consistency

For application developers, the `DecisionContext` class in [`semantica/context/decision_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_context.py) provides a simplified interface:

```python
from semantica.context.decision_context import DecisionContext

ctx = DecisionContext()
decision_id = ctx.record_decision(
    category="credit",
    scenario="Approve loan for applicant X",
    reasoning="Credit score 750, low debt-to-income",
    outcome="approved",
    confidence=0.94,
    entities=["Applicant X", "Bank"],
)
print(f"Decision recorded with ID: {decision_id}")

```

## Querying and Retrieving Decisions

Semantica offers two primary retrieval modes depending on your query pattern.

**Natural-language search** uses `query_decisions`, which delegates to `graph.find_similar_decisions` to perform semantic matching against decision text.

**Structured filters** apply category, outcome, or entity constraints to refine result sets after initial retrieval:

```python
results = ctx.query_decisions(category="credit", limit=5)
for d in results["decisions"]:
    print(d["decision_id"], d["outcome"])

```

## Finding Precedents with Hybrid Similarity

The `find_precedents` function in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py) enables case-based reasoning by retrieving historically similar decisions using hybrid weights that balance semantic meaning against structural graph features.

The function signature supports tuning the relevance algorithm:

```python
from semantica.vector_store.decision_vector_methods import find_precedents

precedents = find_precedents(
    query="Approve loan for applicant X",
    limit=3,
    semantic_weight=0.8,
    structural_weight=0.2,
    category="credit"
)
for p in precedents:
    print(p["decision_id"], p["score"])

```

Higher `semantic_weight` prioritizes vector embedding similarity, while `structural_weight` emphasizes graph topology and relationship proximity.

## Explaining, Tracing, and Analyzing Impact

Beyond retrieval, Semantica provides tools for decision interpretability and downstream impact analysis through three core functions.

**Generating explanations** – The `explain` function retrieves explanation data including reasoning paths, confidence scores, and similarity weights:

```python
from semantica.vector_store.decision_vector_methods import explain

explanation = explain(decision_id, include_paths=True, include_confidence=True)
print(explanation)

```

**Tracing causal chains** – `get_causal_chain` follows decision dependencies upstream or downstream. According to [`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py), this attempts to use `CausalChainAnalyzer` when available, falling back to the graph's native `get_causal_chain` method:

```python
chain = ctx.get_causal_chain(decision_id=decision_id, direction="downstream", max_depth=4)
print(chain)

```

**Analyzing decision impact** – `analyze_decision_impact` computes downstream effects across the Knowledge Graph by calling `graph.analyze_decision_impact` (or the legacy `analyze_decision_influence`):

```python
impact = ctx.analyze_decision_impact(decision_id=decision_id)
print(impact)

```

## Configuring the Vector Store Backend

Before using vector-based analysis methods, initialize the global vector store once per process. The `set_global_vector_store` function in [`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py) registers the backend that all convenience functions will use:

```python
from semantica.vector_store.decision_vector_methods import set_global_vector_store
from semantica.vector_store.weaviate_store import WeaviateVectorStore

store = WeaviateVectorStore(endpoint="http://localhost:8080")
set_global_vector_store(store)

```

Once configured, utilities like `quick_decision`, `similar_to`, `batch_decisions`, and `stats` automatically utilize this store for embedding and retrieval operations.

## Summary

- **Dual-layer persistence**: Semantica stores decisions in a Knowledge Graph ([`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py)) for causal relationships and a Vector Store ([`semantica/vector_store/decision_vector_methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/decision_vector_methods.py)) for similarity search.
- **Recording workflow**: Use `DecisionContext.record_decision()` with mandatory fields (category, scenario, reasoning, outcome, confidence) to generate unique decision IDs with optional disk persistence via `SEMANTICA_KG_PATH`.
- **Hybrid search**: `find_precedents` combines semantic and structural weights to surface relevant historical decisions.
- **Traceability**: Functions like `get_causal_chain` and `analyze_decision_impact` trace downstream effects and policy changes across the graph.
- **Setup requirement**: Initialize the global vector store with `set_global_vector_store()` before calling embedding-based analysis methods.

## Frequently Asked Questions

### How does Semantica ensure decision data persists across restarts?

The Knowledge Graph layer checks for the `SEMANTICA_KG_PATH` environment variable after recording a decision. If set and `is_persistence_safe()` returns true, `handle_record_decision` calls `graph.save_to_file(kg_path)` to write the mutated graph to disk. Without this variable, decisions remain in memory only and roll back if persistence fails.

### What is the difference between `query_decisions` and `find_precedents`?

`query_decisions` operates on the Knowledge Graph layer and performs natural-language similarity matching through `graph.find_similar_decisions`, suitable for broad semantic searches. `find_precedents` targets the Vector Store layer and constructs hybrid queries combining semantic embedding similarity with structural graph weights, optimized for case-based reasoning and legal precedent analysis.

### Can I adjust how much weight Semantica gives to semantic meaning versus graph structure?

Yes. Both `find_precedents` and underlying vector store methods accept `semantic_weight` and `structural_weight` parameters (0.0–1.0 scale) that control the hybrid scoring algorithm. A `semantic_weight` of 0.8 and `structural_weight` of 0.2 prioritizes text meaning over relationship topology, while inverse values emphasize causal chain proximity.

### Which file contains the JSON schemas for decision tool inputs?

The input shapes and validation schemas for all MCP decision tools are defined in [`semantica_mcp/mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/schemas.py). This file specifies required fields, data types, and constraints for operations like `record_decision`, `query_decisions`, and `find_precedents`.