Event Kinds
Event kinds tell LocusGraph what type of agent knowledge you are storing. The kind drives how it gets typed, linked, scored, and graduated.
Why Kinds Matter
A vector store treats all text the same. Structured Agent Knowledge does not. A decision is not the same as an observation. A feedback from the user has more weight than an observation from the agent. The kind is what lets LocusGraph route an event correctly through admission and into the right place on the graduation plane.
Primary Kinds
fact
Aliases: knowledge, learned
Persistent knowledge that remains true over time. Use for preferences, configurations, and learned truths the agent should keep.
"The user prefers dark mode." / "The API rate limit is 1000 req/min."
action
Aliases: task, operation, execution, completed
Something happened. A task was performed or a process completed.
"Deployed version 2.3." / "Sent the weekly report."
decision
Aliases: choice, selection, determination
A choice was made with reasoning. Records the what and the why so future agents can build on it instead of re-deciding.
"Selected PostgreSQL over MySQL for JSONB support."
observation
General notes and impressions. The default kind for unclassified events.
"Build times increased after adding the new dependency."
feedback
Opinions, ratings, or suggestions from users. Carries subjective weight that influences ranking.
"User rated the response 4/5." / "User suggested shorter summaries."
Special Kinds
constraint / rule / constraint_violation
Validation-related events. When a constraint_violation is stored, a derived_from link is auto-created to the source context.
routine / heartbeat / status
Mapped to routine_operation. Filtered from standard retrieval. Use for health checks and lifecycle tracking.
noise / debug / log
Mapped to noise. Filtered from retrieval entirely. Exists for audit only.
Kind-to-Internal Mapping
| Input Kind | Internal Type | Retrievable |
|---|---|---|
fact, knowledge, learned | knowledge_recorded | Yes |
action, task, operation, execution, completed | action_completed | Yes |
decision, choice, selection, determination | decision_made | Yes |
observation | knowledge_recorded | Yes |
feedback | knowledge_recorded | Yes |
constraint, rule, constraint_violation | knowledge_recorded | Yes |
routine, heartbeat, status | routine_operation | No |
noise, debug, log | noise | No |
When in doubt, use fact for things that are true and observation for things you noticed. The admission pipeline handles the rest, including which events feed the event → pattern → skill graduation chain.
Picking the Right Kind
| You want to record... | Use kind |
|---|---|
| A stable truth that should persist forever | fact |
| An execution that happened | action |
| A choice made and why | decision |
| A pattern noticed during work | observation |
| A user opinion or rating | feedback |
| A failed validation or rule trigger | constraint_violation |