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

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 (107) hide show
  1. package/README.md +42 -13
  2. package/dist/commonjs/index.d.ts +2 -2
  3. package/dist/commonjs/index.d.ts.map +1 -1
  4. package/dist/commonjs/index.js +6 -34
  5. package/dist/commonjs/index.js.map +1 -1
  6. package/dist/commonjs/recall-input.d.ts +8 -0
  7. package/dist/commonjs/recall-input.d.ts.map +1 -0
  8. package/dist/commonjs/recall-input.js +45 -0
  9. package/dist/commonjs/recall-input.js.map +1 -0
  10. package/dist/commonjs/retriever/index.d.ts +7 -0
  11. package/dist/commonjs/retriever/index.d.ts.map +1 -0
  12. package/dist/commonjs/retriever/index.js +167 -0
  13. package/dist/commonjs/retriever/index.js.map +1 -0
  14. package/dist/commonjs/retriever/scope.d.ts +5 -0
  15. package/dist/commonjs/retriever/scope.d.ts.map +1 -0
  16. package/dist/commonjs/retriever/scope.js +69 -0
  17. package/dist/commonjs/retriever/scope.js.map +1 -0
  18. package/dist/commonjs/retriever/types.d.ts +89 -0
  19. package/dist/commonjs/retriever/types.d.ts.map +1 -0
  20. package/dist/commonjs/retriever/types.js +3 -0
  21. package/dist/commonjs/retriever/types.js.map +1 -0
  22. package/dist/commonjs/tools/definitions.d.ts +1 -1
  23. package/dist/commonjs/tools/definitions.d.ts.map +1 -1
  24. package/dist/commonjs/tools/definitions.js +30 -12
  25. package/dist/commonjs/tools/definitions.js.map +1 -1
  26. package/dist/commonjs/tools/evidence-ids.d.ts +7 -0
  27. package/dist/commonjs/tools/evidence-ids.d.ts.map +1 -0
  28. package/dist/commonjs/tools/evidence-ids.js +71 -0
  29. package/dist/commonjs/tools/evidence-ids.js.map +1 -0
  30. package/dist/commonjs/tools/factory.d.ts +7 -0
  31. package/dist/commonjs/tools/factory.d.ts.map +1 -0
  32. package/dist/commonjs/tools/factory.js +169 -0
  33. package/dist/commonjs/tools/factory.js.map +1 -0
  34. package/dist/commonjs/tools/index.d.ts +1 -1
  35. package/dist/commonjs/tools/index.d.ts.map +1 -1
  36. package/dist/commonjs/tools/index.js +19 -98
  37. package/dist/commonjs/tools/index.js.map +1 -1
  38. package/dist/commonjs/tools/internal-types.d.ts +18 -0
  39. package/dist/commonjs/tools/internal-types.d.ts.map +1 -0
  40. package/dist/commonjs/tools/internal-types.js +3 -0
  41. package/dist/commonjs/tools/internal-types.js.map +1 -0
  42. package/dist/commonjs/tools/short-ids.d.ts +8 -0
  43. package/dist/commonjs/tools/short-ids.d.ts.map +1 -0
  44. package/dist/commonjs/tools/short-ids.js +81 -0
  45. package/dist/commonjs/tools/short-ids.js.map +1 -0
  46. package/dist/commonjs/tools/types.d.ts +3 -0
  47. package/dist/commonjs/tools/types.d.ts.map +1 -1
  48. package/dist/esm/index.d.ts +2 -2
  49. package/dist/esm/index.d.ts.map +1 -1
  50. package/dist/esm/index.js +5 -33
  51. package/dist/esm/index.js.map +1 -1
  52. package/dist/esm/recall-input.d.ts +8 -0
  53. package/dist/esm/recall-input.d.ts.map +1 -0
  54. package/dist/esm/recall-input.js +40 -0
  55. package/dist/esm/recall-input.js.map +1 -0
  56. package/dist/esm/retriever/index.d.ts +7 -0
  57. package/dist/esm/retriever/index.d.ts.map +1 -0
  58. package/dist/esm/retriever/index.js +163 -0
  59. package/dist/esm/retriever/index.js.map +1 -0
  60. package/dist/esm/retriever/scope.d.ts +5 -0
  61. package/dist/esm/retriever/scope.d.ts.map +1 -0
  62. package/dist/esm/retriever/scope.js +66 -0
  63. package/dist/esm/retriever/scope.js.map +1 -0
  64. package/dist/esm/retriever/types.d.ts +89 -0
  65. package/dist/esm/retriever/types.d.ts.map +1 -0
  66. package/dist/esm/retriever/types.js +2 -0
  67. package/dist/esm/retriever/types.js.map +1 -0
  68. package/dist/esm/tools/definitions.d.ts +1 -1
  69. package/dist/esm/tools/definitions.d.ts.map +1 -1
  70. package/dist/esm/tools/definitions.js +30 -12
  71. package/dist/esm/tools/definitions.js.map +1 -1
  72. package/dist/esm/tools/evidence-ids.d.ts +7 -0
  73. package/dist/esm/tools/evidence-ids.d.ts.map +1 -0
  74. package/dist/esm/tools/evidence-ids.js +68 -0
  75. package/dist/esm/tools/evidence-ids.js.map +1 -0
  76. package/dist/esm/tools/factory.d.ts +7 -0
  77. package/dist/esm/tools/factory.d.ts.map +1 -0
  78. package/dist/esm/tools/factory.js +166 -0
  79. package/dist/esm/tools/factory.js.map +1 -0
  80. package/dist/esm/tools/index.d.ts +1 -1
  81. package/dist/esm/tools/index.d.ts.map +1 -1
  82. package/dist/esm/tools/index.js +19 -98
  83. package/dist/esm/tools/index.js.map +1 -1
  84. package/dist/esm/tools/internal-types.d.ts +18 -0
  85. package/dist/esm/tools/internal-types.d.ts.map +1 -0
  86. package/dist/esm/tools/internal-types.js +2 -0
  87. package/dist/esm/tools/internal-types.js.map +1 -0
  88. package/dist/esm/tools/short-ids.d.ts +8 -0
  89. package/dist/esm/tools/short-ids.d.ts.map +1 -0
  90. package/dist/esm/tools/short-ids.js +78 -0
  91. package/dist/esm/tools/short-ids.js.map +1 -0
  92. package/dist/esm/tools/types.d.ts +3 -0
  93. package/dist/esm/tools/types.d.ts.map +1 -1
  94. package/docs/tools.md +105 -4
  95. package/package.json +18 -5
  96. package/src/index.ts +6 -36
  97. package/src/recall-input.ts +46 -0
  98. package/src/retriever/index.ts +142 -0
  99. package/src/retriever/scope.ts +56 -0
  100. package/src/retriever/types.ts +68 -0
  101. package/src/tools/definitions.ts +30 -11
  102. package/src/tools/evidence-ids.ts +57 -0
  103. package/src/tools/factory.ts +153 -0
  104. package/src/tools/index.ts +21 -93
  105. package/src/tools/internal-types.ts +12 -0
  106. package/src/tools/short-ids.ts +58 -0
  107. package/src/tools/types.ts +3 -0
@@ -73,12 +73,14 @@ function resultSchema(value: JsonSchema): JsonSchema {
73
73
  }
74
74
 
75
75
  /** Common definitions for direct tool calling and MCP; no provider wire format. */
76
- export function toolDefinitions(descriptor: DriveDescriptor, writable = false): ToolDefinition[] {
76
+ export function toolDefinitions(descriptor: DriveDescriptor, writable = false, shortIds = false, evidenceIds = false, retrieval = false): ToolDefinition[] {
77
77
  const external = descriptor.embedding.mode === 'external';
78
78
  const vector = array({ type: 'number' }, { minItems: descriptor.embedding.dimensions,
79
79
  maxItems: descriptor.embedding.dimensions, description: 'Caller-supplied embedding in this drive\'s vector space. Do not invent vector coordinates.' });
80
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.' });
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.' });
82
84
  const request = object({
83
85
  ...(external ? { queryVector: vector } : {
84
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.' },
@@ -91,25 +93,41 @@ export function toolDefinitions(descriptor: DriveDescriptor, writable = false):
91
93
  rerank: external ? { const: false, description: 'External vectors do not support reranking; omit or pass false.' }
92
94
  : { type: 'boolean', description: 'Use native reranking; default true. False preserves native search order.' },
93
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'] : [];
94
98
  const match = external
95
- ? object({ kind: { const: 'mem' }, memId: id, ...attributes }, ['kind', 'memId'])
99
+ ? object({ kind: { const: 'mem' }, memId: id, ...attributes, ...evidence }, ['kind', 'memId', ...evidenceRequired])
96
100
  : 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'])] };
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])] };
102
114
  const countable = ['id', ...Object.entries(descriptor.metadataSchema)
103
115
  .filter(([, field]) => field.type === 'string' || field.type === 'string[]').map(([name]) => `metadata.${name}`)];
104
116
  const define = (name: ToolName, title: string, description: string, input: JsonSchema, output: JsonSchema,
105
117
  hasFilter = false, write: 'remember' | 'forget' | false = false): ToolDefinition => ({
106
- name, title, description,
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.' : ''),
107
123
  inputSchema: { $schema: dialect, ...input, ...(hasFilter ? { $defs: { filter: filterDefinition(descriptor.metadataSchema) } } : {}) },
108
124
  outputSchema: resultSchema(output),
109
125
  annotations: { readOnlyHint: !write, destructiveHint: !!write, idempotentHint: write !== 'remember', openWorldHint: false },
110
126
  });
111
127
  const definitions = [
112
- define('memdrive_recall', 'Search memories', external
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
113
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.'
114
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.`,
115
133
  object({ requests: array(request, { minItems: 1, maxItems: 5,
@@ -118,7 +136,8 @@ export function toolDefinitions(descriptor: DriveDescriptor, writable = false):
118
136
  define('memdrive_read', 'Read original memories', external
119
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.'
120
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.',
121
- object({ ids: ids('Canonical Mem IDs to read, usually matches[].memId from memdrive_recall.') }, ['ids']),
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']),
122
141
  object({ mems: array(mem) }, ['mems'])),
123
142
  define('memdrive_describe', 'Describe memory drive',
124
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.',
@@ -0,0 +1,57 @@
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
+ }
@@ -0,0 +1,153 @@
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,97 +1,25 @@
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
-
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
6
  export type * from './types.js';
7
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. */
8
+ /** Bind the existing tool catalog; optional orchestration changes only recall execution. */
35
9
  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
- });
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 });
97
25
  }
@@ -0,0 +1,12 @@
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
+ }
@@ -0,0 +1,58 @@
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,4 +1,5 @@
1
1
  import type { MemDrive, RequestOptions } from '../types.js';
2
+ import type { CreateRetrieverOptions } from '../retriever/types.js';
2
3
 
3
4
  /** Portable JSON Schema; transport adapters may rename the containing field. */
4
5
  export type JsonSchema = Record<string, unknown>;
@@ -33,6 +34,8 @@ export interface ToolError {
33
34
  export type ToolResult = { ok: true; value: Record<string, unknown> } | { ok: false; error: ToolError };
34
35
  export interface CreateToolsOptions {
35
36
  drive: MemDrive;
37
+ /** Configure only recall orchestration; tool inventory and batch input stay unchanged. */
38
+ retrieval?: Omit<CreateRetrieverOptions, 'drive'>;
36
39
  /** Omit to use the supplied handle's branch. Model arguments cannot change it. */
37
40
  branch?: string;
38
41
  /** Include remember and forget. Defaults to false. This is not authorization. */