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

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 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 (lines 23‑41). This function validates incoming payloads against the RECORD_DECISION schema defined in 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).

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

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.

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.
• 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 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 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 (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.

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