FAQ & Troubleshooting

Direct answers to the most common LocusGraph questions.

General

How do I get an agent secret?

Sign up at locusgraph.com and create an agent from the dashboard. Each agent receives a unique secret.

What is the difference between a graph and a context?

A graph is an isolated workspace -- like a database. A context is a label within a graph -- like a table. One graph can hold thousands of contexts.

Can multiple agents share the same graph?

Yes. Use different context prefixes per agent role (e.g., agent:planner, agent:coder) and filter with context_types during retrieval.

Storing Knowledge

Why was my event filtered?

LocusGraph's admission pipeline filters routine and noise events. Events with kind routine, heartbeat, status, noise, debug, or log are typically filtered. Use fact, action, decision, observation, or feedback instead.

Is there a size limit for payloads?

Yes -- 256KB per event payload. Keep payloads focused and flat.

What happens when two pieces of knowledge contradict each other?

The contradicts link reduces the target's confidence by 0.10 (floor 0.2). Lower-confidence knowledge ranks lower in retrieval results. The newer information effectively overrides the old.

Retrieving Knowledge

How do I scope retrieval to specific knowledge?

Use the context_ids or context_types filters in retrieve_memories. Example:

contextTypes: { skill: ["react", "typescript"] }

This retrieves only from those specific contexts.

Connectivity

The SDK cannot connect -- what do I check?

1. LOCUSGRAPH_AGENT_SECRET is set and valid.
2. LOCUSGRAPH_SERVER_URL is correct (default: https://api.locusgraph.com).
3. Your network or firewall allows outbound HTTPS on port 443.

Next