Designing Memory Schemas

A good schema makes structured agent knowledge discoverable. A bad one buries it.

What "Schema" Means Here

In LocusGraph, the schema is the agreement between your agent and the graph about how knowledge looks: which context types you use, what payload shape every event follows, and how related events get linked. The schema is what lets confidence scoring work and graduation produce real skills instead of disconnected blobs.

Context ID Conventions

Context IDs follow the format type:name. The type groups related knowledge; the name identifies the specific context. Use consistent prefixes across your agent.

Common type prefixes:

Pick a naming convention and stick with it. Snake case works well. Avoid spaces or special characters in names.

Payload Design

Payloads carry the actual knowledge. The simplest pattern uses topic and value fields:

{
  "topic": "useEffect cleanup",
  "value": "Always return a cleanup function when subscribing to external stores"
}

For richer knowledge, use structured objects:

{
  "error_type": "NullPointerException",
  "trigger": "Accessing user.profile before auth check",
  "fix": "Add null guard in middleware",
  "confidence": "high"
}

Schema for a Coding Agent

Here is an example schema for an agent that assists with software development:

• error:null_pointer — stores null reference patterns, triggers, and fixes
• skill:react_hooks — stores graduated best practices, anti-patterns, and learned techniques
• session:2025_03_19 — stores decisions and observations from today's session
• project:auth_module — stores architectural decisions and module-level context

Each context type uses a consistent payload shape. The agent stores events as they occur and retrieves them by type or semantic query. Repeated occurrences in error: and skill: contexts are exactly what graduate into reusable skills.

Hierarchies and Links

Use link arrays (reinforces, extends, contradicts, related_to) to connect knowledge across contexts. When an agent encounters the same error twice, the second event reinforces the first. When a skill graduates from a pattern, the new event extends the original.

Links create a connected graph instead of isolated facts. Connected knowledge gathers confidence faster and graduates from event to pattern to skill — exactly what raises retrieval quality over time.

Schema Smell Test

Before shipping a schema, run through this:

Next