Memories & Events
Events are the atomic unit of structured agent knowledge. Every learning enters LocusGraph as an event and graduates from there.
Why Events, Not Messages
Most "agent memory" systems append messages to a chat log and retrieve similar text. LocusGraph treats every learning as a structured event with a kind, a source, a payload, a context, and links — so it can be admitted, scored, and graduated into a skill instead of just remembered.
Event Shape
An event is a single piece of agent experience submitted to LocusGraph. Each event has shape:
| Field | Required | Description |
|---|---|---|
event_kind | Yes | The type of knowledge: fact, action, decision, observation, feedback |
source | Yes | Who created it: agent, user, system, validator, executor |
payload | Yes | JSON object containing the actual knowledge |
context_id | No | Scope the event to a context (e.g., skill:react_best_practices) |
links | No | Connections to other loci or contexts |
That structure is what separates LocusGraph from a vector blob store.
From Event to Locus
Events do not land in the graph as raw text. They pass through the admission pipeline, which validates, classifies, extracts topics, and creates a permanent locus in your structured agent knowledge graph.
A locus is the graph-native representation of admitted knowledge. Once created, it participates in retrieval, linking, and confidence scoring. This is the first step that turns recall into understanding.
Kind Mapping
Raw event kinds map to internal types during admission:
| Input Kind | Internal Type |
|---|---|
fact, knowledge, observation | knowledge_recorded |
action, task | action_completed |
decision, choice | decision_made |
routine, heartbeat, status | routine_operation (filtered) |
noise, debug, log | noise (filtered) |
Events classified as routine_operation or noise are recorded but excluded from standard retrieval. They exist for audit purposes only.
Events Become Patterns Become Skills
This is the core graduation chain in LocusGraph:
event -> pattern -> skillA single event is data. Repeated events linked together with reinforces become a pattern with rising confidence. Patterns that keep proving useful graduate into skills the agent can retrieve in future work.
You do not have to manage this manually. Linking the right events at admission is enough — confidence scoring and retrieval handle the rest.
Retrieval
When you call retrieveMemories, LocusGraph searches across admitted loci, not raw events. Queries are matched against topics, payload content, and graph connections, then ranked by relevance and confidence. Only validated knowledge gets brought to the forefront.