Session Context

Capture tribal knowledge about a device — issues, root causes, resolutions, and helpful commands — and surface it on connect and to the AI assistant.

Overview

Session Context is NetStacks' tribal-knowledge layer. Each context entry records a structured piece of operational knowledge about a device: the issue you ran into, its root cause, how you resolved it, the commands that helped, and a related ticket reference. When you (or a teammate) connect to that device again, the saved context is surfaced so nobody has to relearn what was already figured out.

What a context entry contains

Issue / Topic (required) -- a brief description of the issue or topic, e.g. "Intermittent packet loss on e1/0"
Root Cause -- what caused the issue, if known
Resolution -- how it was fixed or addressed
Helpful Commands -- one command per line, useful for diagnosing or fixing this issue
Ticket Reference -- a related ticket number, e.g. JIRA-1234 or INC12345

Every entry also records the author and created / updated timestamps automatically.

Context vs recording

Session context captures the semantic knowledge -- what the issue was and how it was resolved. Session recording captures the full terminal output for replay. They complement each other: use context for quick, searchable knowledge and recording for a detailed, replayable audit trail.

How It Works

Context is authored manually -- either by an engineer using the context editor, or by the AI assistant when you ask it to record a finding. NetStacks does not silently scrape commands or diff configs to generate context automatically; entries exist because someone deliberately wrote them down.

Where context is created

The context editor -- a panel titled Device Context with an + Add Context button. You fill in the issue, root cause, resolution, commands, and ticket reference, then save.
The AI assistant -- the assistant has an add_session_context tool. When you tell it something like "the SFP was bad, I replaced it and the errors cleared," it can save that as a context entry on your behalf.

How context is surfaced

When you open a session to a device that already has context, NetStacks shows a proactive popup titled Team Knowledge Available. It previews the most recent entry (author plus the issue line and any ticket badge) and offers Ask AI about this and, when more than one entry exists, View all. Entries are always returned newest-first.

Standalone vs Enterprise

Session context works in both deployment modes. The data model and wire shapes are identical; only where the data lives differs.

Mode	Keyed by	Stored by	Sharing
Standalone	Session	The local agent	Local to your install
Enterprise (Controller)	Device	The Controller	Shared org-wide for that device

In standalone mode, context is session-keyed and stored by the local agent at /sessions/{session_id}/context. In enterprise mode, the Controller exposes a device-keyed variant at /devices/{device_id}/context so an entry is shared across everyone with access to that device. The terminal talks to either backend without client-side rewriting, so the same editor and AI tools work in both modes.

Same UI, both modes

You don't choose a mode in the UI -- the context editor targets a session id in standalone and a device id in enterprise automatically. Write context the same way in both.

Adding and Viewing Context

Add a context entry

Connect to the device in the terminal.
Open the Device Context panel and click + Add Context.
Fill in Issue / Topic (required). Optionally add Root Cause, Resolution, Helpful Commands (one per line), and a Ticket Reference.
Click Add Context. The entry is saved with your username as the author and appears at the top of the list.

View, edit, or delete context

Open the Device Context panel. Entries are listed newest-first, each showing the issue line, author, date, and any ticket badge.
Click an entry that has details to expand its root cause, resolution, and commands.
Use Edit to revise any field, or Delete to remove the entry.

On connect

If the device already has context, the Team Knowledge Available popup appears when the session opens. Click Ask AI about this to send the entry to the assistant, View all to open the full list, or dismiss it.

Write context after every fix

The best time to record context is right after you resolve something. A 30-second entry -- issue, root cause, resolution -- saves the next engineer (often future-you) from rediscovering it.

AI Integration

When an AI chat surface has an active device session, NetStacks appends a DEVICE CONTEXT block to the model's system prompt, summarizing the most recent entries (issue, root cause, resolution, commands, ticket). This gives the assistant continuity across sessions without you re-explaining history.

ai-prompt-block.txttext

DEVICE CONTEXT (team/tribal knowledge for this device — past issues and how they were resolved):
- Issue: Intermittent packet loss on e1/0
  Root cause: Failing SFP module
  Resolution: Replaced SFP in slot 1/0/24, errors cleared
  Commands: show interfaces e1/0; show interfaces transceiver detail
  Ticket: INC12345
- Issue: BGP neighbor 10.0.0.2 flapping
  Root cause: MTU mismatch on the PE-facing link
  Resolution: Set MTU to 9216 on both ends
  Ticket: CHG0012345

The assistant also has two tools it can call directly:

add_session_context -- save a new entry. Parameters: session_id and issue (required), plus optional root_cause, resolution, commands (one per line), and ticket_ref.
list_session_context -- retrieve all saved entries for the active session/device. Parameter: session_id.

A typical exchange where the assistant records knowledge for you:

ai-add-context.txttext

You:  The packet loss on e1/0 was a bad SFP. Swapped it in slot 1/0/24
      and the input errors stopped. Tracking it under INC12345.

AI:   Got it — I'll save that to this device's context so the team has it.
      [calls add_session_context with issue="Intermittent packet loss on e1/0",
       root_cause="Failing SFP module",
       resolution="Replaced SFP in slot 1/0/24, errors cleared",
       ticket_ref="INC12345"]
      Saved. Next time anyone connects, this will show up under Team Knowledge.

API Reference

Context is served by the agent (standalone) or the Controller (enterprise) over the same endpoint shapes. Entries are returned sorted by created_at descending (newest first).

Endpoints

Method	Path	Purpose
GET	`/sessions/{id}/context`	List entries for a session (standalone)
POST	`/sessions/{id}/context`	Create an entry for a session
GET	`/devices/{id}/context`	List entries for a device (enterprise)
POST	`/devices/{id}/context`	Create an entry for a device
GET	`/context/{id}`	Get a single entry
PUT	`/context/{id}`	Update an entry
DELETE	`/context/{id}`	Delete an entry

List context (response shape)

list-context.jsonjson

GET /sessions/{session_id}/context

[
  {
    "id": "ctx_001",
    "session_id": "ssh-9f1c-1734274200",
    "issue": "BGP neighbor 10.0.0.2 flapping",
    "root_cause": "MTU mismatch on the PE-facing link",
    "resolution": "Set MTU to 9216 on both ends",
    "commands": "show ip bgp summary\nshow interfaces e1/0 | include MTU",
    "ticket_ref": "CHG0012345",
    "author": "jsmith",
    "created_at": "2026-06-15T14:30:00Z",
    "updated_at": "2026-06-15T14:30:00Z"
  }
]

Create a context entry

Only issue and author are required; session_id is taken from the path. commands is a single string with one command per line.

create-context.jsonjson

POST /sessions/{session_id}/context
Content-Type: application/json

{
  "issue": "Intermittent packet loss on e1/0",
  "root_cause": "Failing SFP module",
  "resolution": "Replaced SFP in slot 1/0/24, errors cleared",
  "commands": "show interfaces e1/0\nshow interfaces transceiver detail",
  "ticket_ref": "INC12345",
  "author": "mike"
}

The device-keyed variant is identical apart from the path:

create-device-context.jsonjson

POST /devices/{device_id}/context
Content-Type: application/json

{
  "issue": "Fan tray 2 reporting failure after firmware upgrade",
  "root_cause": "Known sensor false-positive on this NOS build",
  "resolution": "Cleared after reseat; RMA not required",
  "ticket_ref": "JIRA-4821",
  "author": "dana"
}

Update an entry

Send only the fields you want to change; nullable fields (root_cause, resolution, commands, ticket_ref) can be set to null to clear them.

update-context.jsonjson

PUT /context/{context_id}
Content-Type: application/json

{
  "resolution": "SFP replaced; confirmed clean over 72h, closing ticket",
  "ticket_ref": "INC12345"
}

Q&A

Q: What fields make up a session context entry?: A: Issue / Topic (required), Root Cause, Resolution, Helpful Commands (one per line), and a Ticket Reference. NetStacks also records the author and created/updated timestamps automatically.

Q: Is context generated automatically from my sessions?: A: No. Context is authored deliberately -- either by an engineer in the Device Context editor or by the AI assistant via its add_session_context tool. NetStacks does not silently scrape commands or diff configs to create entries.

Q: Does session context work without a Controller?: A: Yes. In standalone mode context is session-keyed and stored by the local agent. In enterprise mode the Controller stores it device-keyed and shares it org-wide. The editor and AI tools are the same in both.

Q: How does context reach the AI assistant?: A: When a chat surface has an active device session, NetStacks appends a DEVICE CONTEXT block (the most recent entries) to the system prompt. The assistant can also call list_session_context to read them all and add_session_context to save new ones.

Q: What shows up when I connect to a device with context?: A: A "Team Knowledge Available" popup previews the most recent entry and offers "Ask AI about this" plus "View all" when there is more than one entry.

Q: How do I clear a field on an existing entry?: A: PUT to /context/{id} with the field set to null. Root cause, resolution, commands, and ticket reference are nullable; issue is required and cannot be cleared.

Troubleshooting

No context appears for a device

Context exists only after someone writes an entry -- a device with no saved entries will show an empty "No context yet" state, not auto-generated data.
In enterprise mode, confirm you can reach the Controller and that you have access to the device; device-keyed context is shared per-device access.

The "Team Knowledge Available" popup didn't show

The popup only appears when at least one context entry exists for the device you connected to.
If you dismissed it, reopen the Device Context panel to view all entries directly.

Commands look run together in the AI prompt

The Helpful Commands field is one command per line. When inlined into the AI prompt, newlines are joined with semicolons -- enter each command on its own line so it stays readable.

An entry won't save

Issue / Topic is required. The save button stays disabled until it has a value.

Session Recording -- capture full terminal output for replay and audit
AI Chat -- the assistant that reads and writes session context
Command Suggestions -- AI suggestions informed by device context
Session Sharing -- collaborate live on a session
Adding Devices -- manage the devices that accumulate context