Query Memory

POST/agent/memory/query

Search a volume's memories using semantic similarity. Returns matching memories from vector search plus related knowledge graph facts and document sources.

Request

Headers

Header	Value
Authorization	Bearer sm_live_...
Content-Type	application/json

Body Parameters

querystringrequired

Search query (1–10,000 characters). Natural language works best.

volume_idstring (UUID)required

Volume to search within.

limitinteger

Max results to return (1–50, default: 10).

Response

200 Search results with graph enrichment

{
  "query": "What does John do?",
  "volume_id": "...",
  "memories": [
    {
      "id": "point-id",
      "content": "John Smith is the CTO of Acme Corp",
      "score": 0.95,
      "agent": "onboarding-agent",
      "memory_type": "factual",
      "document_id": null,
      "filename": null,
      "chunk_index": null,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "graph_facts": [
    {
      "source": "John Smith",
      "type": "WORKS_AT",
      "description": "Chief Technology Officer since 2022",
      "target": "Acme Corp"
    }
  ],
  "document_sources": [
    {
      "document_id": "doc-uuid",
      "filename": "team-roster.pdf",
      "best_score": 0.88,
      "chunk_count": 3,
      "snippets": ["John Smith, CTO..."]
    }
  ],
  "total_results": 5
}

Response Fields

Field	Description
memories	Vector search results — only those scored above 0.3 threshold
graph_facts	Related knowledge graph relationships found via entity traversal
document_sources	Documents containing relevant chunks, grouped by file
total_results	Total count of memories + graph facts

Example

cURL

curl -X POST https://api.sharedmemory.ai/agent/memory/query \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What technologies does the team use?",
    "volume_id": "a1b2c3d4-...",
    "limit": 20
  }'

TypeScript SDK

const result = await memory.recall("What technologies does the team use?", {
  volumeId: 'a1b2c3d4-...',
  limit: 20,
})

console.log(result.memories)       // semantic matches
console.log(result.graph_facts)    // knowledge graph relationships
console.log(result.document_sources) // relevant doc chunks

Python

response = requests.post(
    "https://api.sharedmemory.ai/agent/memory/query",
    headers={"Authorization": "Bearer sm_live_..."},
    json={
        "query": "What technologies does the team use?",
        "volume_id": "a1b2c3d4-...",
        "limit": 20
    }
)

data = response.json()
print(data["memories"])
print(data["graph_facts"])

Errors

Status	Error	Description
400	validation_failed	Invalid input — check details
403	agent_not_authorized_for_volume	Agent doesn't have read access
429	Too Many Requests	Rate limit exceeded (60/min)
500	query_failed	Internal error — retry with backoff