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

Retrieve Memories

Run a semantic search over stored knowledge in your wisdom graph.

POST/v1/memories— Semantic search over stored knowledge

Authentication

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

Request Body

NameTypeStatusDefaultDescription
querystringrequired—Search query for semantic matching.
graph_idstringrequired—Graph to search.
limitintegeroptional—Max results to return.
context_idsstring[]optional—Filter by specific context IDs.
context_typesobjectoptional—Filter by context types. A map of type to name arrays, e.g. {"skill": ["react", "rust"]}.
include_idsbooleanoptional—Include locus IDs in the response.

Response

200Success
{
  "memories": "Formatted memory text with relevant knowledge...",
  "items_found": 5
}
  • memories — Formatted text containing the relevant knowledge matching your query.
  • items_found — Number of matching items found.

Examples

curl

curl -X POST https://api.locusgraph.com/v1/memories \
  -H "Authorization: Bearer <agent-secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How should I handle React state management?",
    "graph_id": "graph_01",
    "limit": 10,
    "context_types": {
      "skill": ["react", "state_management"]
    }
  }'

TypeScript

import { LocusGraph } from "@locusgraph/sdk";
 
const locus = new LocusGraph({ agentSecret: process.env.LOCUS_SECRET });
 
const result = await locus.retrieveMemories({
  query: "How should I handle React state management?",
  graphId: "graph_01",
  limit: 10,
  contextTypes: { skill: ["react", "state_management"] },
});
 
console.log(result.memories);
console.log(result.itemsFound); // 5

Python

from locusgraph import LocusGraph
 
locus = LocusGraph(agent_secret=os.environ["LOCUS_SECRET"])
 
result = locus.retrieve_memories(
    query="How should I handle React state management?",
    graph_id="graph_01",
    limit=10,
    context_types={"skill": ["react", "state_management"]},
)
 
print(result.memories)
print(result.items_found)  # 5

Related

Generate Insights
Store Event