garden.engram.searchMemories
Schema Diff
+26 -4
Compatibility Analysis
Backward Compatible
Backward compatible. 2 non-breaking changes.
Non-Breaking Changes (2)
- AddedVertex AddedVertex { vertex_id: "garden.engram.searchMemories:output.mode" }
- AddedEdge AddedEdge { src: "garden.engram.searchMemories:output", tgt: "garden.engram.searchMemories:output.mode", kind: "prop", name: Some("mode") }
Migration Guidance
Added Elements
AddedVertex { vertex_id: "garden.engram.searchMemories:output.mode" }
Additional Notes
- Non-breaking: AddedEdge { src: "garden.engram.searchMemories:output", tgt: "garden.engram.searchMemories:output.mode", kind: "prop", name: Some("mode") }
1
1
{
2
2
"$type": "com.atproto.lexicon.schema",
3
3
"defs": {
4
4
"main": {
5
-
"description": "Vector search over a space's memories. The caller embeds its query with the space's model and query prefix and sends vector, model and modelDigest. A service that runs the space's model may instead embed q itself when no vector is sent. A service that doesn't embed queries answers InvalidRequest, and one that doesn't run the space's model answers ModelNotHosted. Requires a space credential for the space, presented with an HTTP message signature whose audience is this service's DID.",
5
+
"description": "Search over a space's memories, by meaning and exact words. The caller embeds its query with the space's model and query prefix and sends vector, model and modelDigest, plus q: once the space has a keyword index, the results rank by both (hybrid). A service that runs the space's model may instead embed q itself when no vector is sent; one that can't (it doesn't embed queries, doesn't run the space's model, or doesn't embed for the space's authority) searches by keyword alone instead, unless mode asks otherwise. The response's mode says what ran. Requires a space credential for the space, presented with an HTTP message signature whose audience is this service's DID.",
6
6
"errors": [
7
7
{
8
8
"description": "This service does not index the space.",
9
9
"name": "UnknownSpace"
10
10
},
11
11
{
12
12
"description": "The space's authority hasn't declared an embedding model.",
13
13
"name": "NoModel"
14
14
},
15
15
{
16
16
"description": "The query's model isn't the space's model. Re-read the space's config.",
17
17
"name": "ModelMismatch"
18
18
},
19
19
{
20
-
"description": "q was sent without a vector, and this service doesn't run the space's model. Embed the query with the space's model and send the vector.",
20
+
"description": "q was sent without a vector, this service doesn't run the space's model, and keyword search couldn't run instead (mode hybrid, or the space has no keyword index yet). Embed the query with the space's model and send the vector.",
21
21
"name": "ModelNotHosted"
22
22
},
23
23
{
24
-
"description": "This service doesn't embed queries for this space's authority.",
24
+
"description": "This service doesn't embed queries for this space's authority, and keyword search couldn't run instead (mode hybrid, or the space has no keyword index yet).",
25
25
"name": "TextSearchNotAllowed"
26
26
},
27
27
{
28
+
"description": "mode keyword, and the space's keyword index is still being built. Search with a vector meanwhile.",
29
+
"name": "KeywordIndexBuilding"
30
+
},
31
+
{
28
32
"description": "Too many queries are being embedded. Retry shortly.",
29
33
"name": "EmbedderBusy"
30
34
},
31
35
{
32
36
"description": "The space's index is loading. Retry shortly.",
33
37
"name": "IndexLoading"
34
38
},
35
39
{
36
40
"description": "Too many searches for this space.",
37
41
"name": "RateLimitExceeded"
38
42
}
39
43
],
40
44
"output": {
41
45
"encoding": "application/json",
42
46
"schema": {
43
47
"properties": {
44
48
"approximate": {
45
49
"description": "Set when the index couldn't re-rank in time, so results are ranked by a coarser comparison and may be less precise.",
46
50
"type": "boolean"
47
51
},
48
52
"memories": {
49
53
"items": {
50
54
"ref": "garden.engram.defs#memoryView",
51
55
"type": "ref"
52
56
},
53
57
"type": "array"
58
+
},
59
+
"mode": {
60
+
"description": "What ran: hybrid, vector (no q, mode vector, or a space whose keyword index is still being built), or keyword (mode keyword, or a fallback when q couldn't be embedded).",
61
+
"knownValues": [
62
+
"hybrid",
63
+
"vector",
64
+
"keyword"
65
+
],
66
+
"type": "string"
54
67
}
55
68
},
56
69
"required": [
57
70
"memories"
58
71
],
59
72
"type": "object"
60
73
}
61
74
},
62
75
"parameters": {
63
76
"properties": {
64
77
"author": {
65
78
"description": "Only memories written by this DID.",
66
79
"format": "did",
67
80
"type": "string"
68
81
},
69
82
"limit": {
70
83
"default": 10,
71
84
"maximum": 50,
72
85
"minimum": 1,
73
86
"type": "integer"
74
87
},
88
+
"mode": {
89
+
"description": "hybrid (the default with q and a vector) ranks by meaning and exact words; vector ignores q for ranking; keyword ranks by q's words alone, needs no vector, and answers KeywordIndexBuilding until the space has a keyword index. An explicit mode never falls back.",
90
+
"knownValues": [
91
+
"hybrid",
92
+
"vector",
93
+
"keyword"
94
+
],
95
+
"type": "string"
96
+
},
75
97
"model": {
76
98
"description": "Must match the space's model.",
77
99
"type": "string"
78
100
},
79
101
"modelDigest": {
80
102
"description": "Must match the space's model digest.",
81
103
"type": "string"
82
104
},
83
105
"q": {
84
-
"description": "The query's text. Sent with a vector, it isn't used for ranking. Sent alone, a service that embeds queries (at most 1000 characters) embeds it with the space's model and query prefix.",
106
+
"description": "The query's text. With a vector, it makes the search hybrid once the space has a keyword index. Sent alone, a service that embeds queries (at most 1000 characters) embeds it with the space's model and query prefix; otherwise the search is by keyword alone.",
85
107
"maxLength": 4000,
86
108
"type": "string"
87
109
},
88
110
"since": {
89
111
"description": "Only memories created at or after this time.",
90
112
"format": "datetime",
91
113
"type": "string"
92
114
},
93
115
"space": {
94
116
"description": "The space URI.",
95
117
"type": "string"
96
118
},
97
119
"tags": {
98
120
"description": "Only memories carrying every one of these tags.",
99
121
"items": {
100
122
"type": "string"
101
123
},
102
124
"maxLength": 16,
103
125
"type": "array"
104
126
},
105
127
"vector": {
106
128
"description": "The query's vector: little-endian IEEE half precision, base64url-encoded without padding.",
107
129
"maxLength": 43000,
108
130
"type": "string"
109
131
}
110
132
},
111
133
"required": [
112
134
"space"
113
135
],
114
136
"type": "params"
115
137
},
116
138
"type": "query"
117
139
}
118
140
},
119
141
"id": "garden.engram.searchMemories",
120
142
"lexicon": 1
121
143
}