Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Store Event

Record a knowledge event in your wisdom graph.

POST/v1/events— Store a knowledge event

Authentication

All requests require an Authorization: Bearer <agent-secret> header.

Request Body

NameTypeStatusDefaultDescription
graph_idstringrequired—Target graph ID.
event_kindstringrequired—Event kind. One of "fact", "action", "decision", "observation", "feedback".
sourcestringoptional—Event source. One of "agent", "user", "system", "validator", "executor".
context_idstringoptional—Primary context in "type:name" format.
payloadobjectrequired—Event payload. Max 256KB.
reinforcesstring[]optional—Context IDs this event reinforces. Max 50.
extendsstring[]optional—Context IDs this event extends. Max 50.
contradictsstring[]optional—Context IDs this event contradicts. Max 50.
related_tostring[]optional—Related context IDs. Max 50.
timestampstringoptional—Unix timestamp. Defaults to current time.

The total number of link IDs across reinforces, extends, contradicts, and related_to must not exceed 100.

Response

200Success
{
  "event_id": "locus_abc123",
  "status": "recorded",
  "relevance": "high"
}
  • status — "recorded" (event stored) or "filtered" (event discarded by relevance filter).
  • relevance — "high", "medium", or "low".

Examples

curl

curl -X POST https://api.locusgraph.com/v1/events \
  -H "Authorization: Bearer <agent-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "graph_id": "graph_01",
    "event_kind": "fact",
    "context_id": "skill:react_hooks",
    "payload": {
      "topic": "react_hooks",
      "value": "useCallback prevents unnecessary re-renders by memoizing callback references"
    },
    "reinforces": ["skill:react_performance"]
  }'

TypeScript

import { LocusGraph } from "@locusgraph/sdk";
 
const locus = new LocusGraph({ agentSecret: process.env.LOCUS_SECRET });
 
const result = await locus.storeEvent({
  graphId: "graph_01",
  eventKind: "fact",
  contextId: "skill:react_hooks",
  payload: {
    topic: "react_hooks",
    value: "useCallback prevents unnecessary re-renders by memoizing callback references",
  },
  reinforces: ["skill:react_performance"],
});
 
console.log(result.eventId); // "locus_abc123"

Python

from locusgraph import LocusGraph
 
locus = LocusGraph(agent_secret=os.environ["LOCUS_SECRET"])
 
result = locus.store_event(
    graph_id="graph_01",
    event_kind="fact",
    context_id="skill:react_hooks",
    payload={
        "topic": "react_hooks",
        "value": "useCallback prevents unnecessary re-renders by memoizing callback references",
    },
    reinforces=["skill:react_performance"],
)
 
print(result.event_id)  # "locus_abc123"

Related

Retrieve Memories
Event Kinds