Context Graphs

SenseLab doesn’t just store what agents know — it records how they used it. Every read, external input, action, failed attempt and outcome in a run forms a decision trace. The trace is the raw material of the loop: it is what an outcome is credited against, what the briefing is compiled from, what judges grade, and what a model is eventually trained on. One record, four jobs.

The Problem

AI agents are stateless. Each session starts from scratch with no memory of past decisions, patterns, or mistakes. When something goes wrong, there’s no way to answer:

What information did the agent have when it decided?
What external sources did it consult, and what did it do?
Has a similar decision been made before, and what happened?

Traditional systems of record (CRMs, ERPs, ticketing systems) store the final state — the deal was closed, the ticket was resolved, the deploy succeeded. The reasoning that connected data to action was never treated as data, so nothing could learn from it.

Decision Traces

A decision trace is a structured record of how an agent turned context into action:

A decision trace in four layers: what the agent knew, what it consulted, what it decided, and what happened

This trace is queryable. The next agent — or a human auditor — can replay exactly what happened and why.

How SenseLab Captures Decision Traces

SenseLab’s existing primitives map directly to each component of a decision trace:

1. What the agent knew

Every read() call is automatically logged by the ReadTracker. When the agent later commits an outcome, SenseLab knows exactly which entries informed the decision.

entry = mem.read("checkout-service", "retry-pattern")
entry = mem.read("checkout-service", "risk-race-condition")

2. What external inputs were gathered

record_context() captures tool calls, API responses, and other external inputs without writing to storage. These appear in the causal chain alongside SenseLab reads.

mem.record_context(
    "open-incidents",
    "3 SEV-1 incidents in last 24h for checkout-service",
    source="incident tracker",
)

mem.record_context(
    "git-log",
    "15 commits since last deploy, 3 touching retry logic",
    source="git",
)

3. What the agent decided

The agent’s decision is written as a versioned, provenanced entry:

mem.write(
    "checkout-service",
    "decision-rollback-retry",
    "Rolling back retry changes due to incident correlation",
    confidence=0.9,
    memory_type=MemoryType.EXPERIENCE,
    pattern_refs=["checkout-service/retry-pattern"],
)

4. What the agent did

Consequential actions — deploys, rollbacks, edits, refunds — are recorded as they happen, failures included. When a remembered approach did not work, the attempt is closed before the next one starts, so the entries behind it receive the failure rather than the credit for the recovery:

mem.record_action("deploy_rollback", {"service": "checkout", "to_version": "v41"})
mem.record_attempt(summary="restarted worker per runbook; queue still stuck")

5. What happened next

The outcome closes the loop. Confidence moves on the causal entries, and the request and the answer travel with the trace so a judge can grade the run later:

mem.commit_outcome(
    "DEP-500", OutcomeType.SUCCESS,
    task_input="deploy checkout v2.14 safely",
    response_text="Rolled back the retry change first; deploy clean.",
    verified_by="ci",
)

6. Why did we do that?

explain() returns the complete causal chain:

chain = mem.explain("DEP-500")

Returns:

{
  "outcome_ref": "DEP-500",
  "agent_id": "deploy-agent",
  "session_id": "sess-a1b2c3d4",
  "causal_chain_length": 2,
  "causal_entries": [
    {"entity_path": "checkout-service", "key": "retry-pattern", "confidence": 0.92, "...": "..."},
    {"entity_path": "checkout-service", "key": "risk-race-condition", "confidence": 0.78, "...": "..."}
  ],
  "external_contexts": [
    {"label": "open-incidents", "summary": "3 SEV-1 incidents in last 24h", "source": "incident tracker", "recorded_at": "..."},
    {"label": "git-log", "summary": "15 commits since last deploy, 3 touching retry logic", "source": "git", "recorded_at": "..."}
  ]
}

From Traces to Graphs

Individual decision traces accumulate into a context graph: entities connected by decision events with “why” links.

A context graph: one entry read by three agent sessions, each with what else it consulted, what it wrote, and how its outcome fed back into confidence

Over time, this graph captures institutional knowledge that no single agent or person holds:

Precedent — “The last time we saw this pattern, we rolled back and it worked.”
Exception logic — “We always check for open incidents before deploying changes to retry logic.”
Cross-system synthesis — “The decision combined SenseLab memory, open incidents, and git history.”

The Knowledge Graph

A persisted knowledge graph complements the session-scoped decision trace. The two layers serve different purposes:

Layer	Scope	Storage	Purpose
Decision traces	Single session	Stored per session; Pro adds a cryptographically sealed copy	”What happened in this session and why?”
Knowledge graph	Cross-session, cross-agent	A persistent edge store spanning every agent on the account	”How are entities, agents, and outcomes related globally?”

Both layers are always on — the graph materializes from normal reads and writes, and traces are recorded as agents work. Neither needs to be enabled or configured.

How Edges Are Created

The knowledge graph is populated automatically — no manual graph construction needed:

Trigger	Edge created	Example
`write(pattern_refs=["x"])`	`entry → references → x`	`checkout-service/retry-pattern → references → shared/backoff-strategy`
`commit_outcome()`	`entry → informed → outcome`	`checkout-service/retry-pattern → informed → DEP-500`
`commit_outcome()`	Co-occurrence edges between causal entries	`retry-pattern → co_occurs_with → risk-race-condition`
`read_from(agent_id)`	`this_agent → learned_from → other_agent`	`deploy-agent → learned_from → review-agent`

Each edge carries confidence, evidence_count, first_seen, and last_seen. Repeated materializations increment the evidence count rather than creating duplicate edges.

Querying the Graph

Agents can explore the knowledge graph via the SDK or MCP:

edges = mem.graph_neighbors(
    "checkout-service/retry-pattern",
    direction="outgoing",
    depth=2,
)
for edge in edges:
    print(f"{edge.source_entity} --{edge.relation}--> {edge.target_entity} "
          f"(confidence={edge.confidence}, evidence={edge.evidence_count})")

Via MCP:

amfs_graph_neighbors(
    entity="checkout-service/retry-pattern",
    direction="both",
    depth=2,
)

The Memory Cortex also compiles CONNECTION_MAP digests from graph edges, surfacing the most important relationships for an entity during amfs_briefing().

The Feedback Loop

Decision traces compound through SenseLab’s outcome system:

Entries that led to good outcomes are reinforced and decay slower; entries correlated with failures lose confidence and sink out of results. The system learns which decisions lead to good outcomes without any explicit training. The same traces feed the two slower loops. Behavior grades them with judges, opens an incident when a failure recurs, and proposes a fix to the learning itself — tested by replaying the failing traces against the fixed memory before it ships. Managed Models take the traces whose outcomes were good as a labelled training set. Both improve what the next run starts from, which is what makes the improvement recursive.

Enriched Decision Traces

When commit_outcome() is called, SenseLab automatically captures a rich snapshot of the session:

mem.read("checkout-service", "retry-pattern")
mem.search(entity_path="checkout-service", min_confidence=0.5)
mem.record_context("open-incidents", "No active incidents", source="incident tracker")
mem.write("checkout-service", "deploy-v2.14", {"version": "2.14.0"})

mem.commit_outcome("DEP-500", OutcomeType.SUCCESS,
                    decision_summary="Deployed after verifying retry pattern")

The resulting trace includes:

Field	Description
`task_input` / `response_text`	The request as it arrived and the answer the agent gave — what a judge grades
`causal_entries`	Full snapshots of every read entry (value, memory_type, written_by, read_at, duration_ms)
`external_contexts`	All `record_context()` calls with timestamps
`tool_calls` / `llm_calls`	Actions the agent took, and the model calls behind them with tokens, cost and latency
`attempts`	Each approach that was tried and marked as failed before the next
`query_events`	Every `search()` and `list()` call with parameters, result counts, and per-operation latency
`error_events`	Any errors during reads, writes, or tool calls
`state_diff`	Entries created, entries updated, and detailed confidence changes
`attributes` / environment	The dimensions a run is filtered by (customer, task type…) and the model, agent version and runtime it ran on
`session_started_at` / `session_ended_at` / `session_duration_ms`	Session timing
`decision_summary`	Optional human-readable summary

Per-Agent Memory Graph

SenseLab tracks which agents interact with which entities, enabling per-agent memory views:

GET /api/v1/agents                              → list all agents
GET /api/v1/agents/{agent_id}/memory-graph       → agent's entity relationships
GET /api/v1/agents/{agent_id}/activity           → timeline of writes and outcomes

The agent memory graph shows every entity an agent has read from or written to, with entry counts and relationship types — giving you a complete picture of any agent’s knowledge footprint.

Immutability and Replay

Because SenseLab uses Copy-on-Write versioning, decision traces are immutable. You can reconstruct the exact state of the world at any past decision point:

from datetime import datetime, timezone

decision_time = datetime(2026, 3, 15, 14, 30, tzinfo=timezone.utc)

versions = mem.history(
    "checkout-service",
    "retry-pattern",
    until=decision_time,
)

state_at_decision = versions[-1] if versions else None

This is the difference between a system of record (stores the current state) and a context graph (stores the decision lineage). SenseLab preserves both.

Immutable Decision Trace Store

SenseLab extends the traces in SenseLab Open Source with cryptographic guarantees and advanced telemetry:

HMAC-SHA256 signing — every trace is signed with content_hash and chained to the previous trace via parent_hash, forming a Merkle chain that detects tampering
LLM call spans — record model, provider, prompt/completion tokens, cost, latency, temperature, and finish reason for every LLM call during a session
Write events, tool calls, agent interactions — full audit trail of every action
OpenTelemetry export — export traces as OTel spans following GenAI semantic conventions, compatible with Jaeger, Grafana Tempo, Datadog, and Honeycomb
Auto entity extraction — LLM-powered extraction of entities (services, people, tools) and relationships (depends_on, uses, manages) from trace data
Immutability enforcement — updates and deletes are blocked at the storage layer, so a sealed trace cannot be edited or removed even by an administrator

MCP Integration

Via the MCP server, AI coding agents can build decision traces automatically:

amfs_briefing("checkout-service")                → what is already known, evidence-ranked
amfs_read("checkout-service", "pattern")         → read relevant entries (auto-tracked)
amfs_record_context("git-log", "...", "git")     → capture tool inputs
amfs_record_action("deploy_rollback", {...})     → record what was done
amfs_record_attempt(summary="...")               → close an approach that did not work
amfs_write("checkout-service", "decision-...", "...")  → record the decision
amfs_commit_outcome("DEP-500", "success", task_input=..., response_text=...)  → close the loop
amfs_explain("DEP-500")                          → inspect the full trace

The causal chain builds itself from the normal workflow. To add nested steps, LLM calls and cost from an agent you run yourself, see Instrument your agent.

Product

Getting Started

Guides

Self-Hosting

Core Concepts

Pro Features

The Problem

Decision Traces

How SenseLab Captures Decision Traces

1. What the agent knew

2. What external inputs were gathered

3. What the agent decided

4. What the agent did

5. What happened next

6. Why did we do that?

From Traces to Graphs

The Knowledge Graph

How Edges Are Created

Querying the Graph

The Feedback Loop

Enriched Decision Traces

Per-Agent Memory Graph

Immutability and Replay

Immutable Decision Trace Store

MCP Integration

​The Problem

​Decision Traces

​How SenseLab Captures Decision Traces

​1. What the agent knew

​2. What external inputs were gathered

​3. What the agent decided

​4. What the agent did

​5. What happened next

​6. Why did we do that?

​From Traces to Graphs

​The Knowledge Graph

​How Edges Are Created

​Querying the Graph

​The Feedback Loop

​Enriched Decision Traces

​Per-Agent Memory Graph

​Immutability and Replay

​Immutable Decision Trace Store

​MCP Integration

The Problem

Decision Traces

How SenseLab Captures Decision Traces

1. What the agent knew

2. What external inputs were gathered

3. What the agent decided

4. What the agent did

5. What happened next

6. Why did we do that?

From Traces to Graphs

The Knowledge Graph

How Edges Are Created

Querying the Graph

The Feedback Loop

Enriched Decision Traces

Per-Agent Memory Graph

Immutability and Replay

Immutable Decision Trace Store

MCP Integration