Designing Memory Schemas

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

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

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 evolves, the new event extends the original.

Links create a connected graph instead of isolated facts. Connected knowledge ranks higher in retrieval and gives agents richer context.

Next