Query API

Find relevant memories and generate answers.

Query Memories

Find memories relevant to a context using intelligent retrieval.

POST /v1/query

Request Body

Field	Type	Required	Default	Description
context	string	Yes	-	Query context/question
max_memories	int	No	20	Max results (1-100)
relevance_threshold	float	No	0.5	Min score (0-1)
search_depth	float	No	0.5	Search thoroughness (0-1). Higher values search more comprehensively but cost more. 0 = fast, 0.5 = balanced, 1 = exhaustive
include_metadata	bool	No	true	Include metadata
space_id	string	No	null	Filter to specific space
metadata_filter	object	No	null	Filter by metadata values (e.g., {"category": "work"})
query_rewrite	bool	No	false	Expand query for better recall
hybrid_search	bool	No	false	Combine keyword and semantic matching
temporal_boost	float	No	null	Boost recent memories (0-1)
as_of	datetime	No	null	Query memories as of this timestamp (see Temporal Queries)

Search Depth

The search_depth parameter controls how thoroughly the system searches for relevant memories:

• 0.0 - 0.3: Fast searches, best for simple queries or large memory stores (searches ~5-15% of memories)
• 0.3 - 0.7: Balanced approach, good for most use cases (searches ~15-50% of memories)
• 0.7 - 1.0: Thorough searches, best for critical queries where accuracy matters more than speed (searches 50-100% of memories)

Higher search depth values increase accuracy but also increase latency and cost. For most applications, the default value of 0.5 provides a good balance.

Example

curl -X POST https://memoryapi.tensorheart.com/v1/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "What programming languages does the user know?",
    "max_memories": 5,
    "relevance_threshold": 0.6,
    "search_depth": 0.7,
    "space_id": "skills",
    "query_rewrite": true
  }'

Response

{
  "success": true,
  "data": {
    "memories": [
      {
        "id": "mem_abc123",
        "text": "User is proficient in Python and JavaScript",
        "relevance_score": 0.92,
        "metadata": {"category": "skills"}
      }
    ],
    "query_context": "What programming languages does the user know?",
    "total_memories_searched": 50
  },
  "meta": {
    "request_id": "req_abc123",
    "processing_time_ms": 85,
    "usage": {
      "memories_accessed": 1
    }
  }
}

---

Query with Answer

Find memories and generate an AI answer using intelligent retrieval.

POST /v1/query/answer

Request Body

Field	Type	Required	Default	Description
context	string	Yes	-	Question to answer
max_memories	int	No	20	Max memories to consider
relevance_threshold	float	No	0.5	Min relevance (0-1)
search_depth	float	No	0.5	Search thoroughness (0-1). Higher values search more comprehensively but cost more
prompt_template	string	No	null	Custom prompt. Use {context} and {memories} placeholders

Example

curl -X POST https://memoryapi.tensorheart.com/v1/query/answer \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "What industry does the user work in?",
    "search_depth": 0.7
  }'

Response

{
  "success": true,
  "data": {
    "answer": "Based on the stored memories, the user works in the technology industry as a data scientist.",
    "memories_used": [
      {
        "id": "mem_abc123",
        "text": "User works as a data scientist at TechCorp",
        "relevance_score": 0.95,
        "metadata": {"category": "professional"}
      }
    ],
    "confidence": null,
    "model": "gpt-4o-mini"
  },
  "meta": {
    "request_id": "req_def456",
    "processing_time_ms": 1250,
    "usage": {
      "memories_accessed": 1,
      "tokens_processed": 450,
      "model_calls": 1
    }
  }
}

---

Extract Memories

Extract memories from a conversation or document.

POST /v1/query/extract

Request Body

Field	Type	Required	Description
content	string	Yes	Content to extract from
content_type	string	No	Type: conversation, document, notes
metadata	object	No	Metadata for extracted memories

Example

curl -X POST https://memoryapi.tensorheart.com/v1/query/extract \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User: Hi, I am John and I work at Google.\nAssistant: Nice to meet you!",
    "content_type": "conversation"
  }'

Response

{
  "success": true,
  "data": {
    "extracted_count": 2,
    "memory_ids": ["mem_new1", "mem_new2"]
  },
  "meta": {
    "request_id": "req_ghi789",
    "processing_time_ms": 2100,
    "usage": {
      "memories_accessed": 2,
      "tokens_processed": 850,
      "model_calls": 1
    }
  }
}

---

Temporal Queries

Query memories as they existed at a specific point in time using the as_of parameter.

This is useful when:

• You need to understand what was known at a specific date
• Building audit trails or compliance reports
• Debugging when information changed

How It Works

When you use smart updates, old versions of memories are preserved with timestamps. The as_of parameter filters to show only memories that were valid (not yet superseded) at the specified time.

Example

Query what was known about a user on January 1st, 2024:

curl -X POST https://memoryapi.tensorheart.com/v1/query \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "What is Alice experience level?",
    "as_of": "2024-01-01T00:00:00Z"
  }'

Response

Returns memories that were valid on January 1st (before any updates):

{
  "success": true,
  "data": {
    "memories": [
      {
        "id": "mem_abc123",
        "text": "Alice has 5 years of experience",
        "relevance_score": 0.95
      }
    ],
    "query_context": "What is Alice experience level?",
    "total_memories_searched": 8
  },
  "meta": {
    "request_id": "req_xyz123",
    "processing_time_ms": 95
  }
}

Use with Memory History

Combine temporal queries with the Memory History endpoint to see the full timeline of changes.