Context Graphs

SenseLab doesn’t just store what agents know — it captures why they acted. Every read, write, tool consultation, and outcome forms a decision trace that becomes searchable precedent.

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?
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. But the reasoning that connected data to action was never treated as data in the first place.

Decision Traces

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

Agent reads SenseLab entries:
  checkout-service/retry-pattern (v3, confidence: 0.92)
  checkout-service/risk-race-condition (v1, confidence: 0.78)

Agent consults external sources:
  incident tracker → 3 SEV-1 incidents in last 24h
  git log → 15 commits since last deploy, 3 touching retry logic

Agent writes decision:
  checkout-service/decision-rollback-retry → "Rolling back retry changes due to
  incident correlation and high-risk signal from prior agent"

Outcome recorded:
  DEP-500 → success → confidence on causal entries adjusted

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 happened next

Outcomes close the feedback loop. Confidence on causal entries adjusts automatically:

mem.commit_outcome("DEP-500", OutcomeType.SUCCESS)

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

checkout-service/retry-pattern
    ├── read by deploy-agent (sess-a1b2)
    │   ├── also consulted: incident tracker, git log
    │   ├── wrote: decision-rollback-retry
    │   └── outcome: DEP-500 (success) → confidence reinforced
    │
    ├── read by review-agent (sess-e5f6)
    │   ├── also consulted: error tracker
    │   ├── wrote: risk-timeout-regression
    │   └── outcome: INC-1042 (critical_failure) → confidence eroded
    │
    └── read by onboard-agent (sess-g7h8)
        └── wrote: task-summary-retry-review

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

SenseLab now has a persisted knowledge graph that 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:

Agent makes decision → writes entry + records trace
                           │
                           ▼
                   Outcome occurs (deploy, incident)
                           │
                           ▼
                   Confidence adjusts on causal entries
                           │
                           ▼
                   Next agent sees high-confidence precedent
                           │
                           ▼
                   Agent makes better decision → new trace

Entries that led to good outcomes are reinforced and decay slower; entries correlated with incidents lose confidence and sink out of results. The system learns which decisions lead to good outcomes without any explicit training.

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
`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
`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
`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_search("checkout-service")           → find existing context
amfs_read("checkout-service", "pattern")  → read relevant entries (auto-tracked)
amfs_record_context("git-log", "...", "git")  → capture tool inputs
amfs_write("checkout-service", "decision-...", "...")  → record the decision
amfs_commit_outcome("DEP-500", "success")  → close the loop
amfs_explain("DEP-500")                   → inspect the full trace

No manual instrumentation required. The causal chain builds itself from normal agent workflow.

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 happened next

5. 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 happened next

​5. 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 happened next

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