> ## Documentation Index > Fetch the complete documentation index at: https://docs.sense-lab.ai/llms.txt > Use this file to discover all available pages before exploring further. # Context Graphs > How AMFS captures decision traces that explain not just what happened, but why. AMFS 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 AMFS entries: checkout-service/retry-pattern (v3, confidence: 0.92) checkout-service/risk-race-condition (v1, confidence: 0.78) Agent consults external sources: PagerDuty API → 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 AMFS Captures Decision Traces AMFS'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, AMFS knows exactly which entries informed the decision. ```python theme={null} 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 AMFS reads. ```python theme={null} mem.record_context( "pagerduty-incidents", "3 SEV-1 incidents in last 24h for checkout-service", source="PagerDuty API", ) 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: ```python theme={null} 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: ```python theme={null} mem.commit_outcome("DEP-500", OutcomeType.SUCCESS) ``` ### 5. Why did we do that? `explain()` returns the complete causal chain: ```python theme={null} chain = mem.explain("DEP-500") ``` Returns: ```json theme={null} { "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": "pagerduty-incidents", "summary": "3 SEV-1 incidents in last 24h", "source": "PagerDuty API", "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: PagerDuty API, git log │ ├── wrote: decision-rollback-retry │ └── outcome: DEP-500 (success) → confidence adjusted │ ├── read by review-agent (sess-e5f6) │ ├── also consulted: Sentry errors │ ├── wrote: risk-timeout-regression │ └── outcome: INC-1042 (critical_failure) → confidence boosted │ └── 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 PagerDuty before deploying changes to retry logic." * **Cross-system synthesis** — "The decision combined AMFS memory, PagerDuty incidents, and git history." *** ## The Knowledge Graph AMFS 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 | In-memory (OSS), Postgres (Pro) | "What happened in this session and why?" | | Knowledge graph | Cross-session, cross-agent | `amfs_knowledge_graph` table (Postgres) | "How are entities, agents, and outcomes related globally?" | ### 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: ```python theme={null} 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 AMFS'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 validated by positive outcomes decay slower. Entries correlated with incidents get boosted. The system learns which decisions lead to good outcomes without any explicit training. *** ## Enriched Decision Traces When `commit_outcome()` is called, AMFS automatically captures a rich snapshot of the session: ```python theme={null} mem.read("checkout-service", "retry-pattern") mem.search(entity_path="checkout-service", min_confidence=0.5) mem.record_context("pagerduty", "No active incidents", source="PagerDuty API") 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 AMFS 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 AMFS uses Copy-on-Write versioning, decision traces are **immutable**. You can reconstruct the exact state of the world at any past decision point: ```python theme={null} 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). AMFS preserves both. ### Pro: Immutable Decision Trace Store Pro extends OSS traces 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** — Postgres RULEs block UPDATE and DELETE on the trace table *** ## MCP Integration Via the MCP server, AI coding agents can build decision traces automatically: ``` 1. amfs_search("checkout-service") → find existing context 2. amfs_read("checkout-service", "pattern") → read relevant entries (auto-tracked) 3. amfs_record_context("git-log", "...", "git") → capture tool inputs 4. amfs_write("checkout-service", "decision-...", "...") → record the decision 5. amfs_commit_outcome("DEP-500", "success") → close the loop 6. amfs_explain("DEP-500") → inspect the full trace ``` No manual instrumentation required. The causal chain builds itself from normal agent workflow.