@functional-systems/memdrive 0.0.0-stage → 0.1.0-dev.5

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 (97) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/LICENSE +201 -0
  3. package/README.md +229 -2
  4. package/dist/commonjs/chunking.d.ts +7 -0
  5. package/dist/commonjs/chunking.d.ts.map +1 -0
  6. package/dist/commonjs/chunking.js +46 -0
  7. package/dist/commonjs/chunking.js.map +1 -0
  8. package/dist/commonjs/errors.d.ts +17 -0
  9. package/dist/commonjs/errors.d.ts.map +1 -0
  10. package/dist/commonjs/errors.js +44 -0
  11. package/dist/commonjs/errors.js.map +1 -0
  12. package/dist/commonjs/filter.d.ts +30 -0
  13. package/dist/commonjs/filter.d.ts.map +1 -0
  14. package/dist/commonjs/filter.js +224 -0
  15. package/dist/commonjs/filter.js.map +1 -0
  16. package/dist/commonjs/index.d.ts +8 -0
  17. package/dist/commonjs/index.d.ts.map +1 -0
  18. package/dist/commonjs/index.js +343 -0
  19. package/dist/commonjs/index.js.map +1 -0
  20. package/dist/commonjs/package.json +3 -0
  21. package/dist/commonjs/storage.d.ts +274 -0
  22. package/dist/commonjs/storage.d.ts.map +1 -0
  23. package/dist/commonjs/storage.js +861 -0
  24. package/dist/commonjs/storage.js.map +1 -0
  25. package/dist/commonjs/tools/definitions.d.ts +5 -0
  26. package/dist/commonjs/tools/definitions.d.ts.map +1 -0
  27. package/dist/commonjs/tools/definitions.js +129 -0
  28. package/dist/commonjs/tools/definitions.js.map +1 -0
  29. package/dist/commonjs/tools/index.d.ts +6 -0
  30. package/dist/commonjs/tools/index.d.ts.map +1 -0
  31. package/dist/commonjs/tools/index.js +104 -0
  32. package/dist/commonjs/tools/index.js.map +1 -0
  33. package/dist/commonjs/tools/types.d.ts +50 -0
  34. package/dist/commonjs/tools/types.d.ts.map +1 -0
  35. package/dist/commonjs/tools/types.js +3 -0
  36. package/dist/commonjs/tools/types.js.map +1 -0
  37. package/dist/commonjs/types.d.ts +277 -0
  38. package/dist/commonjs/types.d.ts.map +1 -0
  39. package/dist/commonjs/types.js +3 -0
  40. package/dist/commonjs/types.js.map +1 -0
  41. package/dist/commonjs/values.d.ts +17 -0
  42. package/dist/commonjs/values.d.ts.map +1 -0
  43. package/dist/commonjs/values.js +90 -0
  44. package/dist/commonjs/values.js.map +1 -0
  45. package/dist/esm/chunking.d.ts +7 -0
  46. package/dist/esm/chunking.d.ts.map +1 -0
  47. package/dist/esm/chunking.js +42 -0
  48. package/dist/esm/chunking.js.map +1 -0
  49. package/dist/esm/errors.d.ts +17 -0
  50. package/dist/esm/errors.d.ts.map +1 -0
  51. package/dist/esm/errors.js +36 -0
  52. package/dist/esm/errors.js.map +1 -0
  53. package/dist/esm/filter.d.ts +30 -0
  54. package/dist/esm/filter.d.ts.map +1 -0
  55. package/dist/esm/filter.js +209 -0
  56. package/dist/esm/filter.js.map +1 -0
  57. package/dist/esm/index.d.ts +8 -0
  58. package/dist/esm/index.d.ts.map +1 -0
  59. package/dist/esm/index.js +335 -0
  60. package/dist/esm/index.js.map +1 -0
  61. package/dist/esm/package.json +3 -0
  62. package/dist/esm/storage.d.ts +274 -0
  63. package/dist/esm/storage.d.ts.map +1 -0
  64. package/dist/esm/storage.js +845 -0
  65. package/dist/esm/storage.js.map +1 -0
  66. package/dist/esm/tools/definitions.d.ts +5 -0
  67. package/dist/esm/tools/definitions.d.ts.map +1 -0
  68. package/dist/esm/tools/definitions.js +126 -0
  69. package/dist/esm/tools/definitions.js.map +1 -0
  70. package/dist/esm/tools/index.d.ts +6 -0
  71. package/dist/esm/tools/index.d.ts.map +1 -0
  72. package/dist/esm/tools/index.js +101 -0
  73. package/dist/esm/tools/index.js.map +1 -0
  74. package/dist/esm/tools/types.d.ts +50 -0
  75. package/dist/esm/tools/types.d.ts.map +1 -0
  76. package/dist/esm/tools/types.js +2 -0
  77. package/dist/esm/tools/types.js.map +1 -0
  78. package/dist/esm/types.d.ts +277 -0
  79. package/dist/esm/types.d.ts.map +1 -0
  80. package/dist/esm/types.js +2 -0
  81. package/dist/esm/types.js.map +1 -0
  82. package/dist/esm/values.d.ts +17 -0
  83. package/dist/esm/values.d.ts.map +1 -0
  84. package/dist/esm/values.js +87 -0
  85. package/dist/esm/values.js.map +1 -0
  86. package/docs/tools.md +163 -0
  87. package/package.json +100 -4
  88. package/src/chunking.ts +32 -0
  89. package/src/errors.ts +40 -0
  90. package/src/filter.ts +189 -0
  91. package/src/index.ts +323 -0
  92. package/src/storage.ts +765 -0
  93. package/src/tools/definitions.ts +156 -0
  94. package/src/tools/index.ts +97 -0
  95. package/src/tools/types.ts +45 -0
  96. package/src/types.ts +273 -0
  97. package/src/values.ts +103 -0
@@ -0,0 +1,156 @@
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): 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: 'Exclude each canonical Mem ID and all of its chunks. This excludes whole memories, not only previously seen chunks; do not use temporary aliases.' });
82
+ const request = object({
83
+ ...(external ? { queryVector: vector } : {
84
+ 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.' },
85
+ context: string('Optional context relevant to this query; it is incorporated into the embedding and rerank query without an agent call.'),
86
+ recentDialogue: array(object({ role: { type: 'string', enum: ['user', 'assistant'] }, content: string() }, ['role', 'content']),
87
+ { description: 'Optional recent dialogue relevant to this query. No silent truncation is performed.' }),
88
+ }),
89
+ filter, excludeIds: exclusions,
90
+ limit: { type: 'integer', minimum: 1, maximum: 1000, description: 'Maximum matches for this query; default 10.' },
91
+ rerank: external ? { const: false, description: 'External vectors do not support reranking; omit or pass false.' }
92
+ : { type: 'boolean', description: 'Use native reranking; default true. False preserves native search order.' },
93
+ }, [external ? 'queryVector' : 'query']);
94
+ const match = external
95
+ ? object({ kind: { const: 'mem' }, memId: id, ...attributes }, ['kind', 'memId'])
96
+ : object({ kind: { type: 'string', enum: ['mem', 'chunk'] }, memId: id, content: string(),
97
+ start: { type: 'integer', minimum: 0 }, end: { type: 'integer', minimum: 1 }, ...attributes },
98
+ ['kind', 'memId', 'content', 'start', 'end']);
99
+ const mem = object({ id, ...(!external ? { content: string() } : {}), ...attributes }, external ? ['id'] : ['id', 'content']);
100
+ const recallResult = { anyOf: [object({ matches: array(match), usage }, ['matches', 'usage']),
101
+ object({ error: object({ code: string(), message: string(), status: { type: 'integer' } }, ['code', 'message']), usage }, ['error', 'usage'])] };
102
+ const countable = ['id', ...Object.entries(descriptor.metadataSchema)
103
+ .filter(([, field]) => field.type === 'string' || field.type === 'string[]').map(([name]) => `metadata.${name}`)];
104
+ const define = (name: ToolName, title: string, description: string, input: JsonSchema, output: JsonSchema,
105
+ hasFilter = false, write: 'remember' | 'forget' | false = false): ToolDefinition => ({
106
+ name, title, description,
107
+ inputSchema: { $schema: dialect, ...input, ...(hasFilter ? { $defs: { filter: filterDefinition(descriptor.metadataSchema) } } : {}) },
108
+ outputSchema: resultSchema(output),
109
+ annotations: { readOnlyHint: !write, destructiveHint: !!write, idempotentHint: write !== 'remember', openWorldHint: false },
110
+ });
111
+ const definitions = [
112
+ define('memdrive_recall', 'Search memories', external
113
+ ? '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.'
114
+ : `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.`,
115
+ object({ requests: array(request, { minItems: 1, maxItems: 5,
116
+ description: 'Independent search requests; returned results correspond to this array by index.' }) }, ['requests']),
117
+ object({ results: array(recallResult, { minItems: 1, maxItems: 5 }) }, ['results']), true),
118
+ define('memdrive_read', 'Read original memories', external
119
+ ? '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.'
120
+ : '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.',
121
+ object({ ids: ids('Canonical Mem IDs to read, usually matches[].memId from memdrive_recall.') }, ['ids']),
122
+ object({ mems: array(mem) }, ['mems'])),
123
+ define('memdrive_describe', 'Describe memory drive',
124
+ '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.',
125
+ object({}), descriptorSchema),
126
+ define('memdrive_count_values', 'Count metadata values',
127
+ '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.',
128
+ object({ fields: array({ type: 'string', enum: countable }, { minItems: 1, maxItems: 5, uniqueItems: true,
129
+ description: 'One to five keyword fields. Numeric, boolean and datetime fields can filter but cannot be counted.' }),
130
+ filter, excludeIds: exclusions, limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Values per field; default 10, maximum 100.' } }, ['fields']),
131
+ object({ values: { type: 'object', additionalProperties: object({
132
+ buckets: array(object({ value: string(), count: { type: 'integer', minimum: 0 } }, ['value', 'count']), { maxItems: 100 }),
133
+ hasMore: { type: ['boolean', 'null'] },
134
+ }, ['buckets', 'hasMore']) }, asOf: string('ISO 8601 UTC fetch time.') }, ['values', 'asOf']), true),
135
+ define('memdrive_list', 'List stored memories',
136
+ '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.',
137
+ object({ limit: { type: 'integer', minimum: 1, maximum: 1000, description: 'Physical documents per page; default 100. Returned original memories may be fewer.' },
138
+ cursor: { type: 'string', minLength: 1, description: 'Opaque nextCursor from the previous page; omit on the first request.' } }),
139
+ object({ mems: array(mem), nextCursor: string() }, ['mems'])),
140
+ ];
141
+ if (writable) {
142
+ const inputMem = object({ id: { ...id, description: 'Omit to generate an ID. Supplying an existing ID fully replaces that memory.' },
143
+ ...(external ? { embedding: vector } : { content: { type: 'string', minLength: 1, description: 'Original memory text; the SDK handles chunking. Content must contain non-whitespace text.' } }),
144
+ timestamp, metadata: { ...metadataInput(descriptor.metadataSchema), description: 'Declared application metadata only. Omitted fields are not preserved when replacing an existing memory.' },
145
+ }, [external ? 'embedding' : 'content']);
146
+ definitions.push(define('memdrive_remember', 'Store memories',
147
+ '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.',
148
+ object({ mems: array(inputMem, { minItems: 1, description: 'Memories to store; supplied IDs must be unique within this request.' }) }, ['mems']),
149
+ object({ ids: array(id, { minItems: 1 }) }, ['ids']), false, 'remember'),
150
+ define('memdrive_forget', 'Delete memories',
151
+ '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.',
152
+ { type: 'object', anyOf: [object({ ids: ids('Canonical Mem IDs to delete.') }, ['ids']), object({ filter }, ['filter'])] },
153
+ object({ acknowledged: { const: true } }, ['acknowledged']), true, 'forget'));
154
+ }
155
+ return definitions;
156
+ }
@@ -0,0 +1,97 @@
1
+ import { MemDriveError } from '../index.js';
2
+ import type { CountValuesRequest, ForgetRequest, ListRequest, MemInput, RecallRequest, RequestOptions } from '../types.js';
3
+ import { toolDefinitions } from './definitions.js';
4
+ import type { CreateToolsOptions, MemoryTools, ToolError, ToolResult } from './types.js';
5
+
6
+ export type * from './types.js';
7
+
8
+ const object = (value: unknown): value is Record<string, unknown> => value !== null
9
+ && typeof value === 'object' && !Array.isArray(value)
10
+ && [Object.prototype, null].includes(Object.getPrototypeOf(value));
11
+ function requireInput(condition: unknown, message: string): asserts condition {
12
+ if (!condition) throw new MemDriveError('INVALID_INPUT', message);
13
+ }
14
+ function checkAbort(options: RequestOptions) {
15
+ if (options.signal?.aborted) throw new MemDriveError('ABORTED', 'Operation aborted.');
16
+ }
17
+ function errorResult(cause: unknown): ToolResult {
18
+ if (!(cause instanceof MemDriveError)) return { ok: false,
19
+ error: { code: 'TOOL_EXECUTION_FAILED', message: 'Memory tool execution failed.' } };
20
+ const error: ToolError = { code: cause.code, message: cause.message };
21
+ if (Number.isInteger(cause.status)) error.status = cause.status!;
22
+ // Preserve actionable write outcomes, never transport details, causes or stacks.
23
+ if (cause.details) {
24
+ const details: NonNullable<ToolError['details']> = {};
25
+ for (const key of ['completedIds', 'uncertainIds', 'notAttemptedIds'] as const) {
26
+ const value = cause.details[key];
27
+ if (Array.isArray(value) && value.every((id): id is string => typeof id === 'string')) details[key] = [...value];
28
+ }
29
+ if (Object.keys(details).length) error.details = details;
30
+ }
31
+ return { ok: false, error };
32
+ }
33
+
34
+ /** Bind portable tools to an already authorized drive; no model or MCP runtime. */
35
+ export async function createTools(configuration: CreateToolsOptions, options: RequestOptions = {}): Promise<MemoryTools> {
36
+ requireInput(object(configuration) && Object.keys(configuration).every(key => ['drive', 'branch', 'writable'].includes(key)),
37
+ 'Use drive, optional branch and writable to create memory tools.');
38
+ requireInput(configuration.writable === undefined || typeof configuration.writable === 'boolean', 'writable must be a boolean.');
39
+ const { drive, branch, writable = false } = configuration;
40
+ requireInput(drive && typeof drive.describe === 'function' && typeof drive.recall === 'function', 'Provide a MemDrive handle.');
41
+ const data = branch === undefined ? drive : drive.at({ branch });
42
+ const descriptor = await drive.describe(options);
43
+ checkAbort(options);
44
+ const definitions = toolDefinitions(descriptor, writable);
45
+ const enabled = new Set(definitions.map(tool => tool.name));
46
+ return Object.freeze({
47
+ get definitions() { return structuredClone(definitions); },
48
+ async execute(name: string, input: unknown, requestOptions: RequestOptions = {}): Promise<ToolResult> {
49
+ try {
50
+ requireInput(object(requestOptions) && Object.keys(requestOptions).every(key => key === 'signal'), 'Operation options accept only signal.');
51
+ checkAbort(requestOptions);
52
+ if (!enabled.has(name as (typeof definitions)[number]['name']))
53
+ throw new MemDriveError('UNKNOWN_TOOL', 'Unknown or disabled memory tool.');
54
+ requireInput(object(input), 'Tool arguments must be an object.');
55
+ // Detach inputs before any SDK operation can yield. No coercion or null stripping.
56
+ let args: Record<string, unknown>;
57
+ try { args = structuredClone(input); }
58
+ catch { throw new MemDriveError('INVALID_INPUT', 'Tool arguments must be cloneable data.'); }
59
+ let value: unknown;
60
+ switch (name) {
61
+ case 'memdrive_recall':
62
+ requireInput(Object.keys(args).length === 1 && Array.isArray(args.requests)
63
+ && args.requests.length >= 1 && args.requests.length <= 5,
64
+ 'recall requires requests containing 1 to 5 search requests.');
65
+ value = await data.recall({ requests: args.requests as RecallRequest[] }, requestOptions);
66
+ break;
67
+ case 'memdrive_read':
68
+ value = await data.read(args as { ids: string[] }, requestOptions);
69
+ break;
70
+ case 'memdrive_describe':
71
+ requireInput(Object.keys(args).length === 0, 'describe accepts an empty object.');
72
+ value = await drive.describe(requestOptions);
73
+ break;
74
+ case 'memdrive_count_values':
75
+ value = await data.countValues(args as unknown as CountValuesRequest, requestOptions);
76
+ break;
77
+ case 'memdrive_list':
78
+ value = await data.list(args as ListRequest, requestOptions);
79
+ break;
80
+ case 'memdrive_remember':
81
+ value = await data.remember(args as { mems: MemInput[] }, requestOptions);
82
+ break;
83
+ case 'memdrive_forget':
84
+ await data.forget(args as unknown as ForgetRequest, requestOptions);
85
+ value = { acknowledged: true };
86
+ break;
87
+ }
88
+ requireInput(object(value), 'Memory tool returned an invalid result.');
89
+ // Preserve settled SDK outcomes, including completed items in a canceled batch.
90
+ // SDK outputs are JSON data. Every transport receives the same detached value.
91
+ return { ok: true, value: structuredClone(value) };
92
+ } catch (cause) {
93
+ return errorResult(cause);
94
+ }
95
+ },
96
+ });
97
+ }
@@ -0,0 +1,45 @@
1
+ import type { MemDrive, RequestOptions } from '../types.js';
2
+
3
+ /** Portable JSON Schema; transport adapters may rename the containing field. */
4
+ export type JsonSchema = Record<string, unknown>;
5
+ export type ToolName = 'memdrive_recall' | 'memdrive_read' | 'memdrive_describe'
6
+ | 'memdrive_count_values' | 'memdrive_list' | 'memdrive_remember' | 'memdrive_forget';
7
+ export interface ToolAnnotations {
8
+ readOnlyHint: boolean;
9
+ destructiveHint: boolean;
10
+ idempotentHint: boolean;
11
+ openWorldHint: boolean;
12
+ }
13
+ export interface ToolDefinition {
14
+ name: ToolName;
15
+ title: string;
16
+ description: string;
17
+ inputSchema: JsonSchema;
18
+ outputSchema: JsonSchema;
19
+ annotations: ToolAnnotations;
20
+ }
21
+ export interface ToolError {
22
+ code: string;
23
+ message: string;
24
+ status?: number;
25
+ /** Accepted, uncertain and unattempted writes are never silently retried. */
26
+ details?: {
27
+ completedIds?: string[];
28
+ uncertainIds?: string[];
29
+ notAttemptedIds?: string[];
30
+ };
31
+ }
32
+ /** Identical JSON data for direct function calls and MCP structured/text results. */
33
+ export type ToolResult = { ok: true; value: Record<string, unknown> } | { ok: false; error: ToolError };
34
+ export interface CreateToolsOptions {
35
+ drive: MemDrive;
36
+ /** Omit to use the supplied handle's branch. Model arguments cannot change it. */
37
+ branch?: string;
38
+ /** Include remember and forget. Defaults to false. This is not authorization. */
39
+ writable?: boolean;
40
+ }
41
+ export interface MemoryTools {
42
+ /** Returns detached tool definitions that callers may adapt without changing execution. */
43
+ readonly definitions: ToolDefinition[];
44
+ execute(name: string, args: unknown, options?: RequestOptions): Promise<ToolResult>;
45
+ }
package/src/types.ts ADDED
@@ -0,0 +1,273 @@
1
+ import type { LambdaDBClient } from '@functional-systems/lambdadb';
2
+ export type MetadataType = 'string' | 'string[]' | 'number' | 'boolean' | 'datetime';
3
+ export type MetadataValue = string | string[] | number | boolean;
4
+ export type Metadata = Record<string, MetadataValue>;
5
+ export type MetadataSchema = Record<string, {
6
+ type: MetadataType;
7
+ description?: string | undefined;
8
+ }>;
9
+ export interface RequestOptions {
10
+ signal?: AbortSignal | undefined;
11
+ }
12
+ export interface TextSearch {
13
+ analyzers: string[];
14
+ }
15
+ export interface ManagedEmbedding {
16
+ mode: 'managed';
17
+ provider: 'openai';
18
+ model: 'text-embedding-3-small';
19
+ dimensions: 1536;
20
+ similarity: 'cosine';
21
+ }
22
+ export interface ExternalEmbedding {
23
+ mode: 'external';
24
+ dimensions: number;
25
+ similarity: 'cosine';
26
+ identity: string;
27
+ }
28
+ export type EmbeddingOptions = {
29
+ mode: 'managed';
30
+ } | ExternalEmbedding;
31
+ export type EmbeddingConfig = ManagedEmbedding | ExternalEmbedding;
32
+ export interface MemAttributes {
33
+ timestamp?: string | undefined;
34
+ metadata?: Metadata | undefined;
35
+ }
36
+ export interface TextMemInput extends MemAttributes {
37
+ id?: string | undefined;
38
+ content: string;
39
+ embedding?: never;
40
+ }
41
+ export interface VectorMemInput extends MemAttributes {
42
+ id?: string | undefined;
43
+ embedding: number[];
44
+ content?: never;
45
+ }
46
+ export type MemInput = TextMemInput | VectorMemInput;
47
+ export interface TextMem extends MemAttributes {
48
+ id: string;
49
+ content: string;
50
+ }
51
+ /** External-vector reads return source references and metadata, not vectors. */
52
+ export interface VectorMem extends MemAttributes {
53
+ id: string;
54
+ content?: never;
55
+ }
56
+ export type Mem = TextMem | VectorMem;
57
+ export interface TextMatch extends MemAttributes {
58
+ kind: 'mem' | 'chunk';
59
+ memId: string;
60
+ content: string;
61
+ start: number;
62
+ end: number;
63
+ }
64
+ export interface VectorMatch extends MemAttributes {
65
+ kind: 'mem';
66
+ memId: string;
67
+ content?: never;
68
+ start?: never;
69
+ end?: never;
70
+ }
71
+ export type Match = TextMatch | VectorMatch;
72
+ export type FilterScalar = string | number | boolean;
73
+ export type Filter = {
74
+ and: Filter[];
75
+ or?: never;
76
+ field?: never;
77
+ op?: never;
78
+ value?: never;
79
+ } | {
80
+ or: Filter[];
81
+ and?: never;
82
+ field?: never;
83
+ op?: never;
84
+ value?: never;
85
+ } | {
86
+ field: string;
87
+ op: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
88
+ value: FilterScalar;
89
+ and?: never;
90
+ or?: never;
91
+ } | {
92
+ field: string;
93
+ op: 'in';
94
+ value: FilterScalar[];
95
+ and?: never;
96
+ or?: never;
97
+ } | {
98
+ field: string;
99
+ op: 'exists';
100
+ value: boolean;
101
+ and?: never;
102
+ or?: never;
103
+ };
104
+ export interface RecallOptions {
105
+ filter?: Filter | undefined;
106
+ excludeIds?: string[] | undefined;
107
+ limit?: number | undefined;
108
+ rerank?: boolean | undefined;
109
+ }
110
+ export interface TextRecallRequest extends RecallOptions {
111
+ query: string;
112
+ queryVector?: never;
113
+ context?: string | undefined;
114
+ recentDialogue?: Array<{
115
+ role: 'user' | 'assistant';
116
+ content: string;
117
+ }> | undefined;
118
+ }
119
+ export interface VectorRecallRequest extends Omit<RecallOptions, 'rerank'> {
120
+ queryVector: number[];
121
+ query?: never;
122
+ rerank?: false | undefined;
123
+ context?: never;
124
+ recentDialogue?: never;
125
+ }
126
+ export type RecallRequest = TextRecallRequest | VectorRecallRequest;
127
+ export interface Usage {
128
+ elapsedMs: number;
129
+ databaseRequests: number;
130
+ }
131
+ export interface RecallResult {
132
+ matches: Match[];
133
+ usage: Usage;
134
+ }
135
+ export interface RecallFailure {
136
+ error: {
137
+ code: string;
138
+ message: string;
139
+ status?: number;
140
+ };
141
+ usage: Usage;
142
+ }
143
+ export interface BatchRecallResult {
144
+ results: Array<RecallResult | RecallFailure>;
145
+ }
146
+ export interface Observation {
147
+ type: 'retrieved';
148
+ /** Diagnostic physical evidence IDs, not canonical memId values. */
149
+ ids: string[];
150
+ matches: Match[];
151
+ requestIndex?: number | undefined;
152
+ }
153
+ export type RecordEvent = Record<string, unknown> & {
154
+ phase: string;
155
+ requestIndex?: number | undefined;
156
+ };
157
+ export interface RuntimeOptions {
158
+ maxConcurrentRequests?: number | undefined;
159
+ observe?: ((event: Observation) => void | Promise<void>) | undefined;
160
+ record?: ((event: RecordEvent) => void | Promise<void>) | undefined;
161
+ }
162
+ export interface ConnectionOptions {
163
+ client: LambdaDBClient;
164
+ name: string;
165
+ }
166
+ export interface CreateOptions extends ConnectionOptions, RuntimeOptions {
167
+ metadataSchema: MetadataSchema;
168
+ textSearch?: TextSearch | undefined;
169
+ embedding?: EmbeddingOptions | undefined;
170
+ labels?: Record<string, string> | undefined;
171
+ description?: string | undefined;
172
+ }
173
+ export interface OpenOptions extends ConnectionOptions, RuntimeOptions {
174
+ branch?: string | undefined;
175
+ }
176
+ export interface DriveDescriptor {
177
+ name: string;
178
+ description?: string | undefined;
179
+ labels: Record<string, string>;
180
+ metadataSchema: MetadataSchema;
181
+ embedding: EmbeddingConfig;
182
+ textSearch?: TextSearch | undefined;
183
+ }
184
+ export interface CatalogRequest {
185
+ client: LambdaDBClient;
186
+ labels?: Record<string, string> | undefined;
187
+ limit?: number | undefined;
188
+ cursor?: string | undefined;
189
+ }
190
+ export interface CatalogResult {
191
+ drives: DriveDescriptor[];
192
+ nextCursor?: string | undefined;
193
+ }
194
+ export interface ListRequest {
195
+ limit?: number | undefined;
196
+ cursor?: string | undefined;
197
+ }
198
+ export interface ListResult {
199
+ mems: Mem[];
200
+ nextCursor?: string | undefined;
201
+ }
202
+ export type ForgetRequest = {
203
+ ids: string[];
204
+ filter?: never;
205
+ } | {
206
+ filter: Filter;
207
+ ids?: never;
208
+ };
209
+ export type ConfigureRequest = {
210
+ metadataSchema: MetadataSchema;
211
+ description?: string | undefined;
212
+ } | {
213
+ description: string;
214
+ metadataSchema?: MetadataSchema | undefined;
215
+ };
216
+ export interface BranchRequest {
217
+ name: string;
218
+ source?: {
219
+ branch: string;
220
+ } | undefined;
221
+ }
222
+ export type Branch = Awaited<ReturnType<ReturnType<LambdaDBClient['collection']>['branches']['create']>>['branch'];
223
+ /** Counts distinct keyword values across original memories, not chunks. */
224
+ export interface CountValuesRequest {
225
+ /** One to five distinct keyword fields, matching the native facet limit. */
226
+ fields: string[];
227
+ filter?: Filter | undefined;
228
+ excludeIds?: string[] | undefined;
229
+ /** Values per field: defaults to 10, maximum 100. */
230
+ limit?: number | undefined;
231
+ }
232
+ export interface CountValuesResult {
233
+ values: Record<string, {
234
+ buckets: Array<{ value: string; count: number }>;
235
+ /** Null when the native bucket limit prevents determining completeness. */
236
+ hasMore: boolean | null;
237
+ }>;
238
+ /** Time the cached result was fetched, in ISO 8601 UTC. */
239
+ asOf: string;
240
+ }
241
+ export interface DriveData {
242
+ readonly embedding: Readonly<EmbeddingConfig>;
243
+ remember(request: {
244
+ mems: MemInput[];
245
+ }, options?: RequestOptions): Promise<{
246
+ ids: string[];
247
+ }>;
248
+ read(request: {
249
+ ids: string[];
250
+ }, options?: RequestOptions): Promise<{
251
+ mems: Mem[];
252
+ }>;
253
+ list(request?: ListRequest, options?: RequestOptions): Promise<ListResult>;
254
+ countValues(request: CountValuesRequest, options?: RequestOptions): Promise<CountValuesResult>;
255
+ forget(request: ForgetRequest, options?: RequestOptions): Promise<void>;
256
+ recall(request: RecallRequest, options?: RequestOptions): Promise<RecallResult>;
257
+ recall(request: {
258
+ requests: RecallRequest[];
259
+ }, options?: RequestOptions): Promise<BatchRecallResult>;
260
+ }
261
+ export interface MemDrive extends DriveData {
262
+ at(reference: {
263
+ branch: string;
264
+ }): DriveData;
265
+ readonly branches: {
266
+ create(request: BranchRequest, options?: RequestOptions): Promise<Branch>;
267
+ list(options?: RequestOptions): Promise<Branch[]>;
268
+ delete(name: string, options?: RequestOptions): Promise<void>;
269
+ };
270
+ configure(request: ConfigureRequest, options?: RequestOptions): Promise<void>;
271
+ describe(options?: RequestOptions): Promise<DriveDescriptor>;
272
+ destroy(options?: RequestOptions): Promise<void>;
273
+ }