Add docs for Search Mode retrieval_strategy argument

docs/agents/_includes/query_agent.mts

@@ -382,6 +382,17 @@ for (const obj of basicSearchResponse.searchResults.objects) {
 }
 // END BasicSearchQuery
 
+// START SearchStrategyExample
+const strategyResponse = await qa.search("Find me some vintage shoes under $70", {
+    retrievalStrategy: "recall",
+    limit: 10,
+})
+
+for (const obj of strategyResponse.searchResults.objects) {
+    console.log(`Product: ${obj.properties['name']} - ${obj.properties['price']}`)
+}
+// END SearchStrategyExample
+
 
 // START BasicAskQuery
 // Perform a query

docs/agents/_includes/query_agent.py

@@ -398,6 +398,17 @@ def populate_weaviate(client, overwrite_existing=False):
     print(f"Product: {obj.properties['name']} - ${obj.properties['price']}")
 # END BasicSearchQuery
 
+# START SearchStrategyExample
+search_response = qa.search(
+    "Find me some vintage shoes under $70",
+    retrieval_strategy="recall",
+    limit=10,
+)
+
+for obj in search_response.search_results.objects:
+    print(f"Product: {obj.properties['name']} - ${obj.properties['price']}")
+# END SearchStrategyExample
+
 # START SearchModeResponseStructure
 # SearchModeResponse structure for Python
 search_response = qa.search("winter boots for under $100", limit=5)

docs/agents/query/usage.md

@@ -237,6 +237,33 @@ The Query Agent supports two query types:
 
 </Tabs>
 
+#### Retrieval Strategy
+
+Search Mode uses query rewriting to transform your original query into one or multiple Weaviate queries, each with either a search query, metadata filters, or both. The `retrieval_strategy` parameter (`retrievalStrategy` in JavaScript/TypeScript) controls how many Weaviate queries are generated.
+
+- **`"recall"`** (default): Generates multiple Weaviate queries spanning different filters and interpretations of the user query.
+- **`"precision"`**: Generates a single Weaviate query targeting the most likely interpretation of the user query.
+
+<Tabs className="code" groupId="languages">
+    <TabItem value="py_agents" label="Python">
+        <FilteredTextBlock
+            text={PyCode}
+            startMarker="# START SearchStrategyExample"
+            endMarker="# END SearchStrategyExample"
+            language="py"
+        />
+    </TabItem>
+    <TabItem value="ts_agents" label="JavaScript/TypeScript">
+        <FilteredTextBlock
+            text={TSCode}
+            startMarker="// START SearchStrategyExample"
+            endMarker="// END SearchStrategyExample"
+            language="ts"
+        />
+    </TabItem>
+
+</Tabs>
+
 #### `Search` response structure
 
 <Tabs className="code" groupId="languages">

docs/engram/_includes/check_run_status.py

@@ -0,0 +1,38 @@
+import os
+import time
+import uuid
+from engram import EngramClient
+
+client = EngramClient(
+    api_key=os.environ["ENGRAM_API_KEY"]
+)
+
+test_user_id = f"test-{uuid.uuid4().hex[:8]}"
+
+# Setup: store a memory to get a run_id
+run = client.memories.add(
+    "The user prefers dark mode",
+    user_id=test_user_id,
+    group="default",
+)
+
+# START PollRun
+status = client.runs.wait(run.run_id)
+
+print(status.run_id)
+print(status.status)
+print(status.committed_operations)
+# END PollRun
+
+assert status.status == "completed"
+assert status.committed_operations is not None
+assert len(status.memories_created) >= 1
+
+time.sleep(2)  # Allow tenant indexing to complete
+
+# Cleanup
+_all = client.memories.search(query="dark mode", user_id=test_user_id, group="default")
+for _m in _all:
+    client.memories.delete(_m.id, user_id=test_user_id, group="default")
+
+client.close()

docs/engram/_includes/check_run_status.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+set -euo pipefail
+
+BASE_URL="${ENGRAM_BASE_URL:-https://api.engram.weaviate.io}"
+USER_ID="test-curl-$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)"
+
+: <<'DOCSNIPPETS'
+# START PollRun
+curl https://api.engram.weaviate.io/v1/runs/{run-id} \
+  -H "Authorization: Bearer $ENGRAM_API_KEY"
+# END PollRun
+DOCSNIPPETS
+
+# --- Test execution below ---
+
+# Create a memory to get a run_id
+RUN_ID=$(curl -s -X POST "$BASE_URL/v1/memories" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": {
+      "type": "string",
+      "content": "The user prefers dark mode and uses VS Code."
+    },
+    "user_id": "'"$USER_ID"'",
+    "group": "default"
+  }' | jq -r '.run_id')
+
+echo "Run ID: $RUN_ID"
+
+# Poll until completed
+for i in $(seq 1 30); do
+  STATUS=$(curl -s "$BASE_URL/v1/runs/$RUN_ID" \
+    -H "Authorization: Bearer $ENGRAM_API_KEY" | jq -r '.status')
+  echo "Status: $STATUS"
+  [ "$STATUS" = "completed" ] && break
+  sleep 2
+done
+[ "$STATUS" = "completed" ] || { echo "FAIL: run did not complete"; exit 1; }
+
+# Verify committed_operations
+CREATED_COUNT=$(curl -s "$BASE_URL/v1/runs/$RUN_ID" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY" | jq '.committed_operations.created | length')
+[ "$CREATED_COUNT" -ge 1 ] || { echo "FAIL: expected at least 1 created memory"; exit 1; }
+echo "Created memories: $CREATED_COUNT"
+
+# Cleanup
+for i in $(seq 1 10); do
+  WARMUP=$(curl -s -X POST "$BASE_URL/v1/memories/search" \
+    -H "Authorization: Bearer $ENGRAM_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d '{"query": "dark mode", "user_id": "'"$USER_ID"'", "group": "default", "retrieval_config": {"retrieval_type": "hybrid", "limit": 1}}')
+  WARMUP_COUNT=$(echo "$WARMUP" | jq '.memories | length' 2>/dev/null || echo "0")
+  [ "$WARMUP_COUNT" -ge 1 ] 2>/dev/null && break
+  sleep 3
+done
+
+curl -s -X POST "$BASE_URL/v1/memories/search" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "user", "user_id": "'"$USER_ID"'", "group": "default", "retrieval_config": {"retrieval_type": "hybrid", "limit": 100}}' \
+  | jq -r '.memories[]? | .id // empty' | while read -r MID; do
+    curl -s -X DELETE "$BASE_URL/v1/memories/$MID?user_id=$USER_ID&group=default" \
+      -H "Authorization: Bearer $ENGRAM_API_KEY" > /dev/null
+  done
+
+echo "PASS"

docs/engram/_includes/cleanup_memories.py

@@ -0,0 +1,25 @@
+import os
+from engram import EngramClient
+
+client = EngramClient(
+    api_key=os.environ["ENGRAM_API_KEY"]
+)
+
+user_id = os.environ.get("ENGRAM_USER_ID", "user-uuid")
+group = os.environ.get("ENGRAM_GROUP", "default")
+
+deleted = 0
+for _ in range(20):
+    results = client.memories.search(query="user", user_id=user_id, group=group)
+    if len(results) == 0:
+        break
+    for m in results:
+        try:
+            client.memories.delete(m.id, topic=m.topic, user_id=user_id)
+            deleted += 1
+        except Exception:
+            pass
+
+print(f"Deleted {deleted} memories for user_id={user_id}, group={group}")
+
+client.close()

docs/engram/_includes/manage_memories.py

@@ -0,0 +1,58 @@
+import os
+import uuid
+from engram import EngramClient, APIError
+
+client = EngramClient(
+    api_key=os.environ["ENGRAM_API_KEY"]
+)
+
+test_user_id = f"test-{uuid.uuid4().hex[:8]}"
+
+# Setup: store a memory so we can get and delete it
+run = client.memories.add(
+    "The user prefers dark mode",
+    user_id=test_user_id,
+    group="default",
+)
+status = client.runs.wait(run.run_id)
+assert status.status == "completed"
+assert status.committed_operations is not None
+assert len(status.memories_created) >= 1
+
+memory_id = status.memories_created[0].memory_id
+
+# START GetMemory
+memory = client.memories.get(
+    memory_id,
+    user_id=test_user_id,
+    group="default",
+)
+
+print(memory.content)
+print(memory.topic)
+# END GetMemory
+
+assert memory.id == memory_id
+assert "dark mode" in memory.content
+
+# START DeleteMemory
+client.memories.delete(
+    memory_id,
+    user_id=test_user_id,
+    group="default",
+)
+# END DeleteMemory
+
+# Verify the memory was deleted
+try:
+    client.memories.get(memory_id, user_id=test_user_id, group="default")
+    assert False, "Expected memory to be deleted"
+except APIError:
+    pass  # Memory no longer exists
+
+# Cleanup
+_all = client.memories.search(query="dark mode", user_id=test_user_id, group="default")
+for _m in _all:
+    client.memories.delete(_m.id, user_id=test_user_id, group="default")
+
+client.close()

docs/engram/_includes/manage_memories.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+set -euo pipefail
+
+BASE_URL="${ENGRAM_BASE_URL:-https://api.engram.weaviate.io}"
+USER_ID="test-curl-$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)"
+
+: <<'DOCSNIPPETS'
+# START GetMemory
+curl https://api.engram.weaviate.io/v1/memories/{memory-id}?user_id=user-uuid&group=default \
+  -H "Authorization: Bearer $ENGRAM_API_KEY"
+# END GetMemory
+
+# START DeleteMemory
+curl -X DELETE https://api.engram.weaviate.io/v1/memories/{memory-id}?user_id=user-uuid&group=default \
+  -H "Authorization: Bearer $ENGRAM_API_KEY"
+# END DeleteMemory
+DOCSNIPPETS
+
+# --- Test execution below ---
+
+# Seed a memory to manage
+RUN_ID=$(curl -s -X POST "$BASE_URL/v1/memories" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": {
+      "type": "string",
+      "content": "The user prefers dark mode and uses VS Code."
+    },
+    "user_id": "'"$USER_ID"'",
+    "group": "default"
+  }' | jq -r '.run_id')
+
+for i in $(seq 1 30); do
+  STATUS=$(curl -s "$BASE_URL/v1/runs/$RUN_ID" \
+    -H "Authorization: Bearer $ENGRAM_API_KEY" | jq -r '.status')
+  [ "$STATUS" = "completed" ] && break
+  sleep 2
+done
+[ "$STATUS" = "completed" ] || { echo "FAIL: seed run did not complete"; exit 1; }
+
+# Wait for indexing
+for i in $(seq 1 10); do
+  WARMUP=$(curl -s -X POST "$BASE_URL/v1/memories/search" \
+    -H "Authorization: Bearer $ENGRAM_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d '{"query": "dark mode VS Code", "user_id": "'"$USER_ID"'", "group": "default", "retrieval_config": {"retrieval_type": "hybrid", "limit": 1}}')
+  WARMUP_COUNT=$(echo "$WARMUP" | jq '.memories | length' 2>/dev/null || echo "0")
+  [ "$WARMUP_COUNT" -ge 1 ] 2>/dev/null && break
+  sleep 3
+done
+
+# Find a memory ID
+MEMORY_ID=$(curl -s -X POST "$BASE_URL/v1/memories/search" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "dark mode", "user_id": "'"$USER_ID"'", "group": "default", "retrieval_config": {"retrieval_type": "hybrid", "limit": 5}}' \
+  | jq -r '.memories[0].id')
+
+[ "$MEMORY_ID" != "null" ] || { echo "FAIL: no memory found to manage"; exit 1; }
+echo "Memory ID: $MEMORY_ID"
+
+# Test get memory
+GOT_ID=$(curl -s "$BASE_URL/v1/memories/$MEMORY_ID?user_id=$USER_ID&group=default" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY" | jq -r '.id')
+[ "$GOT_ID" = "$MEMORY_ID" ] || { echo "FAIL: get returned wrong memory"; exit 1; }
+echo "Get memory: OK"
+
+# Test delete memory
+curl -s -X DELETE "$BASE_URL/v1/memories/$MEMORY_ID?user_id=$USER_ID&group=default" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY"
+echo "Delete memory: OK"
+
+# Verify deletion
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
+  "$BASE_URL/v1/memories/$MEMORY_ID?user_id=$USER_ID&group=default" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY")
+[ "$HTTP_CODE" = "404" ] || echo "Warning: expected 404 after delete, got $HTTP_CODE"
+
+# Cleanup remaining
+curl -s -X POST "$BASE_URL/v1/memories/search" \
+  -H "Authorization: Bearer $ENGRAM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "user", "user_id": "'"$USER_ID"'", "group": "default", "retrieval_config": {"retrieval_type": "hybrid", "limit": 100}}' \
+  | jq -r '.memories[]? | .id // empty' | while read -r MID; do
+    curl -s -X DELETE "$BASE_URL/v1/memories/$MID?user_id=$USER_ID&group=default" \
+      -H "Authorization: Bearer $ENGRAM_API_KEY" > /dev/null
+  done
+
+echo "PASS"