# How to Record and Manage Decisions in Semantica's ContextGraph: MCP Tools Explained

> Discover how to record manage and trace decisions in Semantica's ContextGraph using MCP tools. Learn to leverage JSON-Schema for provenance and efficient querying of your decision data.

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

---

**Semantica treats every decision as a first-class node in the ContextGraph, providing JSON-Schema-driven MCP tools in [`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py) to record, query, and trace decisions with full provenance.**

Semantica's ContextGraph architecture provides native support for decision management through its Model-Control-Plane (MCP) toolkit. This guide demonstrates how to record and manage decisions in Semantica's ContextGraph using Python handlers that enforce schema validation, persist to disk, and enable semantic similarity search across your knowledge base.

## Recording Decisions with Schema Enforcement

The primary entry point for persistence is `handle_record_decision` in [`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py) (lines 23‑41). This function validates incoming payloads against the `RECORD_DECISION` schema defined in [`semantica_mcp/mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/schemas.py) (lines 39‑78), ensuring required fields like `category`, `scenario`, and `reasoning` are present while enforcing constraints such as confidence limits between 0 and 1 and ISO‑8601 dates for validity windows.

Once validated, the handler invokes `graph.record_decision(...)` to create the node and, if persistence is safe, calls `graph.save_to_file` to write the updated graph back to the path specified by the `SEMANTICA_KG_PATH` environment variable (lines 42‑62).

```python
from semantica_mcp.mcp.tools.decisions import handle_record_decision

payload = {
    "category": "loan_approval",
    "scenario": "Applicant requests $50k loan for home renovation",
    "reasoning": "Credit score 720, debt‑to‑income 30%, collateral provided",
    "outcome": "approved",
    "confidence": 0.93,
    "entities": ["applicant_123", "collateral_house_456"],
    "decision_maker": "automated_risk_engine",
    "valid_from": "2024-01-01T00:00:00Z",
    "valid_until": "2029-12-31T23:59:59Z",
}
result = handle_record_decision(payload)
print(result)  # → {'decision_id': 'd-...', 'status': 'recorded', ...}

```

### Persistence Safety Mechanisms

The graph singleton is lazily instantiated in [`semantica_mcp/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py) via `get_graph` (lines 35‑48). It checks `_load_ok` before any write operations to guard against corrupting an unloadable knowledge graph. If `SEMANTICA_KG_PATH` points to a readable JSON file, the graph loads existing data; otherwise, a fresh instance is created. Mutations only trigger `save_to_file` when `is_persistence_safe()` returns `True`.

## Querying Decisions and Finding Precedents

The MCP layer provides two complementary retrieval strategies. For attribute-based filtering, `handle_query_decisions` (lines 85‑104) accepts parameters like `category`, `outcome`, or free-text queries, returning decision nodes via `graph.find_similar_decisions` or `graph.find_nodes(node_type="decision")`.

For semantic precedent search, `handle_find_precedents` (lines 110‑119) accepts a scenario string and forwards it to the graph's hybrid similarity pipeline. This enables retrieval of historically similar decisions even when keywords differ.

```python
from semantica_mcp.mcp.tools.decisions import handle_query_decisions, handle_find_precedents

# Filter by category

query_result = handle_query_decisions({"category": "loan_approval", "limit": 5})

# Semantic similarity search

precedents = handle_find_precedents({
    "scenario": "small business seeks equipment financing",
    "max_results": 3
})

```

## Causal Chain Analysis and Impact Tracing

Decisions in the ContextGraph are traversable entities. The `handle_get_causal_chain` function (lines 126‑221) traces upstream or downstream dependencies from a given `decision_id`. It constructs a `CausalChainAnalyzer` when available (lines 144‑148), falling back to `graph.get_causal_chain` for backward compatibility, and normalizes results to show the full provenance path.

For downstream analysis, `handle_analyze_decision_impact` (lines 226‑242) calls `graph.analyze_decision_impact` (or its legacy alias `analyze_decision_influence`) to identify which nodes are affected by a specific decision, enabling audit trails and impact assessments.

```python
from semantica_mcp.mcp.tools.decisions import (
    handle_get_causal_chain,
    handle_analyze_decision_impact
)

# Trace upstream reasoning

chain = handle_get_causal_chain({
    "decision_id": "d-abc123",
    "direction": "upstream",
    "max_depth": 4
})

# Analyze downstream effects

impact = handle_analyze_decision_impact({"decision_id": "d-abc123"})

```

## Linking Decisions to the Broader Graph

Because decisions are first-class nodes, they integrate with the graph's relationship model. You can link decisions to **Project**, **Person**, or **Document** nodes using standard relationship tools like `add_relationship`. This creates traceability from a decision to its supporting evidence, responsible parties, and downstream effects without requiring specialized edge types.

## Summary

- **Decision nodes** are native citizens of the ContextGraph, stored and queried via MCP tools in [`semantica_mcp/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/decisions.py).
- **`handle_record_decision`** enforces JSON Schema validation (confidence 0‑1, ISO‑8601 dates) and persists to `SEMANTICA_KG_PATH` when safe.
- **Retrieval** supports both exact filtering (`handle_query_decisions`) and semantic similarity (`handle_find_precedents`).
- **Causal tracing** uses `handle_get_causal_chain` and `handle_analyze_decision_impact` to walk dependency graphs and assess influence.
- **Safety checks** via `is_persistence_safe()` and `_load_ok` in [`semantica_mcp/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py) prevent writing to corrupt or unloadable graph files.

## Frequently Asked Questions

### What environment variable controls where decisions are saved?

Set **`SEMANTICA_KG_PATH`** to a writable JSON file path. The `get_graph` function in [`semantica_mcp/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py) loads from this path at startup and writes updates back when mutations occur and `is_persistence_safe()` returns `True`.

### How does Semantica validate decision payloads before recording?

The `RECORD_DECISION` schema in [`semantica_mcp/mcp/schemas.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/schemas.py) (lines 39‑78) defines required fields (`category`, `scenario`, `reasoning`, `outcome`) and constraints. `handle_record_decision` validates against this schema before calling `graph.record_decision`, ensuring confidence values are between 0 and 1 and date strings follow ISO‑8601 format.

### Can decisions be linked to other entities in the ContextGraph?

Yes. Decisions are standard graph nodes and can be connected to any other entity—such as projects, people, or documents—using the general **`add_relationship`** tool. This enables full traceability from a decision to its supporting evidence and downstream impacts without requiring specialized handlers for each link type.

### What method enables semantic search for similar past decisions?

Use **`handle_find_precedents`** (lines 110‑119), which forwards the scenario text to `graph.find_similar_decisions`. This hybrid similarity search retrieves historically relevant decisions even when phrasing differs from the current query, supporting precedent-based reasoning workflows.