Generate Insights

Reason over your Structured Agent Knowledge to surface patterns and recommendations. This is where validated knowledge is synthesized into something the agent can act on — not just retrieved.

POST/v1/memories/insights— Generate insights by reasoning over stored knowledge

Authentication

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

Request Body

Name	Type	Status	Default	Description
`task`	`string`	required	—	The question or task to reason about.
`graph_id`	`string`	required	—	Graph to reason over.
`locus_query`	`string`	optional	—	Search query for relevant knowledge. Defaults to the `task` value.
`limit`	`integer`	optional	—	Max memories to consider. Default `5`.
`context_ids`	`string[]`	optional	—	Filter by specific context IDs.
`context_types`	`object`	optional	—	Filter by context types. A map of type to name arrays.

When locus_query is omitted, the API uses your task as the search query. Set locus_query separately when your task description is broad but you want to search a specific area of knowledge.

Response

200Success

{
  "insight": "Users consistently prefer dark mode interfaces. Three separate feedback events confirm this.",
  "recommendation": "Set dark mode as the default theme",
  "confidence": "high"
}

insight — A synthesized finding drawn from relevant knowledge.
recommendation — An actionable suggestion based on the insight.
confidence — "high", "medium", or "low".

Examples

curl

curl -X POST https://api.locusgraph.com/v1/memories/insights \
  -H "Authorization: Bearer <agent-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "What UI preferences have users expressed?",
    "graph_id": "graph_01",
    "limit": 10,
    "context_types": {
      "feedback": ["ui", "design"]
    }
  }'

TypeScript

import { LocusGraph } from "@locusgraph/sdk";
 
const locus = new LocusGraph({ agentSecret: process.env.LOCUS_SECRET });
 
const result = await locus.generateInsights({
  task: "What UI preferences have users expressed?",
  graphId: "graph_01",
  limit: 10,
  contextTypes: { feedback: ["ui", "design"] },
});
 
console.log(result.insight);
console.log(result.recommendation);
console.log(result.confidence); // "high"

Python

from locusgraph import LocusGraph
 
locus = LocusGraph(agent_secret=os.environ["LOCUS_SECRET"])
 
result = locus.generate_insights(
    task="What UI preferences have users expressed?",
    graph_id="graph_01",
    limit=10,
    context_types={"feedback": ["ui", "design"]},
)
 
print(result.insight)
print(result.recommendation)
print(result.confidence)  # "high"

Practical Pattern: Identify Recurring Issues

Use insights to detect patterns across error events:

curl -X POST https://api.locusgraph.com/v1/memories/insights \
  -H "Authorization: Bearer <agent-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "What are the most common failure patterns in the last week?",
    "graph_id": "graph_01",
    "locus_query": "error failure crash timeout",
    "limit": 20,
    "context_types": {
      "error": []
    }
  }'

Retrieve Memories

Store Event