Contexts & Graphs

Contexts and graphs are how LocusGraph organizes structured agent knowledge. Graphs isolate workspaces. Contexts group related learnings inside a workspace.

Why Scope Matters

An agent that retrieves everything from one big bucket gets noise. An agent that retrieves from a tight, well-shaped scope gets validated knowledge it can actually use. Graphs and contexts are the two scoping layers that make that possible.

Graph IDs

A graph is a top-level workspace for structured agent knowledge. Each graph is fully isolated — knowledge in one graph cannot be retrieved from another.

Use separate graphs for:

• Different projects
• Different teams
• Different agents
• Production vs. staging environments

Pass graph_id when initializing the client or on each API call. The default value is "default".

Context IDs

Context IDs group related knowledge within a graph. They follow a type:name format:

skill:react_best_practices
session:20250319_ab3f
project:locusgraph_docs
task:onboarding_flow

The type prefix (before the colon) lets you query all contexts of a given type. For example, retrieve all skill: contexts to see every skill the agent has graduated across the graph.

Format Rules

These are all valid:

skill:error_handling
session:2025-03-19_morning
project:my-api
user:preferences

These are normalized:

skill:React Best Practices   -> skill:react_best_practices
MY_SKILL:Testing             -> my_skill:testing

Common Context Types

The type prefix serves as a namespace. These are conventions, not enforced categories — but staying close to them keeps retrieval predictable.

Scoping in Practice

When storing an event, pass context_id to attach it to a context:

{
  "event_kind": "fact",
  "source": "agent",
  "context_id": "skill:react_best_practices",
  "payload": { "topic": "hooks", "value": "prefer useReducer for complex state" }
}

When retrieving, filter by context to narrow results:

{
  "query": "state management",
  "context_id": "skill:react_best_practices",
  "limit": 10
}

Graph Strategy

Next