@functional-systems/memdrive 0.1.1-dev.2 → 0.1.1-dev.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +20 -279
  3. package/dist/commonjs/chunking.d.ts +1 -2
  4. package/dist/commonjs/chunking.d.ts.map +1 -1
  5. package/dist/commonjs/chunking.js +2 -5
  6. package/dist/commonjs/chunking.js.map +1 -1
  7. package/dist/commonjs/config.d.ts +17 -0
  8. package/dist/commonjs/config.d.ts.map +1 -0
  9. package/dist/commonjs/config.js +116 -0
  10. package/dist/commonjs/config.js.map +1 -0
  11. package/dist/commonjs/errors.d.ts +10 -6
  12. package/dist/commonjs/errors.d.ts.map +1 -1
  13. package/dist/commonjs/errors.js +25 -5
  14. package/dist/commonjs/errors.js.map +1 -1
  15. package/dist/commonjs/index.d.ts +15 -5
  16. package/dist/commonjs/index.d.ts.map +1 -1
  17. package/dist/commonjs/index.js +332 -280
  18. package/dist/commonjs/index.js.map +1 -1
  19. package/dist/commonjs/records.d.ts +44 -0
  20. package/dist/commonjs/records.d.ts.map +1 -0
  21. package/dist/commonjs/records.js +88 -0
  22. package/dist/commonjs/records.js.map +1 -0
  23. package/dist/commonjs/search.d.ts +8 -0
  24. package/dist/commonjs/search.d.ts.map +1 -0
  25. package/dist/commonjs/search.js +56 -0
  26. package/dist/commonjs/search.js.map +1 -0
  27. package/dist/commonjs/types.d.ts +84 -252
  28. package/dist/commonjs/types.d.ts.map +1 -1
  29. package/dist/esm/chunking.d.ts +1 -2
  30. package/dist/esm/chunking.d.ts.map +1 -1
  31. package/dist/esm/chunking.js +2 -4
  32. package/dist/esm/chunking.js.map +1 -1
  33. package/dist/esm/config.d.ts +17 -0
  34. package/dist/esm/config.d.ts.map +1 -0
  35. package/dist/esm/config.js +107 -0
  36. package/dist/esm/config.js.map +1 -0
  37. package/dist/esm/errors.d.ts +10 -6
  38. package/dist/esm/errors.d.ts.map +1 -1
  39. package/dist/esm/errors.js +22 -4
  40. package/dist/esm/errors.js.map +1 -1
  41. package/dist/esm/index.d.ts +15 -5
  42. package/dist/esm/index.d.ts.map +1 -1
  43. package/dist/esm/index.js +332 -278
  44. package/dist/esm/index.js.map +1 -1
  45. package/dist/esm/records.d.ts +44 -0
  46. package/dist/esm/records.d.ts.map +1 -0
  47. package/dist/esm/records.js +77 -0
  48. package/dist/esm/records.js.map +1 -0
  49. package/dist/esm/search.d.ts +8 -0
  50. package/dist/esm/search.d.ts.map +1 -0
  51. package/dist/esm/search.js +52 -0
  52. package/dist/esm/search.js.map +1 -0
  53. package/dist/esm/types.d.ts +84 -252
  54. package/dist/esm/types.d.ts.map +1 -1
  55. package/package.json +7 -42
  56. package/src/chunking.ts +2 -3
  57. package/src/config.ts +121 -0
  58. package/src/errors.ts +20 -6
  59. package/src/index.ts +352 -260
  60. package/src/records.ts +83 -0
  61. package/src/search.ts +57 -0
  62. package/src/types.ts +74 -253
  63. package/dist/commonjs/filter.d.ts +0 -30
  64. package/dist/commonjs/filter.d.ts.map +0 -1
  65. package/dist/commonjs/filter.js +0 -224
  66. package/dist/commonjs/filter.js.map +0 -1
  67. package/dist/commonjs/recall-input.d.ts +0 -8
  68. package/dist/commonjs/recall-input.d.ts.map +0 -1
  69. package/dist/commonjs/recall-input.js +0 -45
  70. package/dist/commonjs/recall-input.js.map +0 -1
  71. package/dist/commonjs/retriever/index.d.ts +0 -7
  72. package/dist/commonjs/retriever/index.d.ts.map +0 -1
  73. package/dist/commonjs/retriever/index.js +0 -167
  74. package/dist/commonjs/retriever/index.js.map +0 -1
  75. package/dist/commonjs/retriever/scope.d.ts +0 -5
  76. package/dist/commonjs/retriever/scope.d.ts.map +0 -1
  77. package/dist/commonjs/retriever/scope.js +0 -69
  78. package/dist/commonjs/retriever/scope.js.map +0 -1
  79. package/dist/commonjs/retriever/types.d.ts +0 -89
  80. package/dist/commonjs/retriever/types.d.ts.map +0 -1
  81. package/dist/commonjs/retriever/types.js +0 -3
  82. package/dist/commonjs/retriever/types.js.map +0 -1
  83. package/dist/commonjs/storage.d.ts +0 -274
  84. package/dist/commonjs/storage.d.ts.map +0 -1
  85. package/dist/commonjs/storage.js +0 -861
  86. package/dist/commonjs/storage.js.map +0 -1
  87. package/dist/commonjs/tools/definitions.d.ts +0 -5
  88. package/dist/commonjs/tools/definitions.d.ts.map +0 -1
  89. package/dist/commonjs/tools/definitions.js +0 -147
  90. package/dist/commonjs/tools/definitions.js.map +0 -1
  91. package/dist/commonjs/tools/evidence-ids.d.ts +0 -7
  92. package/dist/commonjs/tools/evidence-ids.d.ts.map +0 -1
  93. package/dist/commonjs/tools/evidence-ids.js +0 -71
  94. package/dist/commonjs/tools/evidence-ids.js.map +0 -1
  95. package/dist/commonjs/tools/factory.d.ts +0 -7
  96. package/dist/commonjs/tools/factory.d.ts.map +0 -1
  97. package/dist/commonjs/tools/factory.js +0 -169
  98. package/dist/commonjs/tools/factory.js.map +0 -1
  99. package/dist/commonjs/tools/index.d.ts +0 -6
  100. package/dist/commonjs/tools/index.d.ts.map +0 -1
  101. package/dist/commonjs/tools/index.js +0 -25
  102. package/dist/commonjs/tools/index.js.map +0 -1
  103. package/dist/commonjs/tools/internal-types.d.ts +0 -18
  104. package/dist/commonjs/tools/internal-types.d.ts.map +0 -1
  105. package/dist/commonjs/tools/internal-types.js +0 -3
  106. package/dist/commonjs/tools/internal-types.js.map +0 -1
  107. package/dist/commonjs/tools/short-ids.d.ts +0 -8
  108. package/dist/commonjs/tools/short-ids.d.ts.map +0 -1
  109. package/dist/commonjs/tools/short-ids.js +0 -81
  110. package/dist/commonjs/tools/short-ids.js.map +0 -1
  111. package/dist/commonjs/tools/types.d.ts +0 -53
  112. package/dist/commonjs/tools/types.d.ts.map +0 -1
  113. package/dist/commonjs/tools/types.js +0 -3
  114. package/dist/commonjs/tools/types.js.map +0 -1
  115. package/dist/commonjs/values.d.ts +0 -17
  116. package/dist/commonjs/values.d.ts.map +0 -1
  117. package/dist/commonjs/values.js +0 -90
  118. package/dist/commonjs/values.js.map +0 -1
  119. package/dist/esm/filter.d.ts +0 -30
  120. package/dist/esm/filter.d.ts.map +0 -1
  121. package/dist/esm/filter.js +0 -209
  122. package/dist/esm/filter.js.map +0 -1
  123. package/dist/esm/recall-input.d.ts +0 -8
  124. package/dist/esm/recall-input.d.ts.map +0 -1
  125. package/dist/esm/recall-input.js +0 -40
  126. package/dist/esm/recall-input.js.map +0 -1
  127. package/dist/esm/retriever/index.d.ts +0 -7
  128. package/dist/esm/retriever/index.d.ts.map +0 -1
  129. package/dist/esm/retriever/index.js +0 -163
  130. package/dist/esm/retriever/index.js.map +0 -1
  131. package/dist/esm/retriever/scope.d.ts +0 -5
  132. package/dist/esm/retriever/scope.d.ts.map +0 -1
  133. package/dist/esm/retriever/scope.js +0 -66
  134. package/dist/esm/retriever/scope.js.map +0 -1
  135. package/dist/esm/retriever/types.d.ts +0 -89
  136. package/dist/esm/retriever/types.d.ts.map +0 -1
  137. package/dist/esm/retriever/types.js +0 -2
  138. package/dist/esm/retriever/types.js.map +0 -1
  139. package/dist/esm/storage.d.ts +0 -274
  140. package/dist/esm/storage.d.ts.map +0 -1
  141. package/dist/esm/storage.js +0 -845
  142. package/dist/esm/storage.js.map +0 -1
  143. package/dist/esm/tools/definitions.d.ts +0 -5
  144. package/dist/esm/tools/definitions.d.ts.map +0 -1
  145. package/dist/esm/tools/definitions.js +0 -144
  146. package/dist/esm/tools/definitions.js.map +0 -1
  147. package/dist/esm/tools/evidence-ids.d.ts +0 -7
  148. package/dist/esm/tools/evidence-ids.d.ts.map +0 -1
  149. package/dist/esm/tools/evidence-ids.js +0 -68
  150. package/dist/esm/tools/evidence-ids.js.map +0 -1
  151. package/dist/esm/tools/factory.d.ts +0 -7
  152. package/dist/esm/tools/factory.d.ts.map +0 -1
  153. package/dist/esm/tools/factory.js +0 -166
  154. package/dist/esm/tools/factory.js.map +0 -1
  155. package/dist/esm/tools/index.d.ts +0 -6
  156. package/dist/esm/tools/index.d.ts.map +0 -1
  157. package/dist/esm/tools/index.js +0 -22
  158. package/dist/esm/tools/index.js.map +0 -1
  159. package/dist/esm/tools/internal-types.d.ts +0 -18
  160. package/dist/esm/tools/internal-types.d.ts.map +0 -1
  161. package/dist/esm/tools/internal-types.js +0 -2
  162. package/dist/esm/tools/internal-types.js.map +0 -1
  163. package/dist/esm/tools/short-ids.d.ts +0 -8
  164. package/dist/esm/tools/short-ids.d.ts.map +0 -1
  165. package/dist/esm/tools/short-ids.js +0 -78
  166. package/dist/esm/tools/short-ids.js.map +0 -1
  167. package/dist/esm/tools/types.d.ts +0 -53
  168. package/dist/esm/tools/types.d.ts.map +0 -1
  169. package/dist/esm/tools/types.js +0 -2
  170. package/dist/esm/tools/types.js.map +0 -1
  171. package/dist/esm/values.d.ts +0 -17
  172. package/dist/esm/values.d.ts.map +0 -1
  173. package/dist/esm/values.js +0 -87
  174. package/dist/esm/values.js.map +0 -1
  175. package/docs/tools.md +0 -264
  176. package/src/filter.ts +0 -189
  177. package/src/recall-input.ts +0 -46
  178. package/src/retriever/index.ts +0 -142
  179. package/src/retriever/scope.ts +0 -56
  180. package/src/retriever/types.ts +0 -68
  181. package/src/storage.ts +0 -765
  182. package/src/tools/definitions.ts +0 -175
  183. package/src/tools/evidence-ids.ts +0 -57
  184. package/src/tools/factory.ts +0 -153
  185. package/src/tools/index.ts +0 -25
  186. package/src/tools/internal-types.ts +0 -12
  187. package/src/tools/short-ids.ts +0 -58
  188. package/src/tools/types.ts +0 -48
  189. package/src/values.ts +0 -103
@@ -1,175 +0,0 @@
1
- import type { DriveDescriptor, MetadataSchema, MetadataType } from '../types.js';
2
- import type { JsonSchema, ToolDefinition, ToolName } from './types.js';
3
-
4
- const dialect = 'https://json-schema.org/draft/2020-12/schema';
5
- const object = (properties: Record<string, JsonSchema>, required: string[] = []): JsonSchema => ({
6
- type: 'object', properties, required, additionalProperties: false,
7
- });
8
- const string = (description?: string): JsonSchema => ({ type: 'string', ...(description ? { description } : {}) });
9
- const array = (items: JsonSchema, extra: JsonSchema = {}): JsonSchema => ({ type: 'array', items, ...extra });
10
- const id = { type: 'string', minLength: 1, maxLength: 512 };
11
- const ids = (description: string): JsonSchema => array(id, { minItems: 1, uniqueItems: true, description });
12
- const timestamp = string('ISO 8601 timestamp with Z or an explicit UTC offset; at most millisecond precision.');
13
- const scalarTypes: Record<MetadataType, JsonSchema> = {
14
- string: { type: 'string', maxLength: 4096 },
15
- 'string[]': array({ type: 'string', maxLength: 4096 }),
16
- number: { type: 'number' },
17
- boolean: { type: 'boolean' },
18
- datetime: timestamp,
19
- };
20
- const metadataValue: JsonSchema = { anyOf: [string(), array(string()), { type: 'number' }, { type: 'boolean' }] };
21
- // Output metadata can reflect a schema refreshed by describe after tool creation.
22
- const outputMetadata: JsonSchema = { type: 'object', additionalProperties: metadataValue };
23
- const attributes = { timestamp, metadata: outputMetadata };
24
- const usage = object({ elapsedMs: { type: 'number', minimum: 0 }, databaseRequests: { type: 'integer', minimum: 0 } },
25
- ['elapsedMs', 'databaseRequests']);
26
- const error = object({ code: string(), message: string(), status: { type: 'integer' },
27
- details: object({ completedIds: array(id), uncertainIds: array(id), notAttemptedIds: array(id) }),
28
- }, ['code', 'message']);
29
-
30
- function metadataInput(schema: MetadataSchema): JsonSchema {
31
- return object(Object.fromEntries(Object.entries(schema).map(([name, field]) => [name, {
32
- ...scalarTypes[field.type], ...(field.description === undefined ? {} : { description: field.description }),
33
- }])));
34
- }
35
-
36
- function filterDefinition(schema: MetadataSchema): JsonSchema {
37
- const fields: Record<string, MetadataType> = { id: 'string', timestamp: 'datetime',
38
- ...Object.fromEntries(Object.entries(schema).map(([name, field]) => [`metadata.${name}`, field.type])),
39
- };
40
- const children = array({ $ref: '#/$defs/filter' }, { minItems: 1 });
41
- const branches: JsonSchema[] = [object({ and: children }, ['and']), object({ or: children }, ['or']),
42
- object({ field: { type: 'string', enum: Object.keys(fields) }, op: { const: 'exists' }, value: { type: 'boolean' } }, ['field', 'op', 'value'])];
43
- for (const type of ['string', 'number', 'boolean', 'datetime'] as const) {
44
- const names = Object.keys(fields).filter(name => fields[name] === type || (type === 'string' && fields[name] === 'string[]'));
45
- if (!names.length) continue;
46
- const field = { type: 'string', enum: names }, value = scalarTypes[type];
47
- const operators = type === 'number' || type === 'datetime' ? ['eq', 'neq', 'gt', 'gte', 'lt', 'lte'] : ['eq', 'neq'];
48
- branches.push(object({ field, op: { type: 'string', enum: operators }, value }, ['field', 'op', 'value']),
49
- object({ field, op: { const: 'in' }, value: array(value, { minItems: 1 }) }, ['field', 'op', 'value']));
50
- }
51
- return { anyOf: branches };
52
- }
53
-
54
- const descriptorSchema = object({
55
- name: string(), description: string(), labels: { type: 'object', additionalProperties: string() },
56
- metadataSchema: { type: 'object', additionalProperties: object({
57
- type: { type: 'string', enum: ['string', 'string[]', 'number', 'boolean', 'datetime'] }, description: string(),
58
- }, ['type']) },
59
- embedding: { anyOf: [
60
- object({ mode: { const: 'managed' }, provider: { const: 'openai' }, model: { const: 'text-embedding-3-small' },
61
- dimensions: { const: 1536 }, similarity: { const: 'cosine' } }, ['mode', 'provider', 'model', 'dimensions', 'similarity']),
62
- object({ mode: { const: 'external' }, dimensions: { type: 'integer', minimum: 64, maximum: 4096 },
63
- similarity: { const: 'cosine' }, identity: string() }, ['mode', 'dimensions', 'similarity', 'identity']),
64
- ] },
65
- textSearch: object({ analyzers: array(string(), { minItems: 1, uniqueItems: true }) }, ['analyzers']),
66
- }, ['name', 'labels', 'metadataSchema', 'embedding']);
67
-
68
- function resultSchema(value: JsonSchema): JsonSchema {
69
- return { $schema: dialect, type: 'object', anyOf: [
70
- object({ ok: { const: true }, value }, ['ok', 'value']),
71
- object({ ok: { const: false }, error }, ['ok', 'error']),
72
- ] };
73
- }
74
-
75
- /** Common definitions for direct tool calling and MCP; no provider wire format. */
76
- export function toolDefinitions(descriptor: DriveDescriptor, writable = false, shortIds = false, evidenceIds = false, retrieval = false): ToolDefinition[] {
77
- const external = descriptor.embedding.mode === 'external';
78
- const vector = array({ type: 'number' }, { minItems: descriptor.embedding.dimensions,
79
- maxItems: descriptor.embedding.dimensions, description: 'Caller-supplied embedding in this drive\'s vector space. Do not invent vector coordinates.' });
80
- const filter: JsonSchema = { $ref: '#/$defs/filter', description: 'Narrow by id, timestamp or declared metadata. Use explicit and/or arrays. Array eq/in test membership; neq requires a stored value and excludes matching elements. Discover fields with memdrive_describe.' };
81
- const exclusions = array(id, { uniqueItems: true, description: shortIds
82
- ? 'Exclude each returned session memory ID and all of its chunks, not only previously seen excerpts.'
83
- : 'Exclude each canonical Mem ID and all of its chunks. This excludes whole memories, not only previously seen chunks; do not use temporary aliases.' });
84
- const request = object({
85
- ...(external ? { queryVector: vector } : {
86
- query: { type: 'string', minLength: 1, description: 'Question or search terms. Cannot be the exact match-all expression *:*. Query and constructed context each have an 8 KiB native limit.' },
87
- context: string('Optional context relevant to this query; it is incorporated into the embedding and rerank query without an agent call.'),
88
- recentDialogue: array(object({ role: { type: 'string', enum: ['user', 'assistant'] }, content: string() }, ['role', 'content']),
89
- { description: 'Optional recent dialogue relevant to this query. No silent truncation is performed.' }),
90
- }),
91
- filter, excludeIds: exclusions,
92
- limit: { type: 'integer', minimum: 1, maximum: 1000, description: 'Maximum matches for this query; default 10.' },
93
- rerank: external ? { const: false, description: 'External vectors do not support reranking; omit or pass false.' }
94
- : { type: 'boolean', description: 'Use native reranking; default true. False preserves native search order.' },
95
- }, [external ? 'queryVector' : 'query']);
96
- const evidence = evidenceIds ? { evidenceId: string('Session evidence reference (e1, e2, ...); use for citations, not memory-ID inputs.') } : {};
97
- const evidenceRequired = evidenceIds ? ['evidenceId'] : [];
98
- const match = external
99
- ? object({ kind: { const: 'mem' }, memId: id, ...attributes, ...evidence }, ['kind', 'memId', ...evidenceRequired])
100
- : object({ kind: { type: 'string', enum: ['mem', 'chunk'] }, memId: id, content: string(),
101
- start: { type: 'integer', minimum: 0 }, end: { type: 'integer', minimum: 1 }, ...attributes, ...evidence },
102
- ['kind', 'memId', 'content', 'start', 'end', ...evidenceRequired]);
103
- const mem = object({ id, ...(!external ? { content: string() } : {}), ...attributes, ...evidence }, [...(external ? ['id'] : ['id', 'content']), ...evidenceRequired]);
104
- const completion = object({ status: { enum: ['completed', 'budget_exhausted', 'aborted', 'failed'] }, reason: string() }, ['status']);
105
- const counts = Object.fromEntries(['knownRecallDatabaseRequests', 'dataCalls', 'toolCalls', 'modelCalls', 'inputTokens', 'outputTokens', 'unknownUsageCalls']
106
- .map(key => [key, { type: 'integer', minimum: 0 }]));
107
- const retrievalUsage = object({ elapsedMs: { type: 'number', minimum: 0 }, databaseRequests: { type: ['integer', 'null'], minimum: 0 }, ...counts },
108
- ['elapsedMs', 'databaseRequests', ...Object.keys(counts)]);
109
- const resultUsage = retrieval ? retrievalUsage : usage;
110
- const completionFields = retrieval ? { completion } : {};
111
- const requiredCompletion = retrieval ? ['completion'] : [];
112
- const recallResult = { anyOf: [object({ matches: array(match), usage: resultUsage, ...completionFields }, ['matches', 'usage', ...requiredCompletion]),
113
- object({ error: object({ code: string(), message: string(), status: { type: 'integer' } }, ['code', 'message']), usage: resultUsage, ...completionFields }, ['error', 'usage', ...requiredCompletion])] };
114
- const countable = ['id', ...Object.entries(descriptor.metadataSchema)
115
- .filter(([, field]) => field.type === 'string' || field.type === 'string[]').map(([name]) => `metadata.${name}`)];
116
- const define = (name: ToolName, title: string, description: string, input: JsonSchema, output: JsonSchema,
117
- hasFilter = false, write: 'remember' | 'forget' | false = false): ToolDefinition => ({
118
- name, title, description: (shortIds && name !== 'memdrive_describe'
119
- ? description.replaceAll('canonical ', '').replaceAll('Canonical ', '')
120
- + ' Memory IDs are session aliases (m1, m2, ...). Reuse only returned aliases; raw IDs and invented aliases are rejected.'
121
- : description) + (evidenceIds && ['memdrive_recall', 'memdrive_read', 'memdrive_list'].includes(name)
122
- ? ' evidenceId identifies this exact returned evidence; reuse it for citations. Memory-ID inputs still use memId/id.' : ''),
123
- inputSchema: { $schema: dialect, ...input, ...(hasFilter ? { $defs: { filter: filterDefinition(descriptor.metadataSchema) } } : {}) },
124
- outputSchema: resultSchema(output),
125
- annotations: { readOnlyHint: !write, destructiveHint: !!write, idempotentHint: write !== 'remember', openWorldHint: false },
126
- });
127
- const definitions = [
128
- define('memdrive_recall', 'Search memories', retrieval
129
- ? 'Retrieve source evidence for 1 to 5 independent requests using the host-configured strategy. Requests run concurrently with isolated per-request budgets. Results preserve input order. Check each completion.status; incomplete retrieval returns no fallback matches. Model and strategy settings cannot be changed through tool arguments.'
130
- : external
131
- ? 'Search this drive with caller-supplied vectors; submit one to five independent requests, returned in input order. Results contain canonical memId values and metadata, without vectors or source text; the caller reconstructs originals. Inspect per-request errors and refine the supplied query when more evidence is needed.'
132
- : `Search stored memories for evidence relevant to one to five questions using ${descriptor.textSearch ? 'hybrid keyword and vector' : 'vector'} retrieval, with native reranking enabled by default. Independent requests run concurrently and results retain input order; kind mem is a complete original, while kind chunk is an excerpt with UTF-16 start/end offsets and memId identifies the original for memdrive_read. When evidence is missing, query the missing facts or narrow filters; results are not an answer and previous searches are not automatically excluded.`,
133
- object({ requests: array(request, { minItems: 1, maxItems: 5,
134
- description: 'Independent search requests; returned results correspond to this array by index.' }) }, ['requests']),
135
- object({ results: array(recallResult, { minItems: 1, maxItems: 5 }) }, ['results']), true),
136
- define('memdrive_read', 'Read original memories', external
137
- ? 'Read canonical memory references and metadata by ID. External-vector memories return neither source text nor vectors; the caller owns source reconstruction. Missing IDs are omitted.'
138
- : 'Read complete originals by canonical Mem ID when an excerpt needs surrounding context. Use memId from search results; kind mem already contains the complete original and needs no additional read. Missing IDs are omitted and originals are not truncated.',
139
- object({ ids: ids(shortIds ? 'Returned session memory IDs to read, usually matches[].memId from memdrive_recall.'
140
- : 'Canonical Mem IDs to read, usually matches[].memId from memdrive_recall.') }, ['ids']),
141
- object({ mems: array(mem) }, ['mems'])),
142
- define('memdrive_describe', 'Describe memory drive',
143
- 'Inspect the drive description, labels, declared metadata fields and their meanings, embedding configuration and text-search analyzers. Use this before constructing unfamiliar metadata filters or choosing fields to count. This is a fresh schema lookup, not a list of stored memories or metadata values.',
144
- object({}), descriptorSchema),
145
- define('memdrive_count_values', 'Count metadata values',
146
- 'Inspect value distributions for id or declared string/string[] metadata fields, over original memories rather than chunks. Filters and excluded Mem IDs restrict the population; an array can put one memory in multiple buckets, so bucket sums are not a memory total. Results may be cached for 60 seconds: asOf is the fetch time and hasMore=null means completeness is unknown at the native bucket limit.',
147
- object({ fields: array({ type: 'string', enum: countable }, { minItems: 1, maxItems: 5, uniqueItems: true,
148
- description: 'One to five keyword fields. Numeric, boolean and datetime fields can filter but cannot be counted.' }),
149
- filter, excludeIds: exclusions, limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Values per field; default 10, maximum 100.' } }, ['fields']),
150
- object({ values: { type: 'object', additionalProperties: object({
151
- buckets: array(object({ value: string(), count: { type: 'integer', minimum: 0 } }, ['value', 'count']), { maxItems: 100 }),
152
- hasMore: { type: ['boolean', 'null'] },
153
- }, ['buckets', 'hasMore']) }, asOf: string('ISO 8601 UTC fetch time.') }, ['values', 'asOf']), true),
154
- define('memdrive_list', 'List stored memories',
155
- 'Browse complete original memories when no relevance query is needed; this is inventory, not ranked search. Pass nextCursor unchanged as cursor to continue, including after an empty logical page. Listing uses committed state and may lag recent writes; use memdrive_read or memdrive_recall when the latest accepted write must be visible.',
156
- object({ limit: { type: 'integer', minimum: 1, maximum: 1000, description: 'Physical documents per page; default 100. Returned original memories may be fewer.' },
157
- cursor: { type: 'string', minLength: 1, description: 'Opaque nextCursor from the previous page; omit on the first request.' } }),
158
- object({ mems: array(mem), nextCursor: string() }, ['mems'])),
159
- ];
160
- if (writable) {
161
- const inputMem = object({ id: { ...id, description: 'Omit to generate an ID. Supplying an existing ID fully replaces that memory.' },
162
- ...(external ? { embedding: vector } : { content: { type: 'string', minLength: 1, description: 'Original memory text; the SDK handles chunking. Content must contain non-whitespace text.' } }),
163
- timestamp, metadata: { ...metadataInput(descriptor.metadataSchema), description: 'Declared application metadata only. Omitted fields are not preserved when replacing an existing memory.' },
164
- }, [external ? 'embedding' : 'content']);
165
- definitions.push(define('memdrive_remember', 'Store memories',
166
- 'Store new memories or fully replace existing memories with the supplied IDs, including metadata. Omit an ID to create a new memory; repeating such a request creates another memory. IDs are returned in input order; partial write errors distinguish completed, uncertain and unattempted IDs, so do not blindly retry the entire request.',
167
- object({ mems: array(inputMem, { minItems: 1, description: 'Memories to store; supplied IDs must be unique within this request.' }) }, ['mems']),
168
- object({ ids: array(id, { minItems: 1 }) }, ['ids']), false, 'remember'),
169
- define('memdrive_forget', 'Delete memories',
170
- 'Delete whole memories and their chunks by canonical IDs or a structured filter, never both. Filter deletion can affect many memories; use the intended scope explicitly. Missing IDs are harmless and success acknowledges the deletion request without reporting how many memories existed.',
171
- { type: 'object', anyOf: [object({ ids: ids('Canonical Mem IDs to delete.') }, ['ids']), object({ filter }, ['filter'])] },
172
- object({ acknowledged: { const: true } }, ['acknowledged']), true, 'forget'));
173
- }
174
- return definitions;
175
- }
@@ -1,57 +0,0 @@
1
- import { MemDriveError } from '../errors.js';
2
- import type { EvidenceReference } from './internal-types.js';
3
-
4
- const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);
5
- const canonical = (value: unknown): unknown => Array.isArray(value) ? value.map(canonical)
6
- : object(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
7
-
8
- /** References identify returned source spans, not model delivery or answer selection. */
9
- export function evidenceIds(external: boolean) {
10
- const references = new Map<string, EvidenceReference>();
11
- const sources = new Map<string, { alias: string; signature: string }>();
12
- const resolve = (id: string): EvidenceReference => {
13
- const reference = references.get(id);
14
- if (!reference) throw new MemDriveError('INVALID_INPUT', 'Use an evidence ID returned by this tool session.');
15
- return { ...reference };
16
- };
17
- const attach = (items: unknown[], originals: boolean): void => {
18
- const pending = new Map<string, { reference: EvidenceReference; signature: string }>();
19
- const rows = items.map(value => {
20
- if (!object(value)) throw new MemDriveError('INVALID_RESULT', 'Memory tool returned invalid evidence.');
21
- const memId = originals ? value.id : value.memId;
22
- if (typeof memId !== 'string') throw new MemDriveError('INVALID_RESULT', 'Memory tool returned invalid evidence.');
23
- const start = originals ? 0 : value.start, end = originals && typeof value.content === 'string' ? value.content.length : value.end;
24
- if (!external && !(typeof value.content === 'string' && Number.isSafeInteger(start) && Number.isSafeInteger(end)
25
- && (start as number) >= 0 && (end as number) > (start as number) && value.content.length === (end as number) - (start as number)))
26
- throw new MemDriveError('INVALID_RESULT', 'Memory tool returned invalid evidence bounds.');
27
- const reference: EvidenceReference = external ? { memId } : { memId, start: start as number, end: end as number };
28
- const key = JSON.stringify(reference);
29
- const signature = JSON.stringify(canonical({ content: value.content, timestamp: value.timestamp, metadata: value.metadata }));
30
- const previous = sources.get(key) ?? pending.get(key);
31
- if (previous && previous.signature !== signature)
32
- throw new MemDriveError('INVALID_RESULT', 'Source changed for an evidence ID in this tool session.');
33
- pending.set(key, { reference, signature });
34
- return { value, key };
35
- });
36
- // Validate the whole result first: a failed item must not allocate unreturned aliases.
37
- for (const [key, entry] of pending) if (!sources.has(key)) {
38
- const alias = `e${references.size + 1}`;
39
- sources.set(key, { alias, signature: entry.signature }); references.set(alias, entry.reference);
40
- }
41
- for (const { value, key } of rows) value.evidenceId = sources.get(key)!.alias;
42
- };
43
- const output = (name: string, value: Record<string, unknown>): void => {
44
- if (name === 'memdrive_recall' && Array.isArray(value.results)) {
45
- value.results = value.results.map(item => {
46
- if (!object(item) || !Array.isArray(item.matches)) return item;
47
- try { attach(item.matches, false); return item; }
48
- catch (cause) {
49
- if (!(cause instanceof MemDriveError)) throw cause;
50
- return { error: { code: cause.code, message: cause.message }, usage: item.usage,
51
- ...(item.completion === undefined ? {} : { completion: { status: 'failed', reason: cause.code } }) };
52
- }
53
- });
54
- } else if ((name === 'memdrive_read' || name === 'memdrive_list') && Array.isArray(value.mems)) attach(value.mems, true);
55
- };
56
- return { resolve, output };
57
- }
@@ -1,153 +0,0 @@
1
- import { MemDriveError } from '../errors.js';
2
- import type { Retriever } from '../retriever/types.js';
3
- import type { MemDrive } from '../types.js';
4
- import type { CountValuesRequest, ForgetRequest, ListRequest, MemInput, RecallRequest, RequestOptions } from '../types.js';
5
- import { toolDefinitions } from './definitions.js';
6
- import { evidenceIds as createEvidenceIds } from './evidence-ids.js';
7
- import { shortIds as createShortIds } from './short-ids.js';
8
- import type { ToolError, ToolResult } from './types.js';
9
- import type { InternalToolsOptions, InternalMemoryTools } from './internal-types.js';
10
-
11
- const object = (value: unknown): value is Record<string, unknown> => value !== null
12
- && typeof value === 'object' && !Array.isArray(value)
13
- && [Object.prototype, null].includes(Object.getPrototypeOf(value));
14
- function requireInput(condition: unknown, message: string): asserts condition {
15
- if (!condition) throw new MemDriveError('INVALID_INPUT', message);
16
- }
17
- function checkAbort(options: RequestOptions) {
18
- if (options.signal?.aborted) throw new MemDriveError('ABORTED', 'Operation aborted.');
19
- }
20
- function errorResult(cause: unknown): ToolResult {
21
- if (!(cause instanceof MemDriveError)) return { ok: false,
22
- error: { code: 'TOOL_EXECUTION_FAILED', message: 'Memory tool execution failed.' } };
23
- const error: ToolError = { code: cause.code, message: cause.message };
24
- if (Number.isInteger(cause.status)) error.status = cause.status!;
25
- // Preserve actionable write outcomes, never transport details, causes or stacks.
26
- if (cause.details) {
27
- const details: NonNullable<ToolError['details']> = {};
28
- for (const key of ['completedIds', 'uncertainIds', 'notAttemptedIds'] as const) {
29
- const value = cause.details[key];
30
- if (Array.isArray(value) && value.every((id): id is string => typeof id === 'string')) details[key] = [...value];
31
- }
32
- if (Object.keys(details).length) error.details = details;
33
- }
34
- return { ok: false, error };
35
- }
36
-
37
- /** Shared primitive factory. Internal retrieval sessions never provide configureRecall. */
38
- export async function createMemoryTools(configuration: InternalToolsOptions, options: RequestOptions = {},
39
- configureRecall?: (drive: MemDrive) => Promise<Retriever>): Promise<InternalMemoryTools> {
40
- requireInput(object(configuration) && Object.keys(configuration).every(key => ['drive', 'branch', 'writable', 'shortIds', 'evidenceIds', 'retrieval'].includes(key)),
41
- 'Use drive, optional branch, writable, shortIds evidenceIds and optional retrieval to create memory tools.');
42
- requireInput(configuration.writable === undefined || typeof configuration.writable === 'boolean', 'writable must be a boolean.');
43
- requireInput(configuration.shortIds === undefined || typeof configuration.shortIds === 'boolean', 'shortIds must be a boolean.');
44
- requireInput(configuration.evidenceIds === undefined || typeof configuration.evidenceIds === 'boolean', 'evidenceIds must be a boolean.');
45
- const { drive, branch, writable = false, shortIds = false, evidenceIds = false } = configuration;
46
- requireInput(!(shortIds || evidenceIds) || !writable, 'Session IDs require read-only memory tools.');
47
- requireInput(drive && typeof drive.describe === 'function' && typeof drive.recall === 'function', 'Provide a MemDrive handle.');
48
- const data = branch === undefined ? drive : drive.at({ branch });
49
- const descriptor = await drive.describe(options);
50
- checkAbort(options);
51
- let initialDescriptor = true;
52
- const retriever = configureRecall ? await configureRecall({ ...drive, ...data, describe: async request => {
53
- if (initialDescriptor) { initialDescriptor = false; return structuredClone(descriptor); }
54
- return drive.describe(request);
55
- } }) : undefined;
56
- const definitions = toolDefinitions(descriptor, writable, shortIds, evidenceIds, !!retriever);
57
- const ids = shortIds ? createShortIds() : undefined;
58
- const evidence = evidenceIds ? createEvidenceIds(descriptor.embedding.mode === 'external') : undefined;
59
- const enabled = new Set(definitions.map(tool => tool.name));
60
- return Object.freeze({
61
- get definitions() { return structuredClone(definitions); },
62
- resolveId: (id: string) => ids ? ids.resolve(id) : id,
63
- resolveEvidence: (id: string) => {
64
- if (!evidence) throw new MemDriveError('INVALID_INPUT', 'Evidence IDs are disabled for this tool session.');
65
- return evidence.resolve(id);
66
- },
67
- async execute(name: string, input: unknown, requestOptions: RequestOptions = {}): Promise<ToolResult> {
68
- try {
69
- requireInput(object(requestOptions) && Object.keys(requestOptions).every(key => key === 'signal'), 'Operation options accept only signal.');
70
- checkAbort(requestOptions);
71
- if (!enabled.has(name as (typeof definitions)[number]['name']))
72
- throw new MemDriveError('UNKNOWN_TOOL', 'Unknown or disabled memory tool.');
73
- requireInput(object(input), 'Tool arguments must be an object.');
74
- // Detach inputs before any SDK operation can yield. No coercion or null stripping.
75
- let args: Record<string, unknown>;
76
- try { args = structuredClone(input); }
77
- catch { throw new MemDriveError('INVALID_INPUT', 'Tool arguments must be cloneable data.'); }
78
- let value: unknown;
79
- switch (name) {
80
- case 'memdrive_recall': {
81
- requireInput(Object.keys(args).length === 1 && Array.isArray(args.requests)
82
- && args.requests.length >= 1 && args.requests.length <= 5,
83
- 'recall requires requests containing 1 to 5 search requests.');
84
- const aliasErrors = new Map<number, string>();
85
- if (ids) args.requests.forEach((request, index) => {
86
- try {
87
- const translated = structuredClone(request);
88
- ids.query(translated);
89
- (args.requests as unknown[])[index] = translated;
90
- }
91
- catch (cause) {
92
- if (!(cause instanceof MemDriveError)) throw cause;
93
- aliasErrors.set(index, cause.message);
94
- // Retain batch indices and SDK cancellation/validation order; {} cannot dispatch a query.
95
- (args.requests as unknown[])[index] = {};
96
- }
97
- });
98
- const received = retriever ? { results: await Promise.all((args.requests as RecallRequest[]).map(async request => {
99
- try { return await retriever.recall(request, requestOptions); }
100
- catch (cause) {
101
- const failure = errorResult(cause); if (failure.ok) throw cause;
102
- const native = cause instanceof MemDriveError ? cause.usage?.databaseRequests : undefined;
103
- return { error: failure.error, completion: { status: failure.error.code === 'ABORTED' ? 'aborted' : 'failed', reason: failure.error.code },
104
- usage: { elapsedMs: cause instanceof MemDriveError ? cause.usage?.elapsedMs ?? 0 : 0,
105
- databaseRequests: native ?? (failure.error.code === 'INVALID_INPUT' ? 0 : null),
106
- knownRecallDatabaseRequests: native ?? 0, dataCalls: native === undefined ? 0 : 1,
107
- toolCalls: 0, modelCalls: 0, inputTokens: 0, outputTokens: 0, unknownUsageCalls: 0 } };
108
- }
109
- })) } : await data.recall({ requests: args.requests as RecallRequest[] }, requestOptions);
110
- const recalled = aliasErrors.size ? structuredClone(received) : received;
111
- for (const [index, message] of aliasErrors) {
112
- const item = recalled.results[index];
113
- if (item && 'error' in item && item.error.code === 'INVALID_INPUT') item.error.message = message;
114
- }
115
- value = recalled;
116
- break;
117
- }
118
- case 'memdrive_read':
119
- ids?.read(args);
120
- value = await data.read(args as { ids: string[] }, requestOptions);
121
- break;
122
- case 'memdrive_describe':
123
- requireInput(Object.keys(args).length === 0, 'describe accepts an empty object.');
124
- value = await drive.describe(requestOptions);
125
- break;
126
- case 'memdrive_count_values':
127
- ids?.query(args);
128
- value = await data.countValues(args as unknown as CountValuesRequest, requestOptions);
129
- break;
130
- case 'memdrive_list':
131
- value = await data.list(args as ListRequest, requestOptions);
132
- break;
133
- case 'memdrive_remember':
134
- value = await data.remember(args as { mems: MemInput[] }, requestOptions);
135
- break;
136
- case 'memdrive_forget':
137
- await data.forget(args as unknown as ForgetRequest, requestOptions);
138
- value = { acknowledged: true };
139
- break;
140
- }
141
- requireInput(object(value), 'Memory tool returned an invalid result.');
142
- // Preserve settled SDK outcomes, including completed items in a canceled batch.
143
- // SDK outputs are JSON data. Every transport receives the same detached value.
144
- const detached = structuredClone(value);
145
- evidence?.output(name, detached);
146
- ids?.output(name, detached);
147
- return { ok: true, value: detached };
148
- } catch (cause) {
149
- return errorResult(cause);
150
- }
151
- },
152
- });
153
- }
@@ -1,25 +0,0 @@
1
- import type { RequestOptions } from '../types.js';
2
- import { requireInput } from '../errors.js';
3
- import { createRetriever } from '../retriever/index.js';
4
- import { createMemoryTools } from './factory.js';
5
- import type { CreateToolsOptions, MemoryTools } from './types.js';
6
- export type * from './types.js';
7
-
8
- /** Bind the existing tool catalog; optional orchestration changes only recall execution. */
9
- export async function createTools(configuration: CreateToolsOptions, options: RequestOptions = {}): Promise<MemoryTools> {
10
- requireInput(configuration !== null && typeof configuration === 'object' && !Array.isArray(configuration)
11
- && Object.keys(configuration).every(key => ['drive', 'branch', 'writable', 'retrieval'].includes(key)), 'Use drive, optional branch, writable and retrieval to create memory tools.');
12
- const retrieval = configuration?.retrieval;
13
- requireInput(retrieval === undefined || (retrieval !== null && typeof retrieval === 'object' && !Array.isArray(retrieval)
14
- && Object.keys(retrieval).every(key => ['strategy', 'agent', 'record'].includes(key))), 'Use documented retrieval options.');
15
- const agent = retrieval?.agent;
16
- const snapshot = retrieval === undefined ? undefined : { ...retrieval,
17
- ...(agent && typeof agent === 'object' && !Array.isArray(agent) ? { agent: { ...agent,
18
- model: typeof agent.model?.createSession === 'function' ? { createSession: agent.model.createSession.bind(agent.model) } : agent.model,
19
- ...(agent.limits && typeof agent.limits === 'object' && !Array.isArray(agent.limits) ? { limits: { ...agent.limits } } : {}),
20
- } } : {}),
21
- };
22
- const tools = await createMemoryTools(configuration, options, snapshot === undefined ? undefined
23
- : drive => createRetriever({ ...snapshot, drive }, options));
24
- return Object.freeze({ get definitions() { return tools.definitions; }, execute: tools.execute });
25
- }
@@ -1,12 +0,0 @@
1
- import type { CreateToolsOptions, MemoryTools } from './types.js';
2
-
3
- /** Internal model-session identities, never public memory-tool arguments or results. */
4
- export type EvidenceReference = { memId: string; start: number; end: number } | { memId: string };
5
- export interface InternalToolsOptions extends CreateToolsOptions {
6
- shortIds?: boolean;
7
- evidenceIds?: boolean;
8
- }
9
- export interface InternalMemoryTools extends MemoryTools {
10
- resolveId(id: string): string;
11
- resolveEvidence(id: string): EvidenceReference;
12
- }
@@ -1,58 +0,0 @@
1
- import { MemDriveError } from '../errors.js';
2
-
3
- const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);
4
-
5
- /** One read-only tool registry owns this map; never inspect arbitrary text for IDs. */
6
- export function shortIds() {
7
- const canonical = new Map<string, string>(), aliases = new Map<string, string>();
8
- const resolve = (id: unknown): string => {
9
- const value = typeof id === 'string' ? canonical.get(id) : undefined;
10
- if (value === undefined) throw new MemDriveError('INVALID_INPUT', 'Use a memory ID returned by this tool session.');
11
- return value;
12
- };
13
- const encode = (id: unknown): string => {
14
- if (typeof id !== 'string') throw new MemDriveError('INVALID_RESULT', 'Memory tool returned an invalid ID.');
15
- let alias = aliases.get(id);
16
- if (alias === undefined) {
17
- alias = `m${aliases.size + 1}`;
18
- aliases.set(id, alias); canonical.set(alias, id);
19
- }
20
- return alias;
21
- };
22
- const filter = (root: unknown): void => {
23
- const pending = [root], seen = new Set<object>();
24
- while (pending.length) {
25
- const value = pending.pop();
26
- if (!object(value) || seen.has(value)) continue;
27
- seen.add(value);
28
- const keys = Object.keys(value);
29
- // Leave malformed/cyclic expressions for the SDK's normal validation.
30
- if (keys.length === 1 && ['and', 'or'].includes(keys[0]!)) {
31
- const children = value[keys[0]!];
32
- if (Array.isArray(children)) for (const child of children) pending.push(child);
33
- } else if (keys.length === 3 && keys.every(key => ['field', 'op', 'value'].includes(key)) && value.field === 'id') {
34
- if (value.op === 'eq' || value.op === 'neq') value.value = resolve(value.value);
35
- else if (value.op === 'in' && Array.isArray(value.value)) value.value = value.value.map(resolve);
36
- }
37
- }
38
- };
39
- const query = (value: unknown): void => {
40
- if (!object(value)) return;
41
- if (Array.isArray(value.excludeIds)) value.excludeIds = value.excludeIds.map(resolve);
42
- filter(value.filter);
43
- };
44
- const output = (name: string, value: Record<string, unknown>): void => {
45
- if (name === 'memdrive_recall' && Array.isArray(value.results)) {
46
- for (const item of value.results) if (object(item) && Array.isArray(item.matches))
47
- for (const match of item.matches) if (object(match)) match.memId = encode(match.memId);
48
- } else if ((name === 'memdrive_read' || name === 'memdrive_list') && Array.isArray(value.mems)) {
49
- for (const mem of value.mems) if (object(mem)) mem.id = encode(mem.id);
50
- } else if (name === 'memdrive_count_values' && object(value.values) && object(value.values.id)
51
- && Array.isArray(value.values.id.buckets)) {
52
- for (const bucket of value.values.id.buckets) if (object(bucket)) bucket.value = encode(bucket.value);
53
- }
54
- };
55
- return { resolve, query, output, read: (args: Record<string, unknown>) => {
56
- if (Array.isArray(args.ids)) args.ids = args.ids.map(resolve);
57
- } };
58
- }
@@ -1,48 +0,0 @@
1
- import type { MemDrive, RequestOptions } from '../types.js';
2
- import type { CreateRetrieverOptions } from '../retriever/types.js';
3
-
4
- /** Portable JSON Schema; transport adapters may rename the containing field. */
5
- export type JsonSchema = Record<string, unknown>;
6
- export type ToolName = 'memdrive_recall' | 'memdrive_read' | 'memdrive_describe'
7
- | 'memdrive_count_values' | 'memdrive_list' | 'memdrive_remember' | 'memdrive_forget';
8
- export interface ToolAnnotations {
9
- readOnlyHint: boolean;
10
- destructiveHint: boolean;
11
- idempotentHint: boolean;
12
- openWorldHint: boolean;
13
- }
14
- export interface ToolDefinition {
15
- name: ToolName;
16
- title: string;
17
- description: string;
18
- inputSchema: JsonSchema;
19
- outputSchema: JsonSchema;
20
- annotations: ToolAnnotations;
21
- }
22
- export interface ToolError {
23
- code: string;
24
- message: string;
25
- status?: number;
26
- /** Accepted, uncertain and unattempted writes are never silently retried. */
27
- details?: {
28
- completedIds?: string[];
29
- uncertainIds?: string[];
30
- notAttemptedIds?: string[];
31
- };
32
- }
33
- /** Identical JSON data for direct function calls and MCP structured/text results. */
34
- export type ToolResult = { ok: true; value: Record<string, unknown> } | { ok: false; error: ToolError };
35
- export interface CreateToolsOptions {
36
- drive: MemDrive;
37
- /** Configure only recall orchestration; tool inventory and batch input stay unchanged. */
38
- retrieval?: Omit<CreateRetrieverOptions, 'drive'>;
39
- /** Omit to use the supplied handle's branch. Model arguments cannot change it. */
40
- branch?: string;
41
- /** Include remember and forget. Defaults to false. This is not authorization. */
42
- writable?: boolean;
43
- }
44
- export interface MemoryTools {
45
- /** Returns detached tool definitions that callers may adapt without changing execution. */
46
- readonly definitions: ToolDefinition[];
47
- execute(name: string, args: unknown, options?: RequestOptions): Promise<ToolResult>;
48
- }