stratagate-dsh 0.3.33 → 0.3.35

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 (41) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/CONTRIBUTING.md +88 -88
  3. package/CONTRIBUTING.zh-CN.md +88 -88
  4. package/LICENSE +21 -21
  5. package/README.md +487 -487
  6. package/README.zh-CN.md +491 -491
  7. package/benchmarks/locomo-conv26-r8-final.json +146 -146
  8. package/cordis.patch.yml +16 -16
  9. package/dist/client.d.ts +1 -1
  10. package/dist/client.js +4 -4
  11. package/dist/index.d.ts +3 -0
  12. package/dist/index.js.map +1 -1
  13. package/dist/plugin.d.ts +3 -0
  14. package/dist/plugin.js +992 -157
  15. package/dist/plugin.js.map +1 -1
  16. package/dist/repair-profile.js.map +1 -1
  17. package/docs/ARCHITECTURE.md +282 -282
  18. package/docs/DSH.md +337 -331
  19. package/docs/DSH.zh-CN.md +315 -309
  20. package/docs/EVALUATION.md +189 -189
  21. package/docs/EXTERNAL_MEMORY_IMPORT.zh-CN.md +99 -99
  22. package/docs/MEMORY_TOPICS.zh-CN.md +51 -51
  23. package/docs/benchmarks/issue-128-windows-review.json +104 -104
  24. package/docs/benchmarks/issue-128-windows.json +103 -103
  25. package/docs/database-access.md +32 -0
  26. package/docs/dreaming-agent.md +69 -69
  27. package/docs/event-extractor.md +48 -48
  28. package/docs/feedback.md +50 -50
  29. package/docs/issue-128-lease-cache-review-followup.md +55 -55
  30. package/docs/issue-128-review-followup.md +58 -58
  31. package/docs/knowledge-graph.md +38 -38
  32. package/docs/npm-release.md +53 -53
  33. package/docs/surface-maintenance.md +36 -36
  34. package/docs/user-operation-priority.md +39 -39
  35. package/docs/validation/issue119.md +41 -41
  36. package/docs/validation/workspace-cleanup-20261020.md +36 -36
  37. package/package.json +255 -255
  38. package/packages/core/examples/basic.ts +87 -87
  39. package/packages/core/src/blocks.ts +442 -442
  40. package/packages/core/src/weights.ts +21 -21
  41. package/screenshots.json +8 -8
@@ -1,442 +1,442 @@
1
- import type { BlockLevel, MemoryBlock, RawMessage, ToolTrace } from './types.js';
2
-
3
- export const DEFAULT_BLOCK_TURN_SIZE = 12;
4
- export const BLOCK_MAX_LEVEL = 5;
5
- export const BLOCK_DECAY_LAMBDA = 0.3;
6
-
7
- export interface BlockPosition {
8
- blockPosition: number;
9
- latestBlockPosition: number;
10
- }
11
-
12
- /** Sealed order is independent of derivation status and isolated per thread. */
13
- export function buildBlockTimeline(
14
- blocks: readonly Pick<MemoryBlock, 'id' | 'threadId' | 'sequence'>[],
15
- ): Map<string, BlockPosition> {
16
- const threads = new Map<string | undefined, typeof blocks[number][]>();
17
- for (const block of blocks) {
18
- const thread = threads.get(block.threadId) ?? [];
19
- thread.push(block);
20
- threads.set(block.threadId, thread);
21
- }
22
- const positions = new Map<string, BlockPosition>();
23
- for (const thread of threads.values()) {
24
- thread.sort((a, b) => a.sequence - b.sequence);
25
- thread.forEach((block, index) => positions.set(block.id, {
26
- blockPosition: index + 1,
27
- latestBlockPosition: thread.length,
28
- }));
29
- }
30
- return positions;
31
- }
32
-
33
- export function getBlockDecayView(
34
- block: Pick<MemoryBlock, 'pointerAnchorLevel' | 'pointerAnchorBlockPosition'>,
35
- position: BlockPosition,
36
- lambda = BLOCK_DECAY_LAMBDA,
37
- ): { age: number; level: BlockLevel } {
38
- return {
39
- age: Math.max(0, position.latestBlockPosition - position.blockPosition),
40
- level: getDecayedBlockLevel(block.pointerAnchorLevel, block.pointerAnchorBlockPosition, position.latestBlockPosition, lambda),
41
- };
42
- }
43
-
44
- const FILLER_ONLY = new Set([
45
- 'ok', 'okay', 'got it', 'thanks', 'thank you', 'yes', 'correct', 'sure',
46
- '好', '好的', '嗯', '嗯嗯', '明白', '收到', '谢谢', '感谢', '辛苦了',
47
- '是', '是的', '对', '对的', '没错', '可以', '行', '同意', '就这样',
48
- ]);
49
-
50
- const REPEATED_PASTE_MIN_CHARS = 80;
51
- const REPEATED_PASTE_MARKER = '[repeated paste omitted; original remains in L5]';
52
- const DERIVATION_SOURCE_FIELD_MIN_CHARS = 240;
53
- const DERIVATION_ARGUMENT_MAX_CHARS = 1_200;
54
- const DERIVATION_RESULT_MAX_CHARS = 2_400;
55
- const DERIVATION_TOOL_MESSAGE_MAX_CHARS = 2_400;
56
- const DERIVATION_SOURCE_FIELD = /^(?:code|command|program|script|source|sourcecode)$/u;
57
-
58
- function asBlockLevel(value: number): BlockLevel {
59
- return Math.max(0, Math.min(BLOCK_MAX_LEVEL, Math.round(value))) as BlockLevel;
60
- }
61
-
62
- export function getBlockWeight(
63
- anchorBlockPosition: number,
64
- latestBlockPosition: number,
65
- lambda = BLOCK_DECAY_LAMBDA,
66
- ): number {
67
- return Math.exp(-lambda * Math.max(0, latestBlockPosition - anchorBlockPosition));
68
- }
69
-
70
- export function getDecayedBlockLevel(
71
- anchorLevel: BlockLevel,
72
- anchorBlockPosition: number,
73
- latestBlockPosition: number,
74
- lambda = BLOCK_DECAY_LAMBDA,
75
- ): BlockLevel {
76
- const weight = getBlockWeight(anchorBlockPosition, latestBlockPosition, lambda);
77
- const droppedLevels = weight > 0.7
78
- ? 0
79
- : weight > 0.5
80
- ? 1
81
- : weight > 0.3
82
- ? 2
83
- : weight > 0.15
84
- ? 3
85
- : weight > 0.08
86
- ? 4
87
- : 5;
88
- return asBlockLevel(anchorLevel - droppedLevels);
89
- }
90
-
91
- export function normalizeBlockLevel(value: unknown, currentLevel: BlockLevel): BlockLevel {
92
- if (value === 'raw' || value === 'L5' || value === 5 || value === '5') return 5;
93
- if (value === 'next' || value === '+1' || value === undefined || value === null) return asBlockLevel(currentLevel + 1);
94
- if (typeof value === 'number' && Number.isFinite(value)) return asBlockLevel(value);
95
- if (typeof value === 'string' && /^L?[0-5]$/i.test(value.trim())) return asBlockLevel(Number(value.replace(/^L/i, '')));
96
- return asBlockLevel(currentLevel + 1);
97
- }
98
-
99
- export function blockLevelLabel(level: BlockLevel): string {
100
- return [
101
- 'L0 title and tags',
102
- 'L1 narrative summary',
103
- 'L2 key points',
104
- 'L3 rule-condensed transcript',
105
- 'L4 readable near-verbatim transcript',
106
- 'L5 raw transcript',
107
- ][level] ?? 'unknown';
108
- }
109
-
110
- function roleLabel(message: RawMessage, raw = false): string {
111
- const { role } = message;
112
- // Older synthetic provenance stored agent-authored facts with role=user.
113
- // Label their origin when rendering, keeping the stored source intact.
114
- if (role === 'user' && message.threadId?.startsWith('agent-memory:')) return 'Recorded';
115
- if (raw) return role;
116
- if (role === 'user') return 'User';
117
- if (role === 'assistant') return 'Assistant';
118
- if (role === 'tool') return 'Tool';
119
- return 'System';
120
- }
121
-
122
- function normalizedParagraph(value: string): string {
123
- return value.replace(/\s+/g, ' ').trim().toLocaleLowerCase();
124
- }
125
-
126
- function isFillerSentence(value: string): boolean {
127
- const normalized = value.trim().replace(/[。!?,、,.!?~~]+$/gu, '').trim().toLocaleLowerCase();
128
- return FILLER_ONLY.has(normalized);
129
- }
130
-
131
- function resultSummary(value: unknown): string {
132
- if (typeof value === 'string') {
133
- const text = value.replace(/\s+/g, ' ').trim();
134
- if (!text) return '';
135
- try {
136
- return resultSummary(JSON.parse(text));
137
- } catch {
138
- return text.slice(0, 160);
139
- }
140
- }
141
- if (typeof value === 'number' || typeof value === 'boolean') return String(value);
142
- if (!value || typeof value !== 'object') return '';
143
- const record = value as Record<string, unknown>;
144
- if (typeof record.error === 'string') return `failed: ${record.error.replace(/\s+/g, ' ').slice(0, 140)}`;
145
- if (typeof record.summary === 'string') return record.summary.replace(/\s+/g, ' ').slice(0, 160);
146
- if (typeof record.message === 'string') return record.message.replace(/\s+/g, ' ').slice(0, 160);
147
- const counts = Object.entries(record)
148
- .filter(([key, item]) => !['arguments', 'params', 'input', 'request'].includes(key) && Array.isArray(item))
149
- .map(([key, item]) => `${key}: ${(item as unknown[]).length}`);
150
- if (counts.length > 0) return counts.join(', ').slice(0, 160);
151
- if (record.ok === true) return 'completed';
152
- if (record.ok === false) return 'not completed';
153
- return 'structured result returned';
154
- }
155
-
156
- function serializedValue(value: unknown): string {
157
- if (typeof value === 'string') return value;
158
- try {
159
- return JSON.stringify(value) ?? String(value);
160
- } catch {
161
- return String(value);
162
- }
163
- }
164
-
165
- function sourceFieldName(value: string): boolean {
166
- return DERIVATION_SOURCE_FIELD.test(value.replace(/[\s_-]+/gu, '').toLocaleLowerCase());
167
- }
168
-
169
- function omitLargeSourceFields(value: unknown, key = '', seen = new WeakSet<object>()): unknown {
170
- if (typeof value === 'string') {
171
- if (!sourceFieldName(key) || value.length <= DERIVATION_SOURCE_FIELD_MIN_CHARS) return value;
172
- return `[${key || 'source'} omitted: ${value.length} chars; full value remains in L5]`;
173
- }
174
- if (!value || typeof value !== 'object') return value;
175
- if (seen.has(value)) return '[circular value omitted; full value remains in L5]';
176
- seen.add(value);
177
- if (Array.isArray(value)) return value.map((item) => omitLargeSourceFields(item, key, seen));
178
- return Object.fromEntries(Object.entries(value as Record<string, unknown>)
179
- .map(([nestedKey, nestedValue]) => [nestedKey, omitLargeSourceFields(nestedValue, nestedKey, seen)]));
180
- }
181
-
182
- function compactDerivationValue(value: unknown, maxChars: number, label: string): unknown {
183
- const rendered = serializedValue(value);
184
- if (rendered.length <= maxChars) return value;
185
- const summary = resultSummary(value);
186
- const headChars = Math.max(160, Math.floor(maxChars * 0.48));
187
- const tailChars = Math.max(80, Math.floor(maxChars * 0.2));
188
- const omittedChars = Math.max(0, rendered.length - headChars - tailChars);
189
- return {
190
- _stratagate: `${label} compacted; full value remains in L5`,
191
- originalChars: rendered.length,
192
- ...(summary ? { summary } : {}),
193
- head: rendered.slice(0, headChars),
194
- tail: rendered.slice(-tailChars),
195
- omittedChars,
196
- };
197
- }
198
-
199
- function compactDerivationText(value: string, maxChars: number, label: string): string {
200
- if (value.length <= maxChars) return value;
201
- const headChars = Math.max(160, Math.floor(maxChars * 0.6));
202
- const tailChars = Math.max(80, Math.floor(maxChars * 0.2));
203
- const omittedChars = Math.max(0, value.length - headChars - tailChars);
204
- return `${value.slice(0, headChars)}\n[${label} compacted: ${omittedChars} chars omitted; full value remains in L5]\n${value.slice(-tailChars)}`;
205
- }
206
-
207
- /**
208
- * Builds the structured, provenance-preserving transcript used by memory
209
- * derivation model calls. It never mutates or replaces the stored L5 layer.
210
- */
211
- export function buildMemoryDerivationMessages(messages: readonly RawMessage[]): RawMessage[] {
212
- return messages.map((message) => ({
213
- ...message,
214
- content: (message.role === 'tool' ? dailyToolJson(message.content) : undefined) ?? (message.role === 'tool'
215
- ? compactDerivationText(message.content, DERIVATION_TOOL_MESSAGE_MAX_CHARS, 'tool message content')
216
- : message.content),
217
- ...(message.toolCalls
218
- ? {
219
- toolCalls: message.toolCalls.map((trace) => {
220
- const daily = dailyToolSummary(trace);
221
- if (daily) return { name: trace.name, result: daily };
222
- const argumentsValue = trace.arguments === undefined
223
- ? undefined
224
- : compactDerivationValue(
225
- omitLargeSourceFields(trace.arguments),
226
- DERIVATION_ARGUMENT_MAX_CHARS,
227
- 'tool arguments',
228
- ) as Record<string, unknown>;
229
- return {
230
- name: trace.name,
231
- ...(argumentsValue === undefined ? {} : { arguments: argumentsValue }),
232
- ...(trace.result === undefined
233
- ? {}
234
- : { result: compactDerivationValue(trace.result, DERIVATION_RESULT_MAX_CHARS, 'tool result') }),
235
- };
236
- }),
237
- }
238
- : {}),
239
- }));
240
- }
241
-
242
- function dailyToolSummary(trace: ToolTrace): string | undefined {
243
- if (trace.name !== 'memory_daily_write' && trace.name !== 'memory_daily_read') return undefined;
244
- let result = trace.result;
245
- if (typeof result === 'string') { try { result = JSON.parse(result); } catch { result = {}; } }
246
- const saved = result && typeof result === 'object' ? result as Record<string, unknown> : {};
247
- const args = trace.arguments ?? {};
248
- const oneLine = (value: unknown) => String(value ?? '').replace(/[\r\n]+/g, ' ');
249
- return trace.name === 'memory_daily_write'
250
- ? `更新了 ${oneLine(saved.date ?? args.date ?? '今天')} 日记:《${oneLine(args.title)}》`
251
- : `读取了每日笔记(${oneLine(args.date ?? args.query ?? '最近日期')})`;
252
- }
253
-
254
- function dailyToolJson(text: string): string | undefined {
255
- try {
256
- const value = JSON.parse(text) as Record<string, unknown>;
257
- return dailyToolSummary({ name: String(value.name ?? value.tool ?? ''), arguments: (value.arguments ?? value.parameters) as Record<string, unknown>, result: value.result });
258
- } catch { return undefined; }
259
- }
260
-
261
- function summarizeToolTrace(trace: ToolTrace): string {
262
- const daily = dailyToolSummary(trace);
263
- if (daily) return daily;
264
- const summary = resultSummary(trace.result);
265
- return `Tool call: ${trace.name}${summary ? ` (${summary})` : ''}`;
266
- }
267
-
268
- function summarizeToolJson(value: string): string | null {
269
- const daily = dailyToolJson(value);
270
- if (daily) return daily;
271
- const trimmed = value.trim().replace(/^```(?:json)?\s*/iu, '').replace(/\s*```$/u, '');
272
- try {
273
- const parsed = JSON.parse(trimmed) as Record<string, unknown>;
274
- const names = new Set<string>();
275
- const visit = (item: unknown): void => {
276
- if (!item || typeof item !== 'object') return;
277
- if (Array.isArray(item)) {
278
- item.forEach(visit);
279
- return;
280
- }
281
- const record = item as Record<string, unknown>;
282
- if (typeof record.name === 'string' && ('arguments' in record || 'parameters' in record)) names.add(record.name);
283
- if (typeof record.tool === 'string') names.add(record.tool);
284
- if (record.function && typeof record.function === 'object') {
285
- const name = (record.function as Record<string, unknown>).name;
286
- if (typeof name === 'string') names.add(name);
287
- }
288
- Object.values(record).forEach(visit);
289
- };
290
- visit(parsed);
291
- if (names.size === 0) return null;
292
- const summary = resultSummary(parsed.result ?? parsed.content);
293
- return `Tool call: ${[...names].join(', ')}${summary ? ` (${summary})` : ''}`;
294
- } catch {
295
- if (!/(tool_calls|tool_call|"function"|"arguments")/iu.test(trimmed)) return null;
296
- const names = [...trimmed.matchAll(/"name"\s*:\s*"([^"\\]+)"/gu)].map((match) => match[1]);
297
- return names.length > 0 ? `Tool call: ${[...new Set(names)].join(', ')} (raw arguments omitted)` : 'Tool call (raw arguments omitted)';
298
- }
299
- }
300
-
301
- function removeStandaloneFillers(paragraph: string): string {
302
- const pieces = paragraph
303
- .split(/(?<=[。!?!?])|\n+/u)
304
- .map((piece) => piece.trim())
305
- .filter(Boolean);
306
- const kept = pieces.filter((piece) => !isFillerSentence(piece));
307
- if (kept.length === pieces.length) return paragraph.trim();
308
- return kept.join('\n');
309
- }
310
-
311
- function splitTextAndCode(source: string): Array<{ text: string; isCode: boolean }> {
312
- const parts: Array<{ text: string; isCode: boolean }> = [];
313
- const fencedCode = /```[\s\S]*?```/gu;
314
- let cursor = 0;
315
- for (const match of source.matchAll(fencedCode)) {
316
- const index = match.index ?? 0;
317
- if (index > cursor) parts.push({ text: source.slice(cursor, index), isCode: false });
318
- parts.push({ text: match[0], isCode: true });
319
- cursor = index + match[0].length;
320
- }
321
- if (cursor < source.length) parts.push({ text: source.slice(cursor), isCode: false });
322
- return parts;
323
- }
324
-
325
- function looksLikeCode(value: string): boolean {
326
- return /\n/u.test(value) && /(?:^|\n)\s*(?:const|let|var|function|class|import|export|def|SELECT|INSERT|UPDATE)\b|=>|[{};]/mu.test(value);
327
- }
328
-
329
- function condenseMessage(content: string): Array<{ text: string; pasteCandidate: boolean }> {
330
- const source = content.trim();
331
- const toolSummary = summarizeToolJson(source);
332
- if (toolSummary) return [{ text: toolSummary, pasteCandidate: false }];
333
- return splitTextAndCode(source).flatMap(({ text, isCode }) => {
334
- if (isCode) return text.trim() ? [{ text: text.trim(), pasteCandidate: true }] : [];
335
- return text
336
- .split(/\n\s*\n+/u)
337
- .map(removeStandaloneFillers)
338
- .filter(Boolean)
339
- .map((paragraph) => ({
340
- text: paragraph,
341
- pasteCandidate: looksLikeCode(paragraph) || normalizedParagraph(paragraph).length >= REPEATED_PASTE_MIN_CHARS,
342
- }));
343
- });
344
- }
345
-
346
- export function formatReadableTranscript(messages: readonly RawMessage[]): string {
347
- return messages
348
- .filter((message) => message.role !== 'system')
349
- .flatMap((message) => {
350
- const text = message.content.trim();
351
- const inline = message.role === 'tool' ? summarizeToolJson(text) ?? text : text;
352
- const lines = inline ? [`${roleLabel(message)}: ${inline}`] : [];
353
- lines.push(...(message.toolCalls ?? []).map(summarizeToolTrace));
354
- return lines;
355
- })
356
- .join('\n\n');
357
- }
358
-
359
- function renderRawToolTrace(trace: ToolTrace): string {
360
- return `Tool call (raw): ${JSON.stringify(trace)}`;
361
- }
362
-
363
- export function formatRawTranscript(messages: readonly RawMessage[]): string {
364
- return messages
365
- .flatMap((message) => [
366
- `${roleLabel(message, true)}: ${message.content}`,
367
- ...(message.toolCalls ?? []).map(renderRawToolTrace),
368
- ])
369
- .join('\n\n');
370
- }
371
-
372
- export function estimateTokens(value: string): number {
373
- let tokens = 0;
374
- let asciiRun = 0;
375
- const flushAscii = (): void => {
376
- if (asciiRun > 0) tokens += Math.ceil(asciiRun / 4);
377
- asciiRun = 0;
378
- };
379
- for (const character of value) {
380
- if (character.codePointAt(0)! <= 0x7f) asciiRun += 1;
381
- else {
382
- flushAscii();
383
- tokens += 1;
384
- }
385
- }
386
- flushAscii();
387
- return tokens;
388
- }
389
-
390
- export function condenseTranscript(messages: readonly RawMessage[]): string {
391
- const seen = new Set<string>();
392
- return messages
393
- .filter((message) => message.role !== 'system')
394
- .flatMap((message) => {
395
- const parts = [
396
- ...condenseMessage(message.content),
397
- ...(message.toolCalls ?? []).map((trace) => ({ text: summarizeToolTrace(trace), pasteCandidate: false })),
398
- ];
399
- const rendered = parts.map((part) => {
400
- if (!part.pasteCandidate) return part.text;
401
- const key = normalizedParagraph(part.text);
402
- if (!seen.has(key)) {
403
- seen.add(key);
404
- return part.text;
405
- }
406
- return REPEATED_PASTE_MARKER;
407
- });
408
- return rendered.length > 0 ? [`${roleLabel(message)}: ${rendered.join('\n\n')}`] : [];
409
- })
410
- .join('\n\n');
411
- }
412
-
413
- export function cloneRawMessages(messages: readonly RawMessage[]): RawMessage[] {
414
- return messages.map((message) => ({
415
- ...message,
416
- ...(message.toolCalls
417
- ? { toolCalls: message.toolCalls.map((trace) => ({
418
- ...trace,
419
- ...(trace.arguments ? { arguments: { ...trace.arguments } } : {}),
420
- })) }
421
- : {}),
422
- }));
423
- }
424
-
425
- export function deterministicBlockLayers(messages: readonly RawMessage[]): Pick<
426
- import('./types.js').BlockLayers,
427
- 'l3Condensed' | 'l4Readable' | 'l5Raw'
428
- > {
429
- const l5Rendered = formatRawTranscript(messages);
430
- const readable = formatReadableTranscript(messages);
431
- // Daily traces must never fall back to raw bodies, even for tiny calls where
432
- // the explanatory summary is longer than the original JSON.
433
- const hasDailyTrace = messages.some(message => message.toolCalls?.some(trace => dailyToolSummary(trace) !== undefined) || (message.role === 'tool' && dailyToolJson(message.content) !== undefined));
434
- const l4Readable = hasDailyTrace || estimateTokens(readable) <= estimateTokens(l5Rendered) ? readable : l5Rendered;
435
- const condensed = condenseTranscript(messages);
436
- const l3Condensed = estimateTokens(condensed) <= estimateTokens(l4Readable) ? condensed : l4Readable;
437
- return {
438
- l3Condensed,
439
- l4Readable,
440
- l5Raw: cloneRawMessages(messages),
441
- };
442
- }
1
+ import type { BlockLevel, MemoryBlock, RawMessage, ToolTrace } from './types.js';
2
+
3
+ export const DEFAULT_BLOCK_TURN_SIZE = 12;
4
+ export const BLOCK_MAX_LEVEL = 5;
5
+ export const BLOCK_DECAY_LAMBDA = 0.3;
6
+
7
+ export interface BlockPosition {
8
+ blockPosition: number;
9
+ latestBlockPosition: number;
10
+ }
11
+
12
+ /** Sealed order is independent of derivation status and isolated per thread. */
13
+ export function buildBlockTimeline(
14
+ blocks: readonly Pick<MemoryBlock, 'id' | 'threadId' | 'sequence'>[],
15
+ ): Map<string, BlockPosition> {
16
+ const threads = new Map<string | undefined, typeof blocks[number][]>();
17
+ for (const block of blocks) {
18
+ const thread = threads.get(block.threadId) ?? [];
19
+ thread.push(block);
20
+ threads.set(block.threadId, thread);
21
+ }
22
+ const positions = new Map<string, BlockPosition>();
23
+ for (const thread of threads.values()) {
24
+ thread.sort((a, b) => a.sequence - b.sequence);
25
+ thread.forEach((block, index) => positions.set(block.id, {
26
+ blockPosition: index + 1,
27
+ latestBlockPosition: thread.length,
28
+ }));
29
+ }
30
+ return positions;
31
+ }
32
+
33
+ export function getBlockDecayView(
34
+ block: Pick<MemoryBlock, 'pointerAnchorLevel' | 'pointerAnchorBlockPosition'>,
35
+ position: BlockPosition,
36
+ lambda = BLOCK_DECAY_LAMBDA,
37
+ ): { age: number; level: BlockLevel } {
38
+ return {
39
+ age: Math.max(0, position.latestBlockPosition - position.blockPosition),
40
+ level: getDecayedBlockLevel(block.pointerAnchorLevel, block.pointerAnchorBlockPosition, position.latestBlockPosition, lambda),
41
+ };
42
+ }
43
+
44
+ const FILLER_ONLY = new Set([
45
+ 'ok', 'okay', 'got it', 'thanks', 'thank you', 'yes', 'correct', 'sure',
46
+ '好', '好的', '嗯', '嗯嗯', '明白', '收到', '谢谢', '感谢', '辛苦了',
47
+ '是', '是的', '对', '对的', '没错', '可以', '行', '同意', '就这样',
48
+ ]);
49
+
50
+ const REPEATED_PASTE_MIN_CHARS = 80;
51
+ const REPEATED_PASTE_MARKER = '[repeated paste omitted; original remains in L5]';
52
+ const DERIVATION_SOURCE_FIELD_MIN_CHARS = 240;
53
+ const DERIVATION_ARGUMENT_MAX_CHARS = 1_200;
54
+ const DERIVATION_RESULT_MAX_CHARS = 2_400;
55
+ const DERIVATION_TOOL_MESSAGE_MAX_CHARS = 2_400;
56
+ const DERIVATION_SOURCE_FIELD = /^(?:code|command|program|script|source|sourcecode)$/u;
57
+
58
+ function asBlockLevel(value: number): BlockLevel {
59
+ return Math.max(0, Math.min(BLOCK_MAX_LEVEL, Math.round(value))) as BlockLevel;
60
+ }
61
+
62
+ export function getBlockWeight(
63
+ anchorBlockPosition: number,
64
+ latestBlockPosition: number,
65
+ lambda = BLOCK_DECAY_LAMBDA,
66
+ ): number {
67
+ return Math.exp(-lambda * Math.max(0, latestBlockPosition - anchorBlockPosition));
68
+ }
69
+
70
+ export function getDecayedBlockLevel(
71
+ anchorLevel: BlockLevel,
72
+ anchorBlockPosition: number,
73
+ latestBlockPosition: number,
74
+ lambda = BLOCK_DECAY_LAMBDA,
75
+ ): BlockLevel {
76
+ const weight = getBlockWeight(anchorBlockPosition, latestBlockPosition, lambda);
77
+ const droppedLevels = weight > 0.7
78
+ ? 0
79
+ : weight > 0.5
80
+ ? 1
81
+ : weight > 0.3
82
+ ? 2
83
+ : weight > 0.15
84
+ ? 3
85
+ : weight > 0.08
86
+ ? 4
87
+ : 5;
88
+ return asBlockLevel(anchorLevel - droppedLevels);
89
+ }
90
+
91
+ export function normalizeBlockLevel(value: unknown, currentLevel: BlockLevel): BlockLevel {
92
+ if (value === 'raw' || value === 'L5' || value === 5 || value === '5') return 5;
93
+ if (value === 'next' || value === '+1' || value === undefined || value === null) return asBlockLevel(currentLevel + 1);
94
+ if (typeof value === 'number' && Number.isFinite(value)) return asBlockLevel(value);
95
+ if (typeof value === 'string' && /^L?[0-5]$/i.test(value.trim())) return asBlockLevel(Number(value.replace(/^L/i, '')));
96
+ return asBlockLevel(currentLevel + 1);
97
+ }
98
+
99
+ export function blockLevelLabel(level: BlockLevel): string {
100
+ return [
101
+ 'L0 title and tags',
102
+ 'L1 narrative summary',
103
+ 'L2 key points',
104
+ 'L3 rule-condensed transcript',
105
+ 'L4 readable near-verbatim transcript',
106
+ 'L5 raw transcript',
107
+ ][level] ?? 'unknown';
108
+ }
109
+
110
+ function roleLabel(message: RawMessage, raw = false): string {
111
+ const { role } = message;
112
+ // Older synthetic provenance stored agent-authored facts with role=user.
113
+ // Label their origin when rendering, keeping the stored source intact.
114
+ if (role === 'user' && message.threadId?.startsWith('agent-memory:')) return 'Recorded';
115
+ if (raw) return role;
116
+ if (role === 'user') return 'User';
117
+ if (role === 'assistant') return 'Assistant';
118
+ if (role === 'tool') return 'Tool';
119
+ return 'System';
120
+ }
121
+
122
+ function normalizedParagraph(value: string): string {
123
+ return value.replace(/\s+/g, ' ').trim().toLocaleLowerCase();
124
+ }
125
+
126
+ function isFillerSentence(value: string): boolean {
127
+ const normalized = value.trim().replace(/[。!?,、,.!?~~]+$/gu, '').trim().toLocaleLowerCase();
128
+ return FILLER_ONLY.has(normalized);
129
+ }
130
+
131
+ function resultSummary(value: unknown): string {
132
+ if (typeof value === 'string') {
133
+ const text = value.replace(/\s+/g, ' ').trim();
134
+ if (!text) return '';
135
+ try {
136
+ return resultSummary(JSON.parse(text));
137
+ } catch {
138
+ return text.slice(0, 160);
139
+ }
140
+ }
141
+ if (typeof value === 'number' || typeof value === 'boolean') return String(value);
142
+ if (!value || typeof value !== 'object') return '';
143
+ const record = value as Record<string, unknown>;
144
+ if (typeof record.error === 'string') return `failed: ${record.error.replace(/\s+/g, ' ').slice(0, 140)}`;
145
+ if (typeof record.summary === 'string') return record.summary.replace(/\s+/g, ' ').slice(0, 160);
146
+ if (typeof record.message === 'string') return record.message.replace(/\s+/g, ' ').slice(0, 160);
147
+ const counts = Object.entries(record)
148
+ .filter(([key, item]) => !['arguments', 'params', 'input', 'request'].includes(key) && Array.isArray(item))
149
+ .map(([key, item]) => `${key}: ${(item as unknown[]).length}`);
150
+ if (counts.length > 0) return counts.join(', ').slice(0, 160);
151
+ if (record.ok === true) return 'completed';
152
+ if (record.ok === false) return 'not completed';
153
+ return 'structured result returned';
154
+ }
155
+
156
+ function serializedValue(value: unknown): string {
157
+ if (typeof value === 'string') return value;
158
+ try {
159
+ return JSON.stringify(value) ?? String(value);
160
+ } catch {
161
+ return String(value);
162
+ }
163
+ }
164
+
165
+ function sourceFieldName(value: string): boolean {
166
+ return DERIVATION_SOURCE_FIELD.test(value.replace(/[\s_-]+/gu, '').toLocaleLowerCase());
167
+ }
168
+
169
+ function omitLargeSourceFields(value: unknown, key = '', seen = new WeakSet<object>()): unknown {
170
+ if (typeof value === 'string') {
171
+ if (!sourceFieldName(key) || value.length <= DERIVATION_SOURCE_FIELD_MIN_CHARS) return value;
172
+ return `[${key || 'source'} omitted: ${value.length} chars; full value remains in L5]`;
173
+ }
174
+ if (!value || typeof value !== 'object') return value;
175
+ if (seen.has(value)) return '[circular value omitted; full value remains in L5]';
176
+ seen.add(value);
177
+ if (Array.isArray(value)) return value.map((item) => omitLargeSourceFields(item, key, seen));
178
+ return Object.fromEntries(Object.entries(value as Record<string, unknown>)
179
+ .map(([nestedKey, nestedValue]) => [nestedKey, omitLargeSourceFields(nestedValue, nestedKey, seen)]));
180
+ }
181
+
182
+ function compactDerivationValue(value: unknown, maxChars: number, label: string): unknown {
183
+ const rendered = serializedValue(value);
184
+ if (rendered.length <= maxChars) return value;
185
+ const summary = resultSummary(value);
186
+ const headChars = Math.max(160, Math.floor(maxChars * 0.48));
187
+ const tailChars = Math.max(80, Math.floor(maxChars * 0.2));
188
+ const omittedChars = Math.max(0, rendered.length - headChars - tailChars);
189
+ return {
190
+ _stratagate: `${label} compacted; full value remains in L5`,
191
+ originalChars: rendered.length,
192
+ ...(summary ? { summary } : {}),
193
+ head: rendered.slice(0, headChars),
194
+ tail: rendered.slice(-tailChars),
195
+ omittedChars,
196
+ };
197
+ }
198
+
199
+ function compactDerivationText(value: string, maxChars: number, label: string): string {
200
+ if (value.length <= maxChars) return value;
201
+ const headChars = Math.max(160, Math.floor(maxChars * 0.6));
202
+ const tailChars = Math.max(80, Math.floor(maxChars * 0.2));
203
+ const omittedChars = Math.max(0, value.length - headChars - tailChars);
204
+ return `${value.slice(0, headChars)}\n[${label} compacted: ${omittedChars} chars omitted; full value remains in L5]\n${value.slice(-tailChars)}`;
205
+ }
206
+
207
+ /**
208
+ * Builds the structured, provenance-preserving transcript used by memory
209
+ * derivation model calls. It never mutates or replaces the stored L5 layer.
210
+ */
211
+ export function buildMemoryDerivationMessages(messages: readonly RawMessage[]): RawMessage[] {
212
+ return messages.map((message) => ({
213
+ ...message,
214
+ content: (message.role === 'tool' ? dailyToolJson(message.content) : undefined) ?? (message.role === 'tool'
215
+ ? compactDerivationText(message.content, DERIVATION_TOOL_MESSAGE_MAX_CHARS, 'tool message content')
216
+ : message.content),
217
+ ...(message.toolCalls
218
+ ? {
219
+ toolCalls: message.toolCalls.map((trace) => {
220
+ const daily = dailyToolSummary(trace);
221
+ if (daily) return { name: trace.name, result: daily };
222
+ const argumentsValue = trace.arguments === undefined
223
+ ? undefined
224
+ : compactDerivationValue(
225
+ omitLargeSourceFields(trace.arguments),
226
+ DERIVATION_ARGUMENT_MAX_CHARS,
227
+ 'tool arguments',
228
+ ) as Record<string, unknown>;
229
+ return {
230
+ name: trace.name,
231
+ ...(argumentsValue === undefined ? {} : { arguments: argumentsValue }),
232
+ ...(trace.result === undefined
233
+ ? {}
234
+ : { result: compactDerivationValue(trace.result, DERIVATION_RESULT_MAX_CHARS, 'tool result') }),
235
+ };
236
+ }),
237
+ }
238
+ : {}),
239
+ }));
240
+ }
241
+
242
+ function dailyToolSummary(trace: ToolTrace): string | undefined {
243
+ if (trace.name !== 'memory_daily_write' && trace.name !== 'memory_daily_read') return undefined;
244
+ let result = trace.result;
245
+ if (typeof result === 'string') { try { result = JSON.parse(result); } catch { result = {}; } }
246
+ const saved = result && typeof result === 'object' ? result as Record<string, unknown> : {};
247
+ const args = trace.arguments ?? {};
248
+ const oneLine = (value: unknown) => String(value ?? '').replace(/[\r\n]+/g, ' ');
249
+ return trace.name === 'memory_daily_write'
250
+ ? `更新了 ${oneLine(saved.date ?? args.date ?? '今天')} 日记:《${oneLine(args.title)}》`
251
+ : `读取了每日笔记(${oneLine(args.date ?? args.query ?? '最近日期')})`;
252
+ }
253
+
254
+ function dailyToolJson(text: string): string | undefined {
255
+ try {
256
+ const value = JSON.parse(text) as Record<string, unknown>;
257
+ return dailyToolSummary({ name: String(value.name ?? value.tool ?? ''), arguments: (value.arguments ?? value.parameters) as Record<string, unknown>, result: value.result });
258
+ } catch { return undefined; }
259
+ }
260
+
261
+ function summarizeToolTrace(trace: ToolTrace): string {
262
+ const daily = dailyToolSummary(trace);
263
+ if (daily) return daily;
264
+ const summary = resultSummary(trace.result);
265
+ return `Tool call: ${trace.name}${summary ? ` (${summary})` : ''}`;
266
+ }
267
+
268
+ function summarizeToolJson(value: string): string | null {
269
+ const daily = dailyToolJson(value);
270
+ if (daily) return daily;
271
+ const trimmed = value.trim().replace(/^```(?:json)?\s*/iu, '').replace(/\s*```$/u, '');
272
+ try {
273
+ const parsed = JSON.parse(trimmed) as Record<string, unknown>;
274
+ const names = new Set<string>();
275
+ const visit = (item: unknown): void => {
276
+ if (!item || typeof item !== 'object') return;
277
+ if (Array.isArray(item)) {
278
+ item.forEach(visit);
279
+ return;
280
+ }
281
+ const record = item as Record<string, unknown>;
282
+ if (typeof record.name === 'string' && ('arguments' in record || 'parameters' in record)) names.add(record.name);
283
+ if (typeof record.tool === 'string') names.add(record.tool);
284
+ if (record.function && typeof record.function === 'object') {
285
+ const name = (record.function as Record<string, unknown>).name;
286
+ if (typeof name === 'string') names.add(name);
287
+ }
288
+ Object.values(record).forEach(visit);
289
+ };
290
+ visit(parsed);
291
+ if (names.size === 0) return null;
292
+ const summary = resultSummary(parsed.result ?? parsed.content);
293
+ return `Tool call: ${[...names].join(', ')}${summary ? ` (${summary})` : ''}`;
294
+ } catch {
295
+ if (!/(tool_calls|tool_call|"function"|"arguments")/iu.test(trimmed)) return null;
296
+ const names = [...trimmed.matchAll(/"name"\s*:\s*"([^"\\]+)"/gu)].map((match) => match[1]);
297
+ return names.length > 0 ? `Tool call: ${[...new Set(names)].join(', ')} (raw arguments omitted)` : 'Tool call (raw arguments omitted)';
298
+ }
299
+ }
300
+
301
+ function removeStandaloneFillers(paragraph: string): string {
302
+ const pieces = paragraph
303
+ .split(/(?<=[。!?!?])|\n+/u)
304
+ .map((piece) => piece.trim())
305
+ .filter(Boolean);
306
+ const kept = pieces.filter((piece) => !isFillerSentence(piece));
307
+ if (kept.length === pieces.length) return paragraph.trim();
308
+ return kept.join('\n');
309
+ }
310
+
311
+ function splitTextAndCode(source: string): Array<{ text: string; isCode: boolean }> {
312
+ const parts: Array<{ text: string; isCode: boolean }> = [];
313
+ const fencedCode = /```[\s\S]*?```/gu;
314
+ let cursor = 0;
315
+ for (const match of source.matchAll(fencedCode)) {
316
+ const index = match.index ?? 0;
317
+ if (index > cursor) parts.push({ text: source.slice(cursor, index), isCode: false });
318
+ parts.push({ text: match[0], isCode: true });
319
+ cursor = index + match[0].length;
320
+ }
321
+ if (cursor < source.length) parts.push({ text: source.slice(cursor), isCode: false });
322
+ return parts;
323
+ }
324
+
325
+ function looksLikeCode(value: string): boolean {
326
+ return /\n/u.test(value) && /(?:^|\n)\s*(?:const|let|var|function|class|import|export|def|SELECT|INSERT|UPDATE)\b|=>|[{};]/mu.test(value);
327
+ }
328
+
329
+ function condenseMessage(content: string): Array<{ text: string; pasteCandidate: boolean }> {
330
+ const source = content.trim();
331
+ const toolSummary = summarizeToolJson(source);
332
+ if (toolSummary) return [{ text: toolSummary, pasteCandidate: false }];
333
+ return splitTextAndCode(source).flatMap(({ text, isCode }) => {
334
+ if (isCode) return text.trim() ? [{ text: text.trim(), pasteCandidate: true }] : [];
335
+ return text
336
+ .split(/\n\s*\n+/u)
337
+ .map(removeStandaloneFillers)
338
+ .filter(Boolean)
339
+ .map((paragraph) => ({
340
+ text: paragraph,
341
+ pasteCandidate: looksLikeCode(paragraph) || normalizedParagraph(paragraph).length >= REPEATED_PASTE_MIN_CHARS,
342
+ }));
343
+ });
344
+ }
345
+
346
+ export function formatReadableTranscript(messages: readonly RawMessage[]): string {
347
+ return messages
348
+ .filter((message) => message.role !== 'system')
349
+ .flatMap((message) => {
350
+ const text = message.content.trim();
351
+ const inline = message.role === 'tool' ? summarizeToolJson(text) ?? text : text;
352
+ const lines = inline ? [`${roleLabel(message)}: ${inline}`] : [];
353
+ lines.push(...(message.toolCalls ?? []).map(summarizeToolTrace));
354
+ return lines;
355
+ })
356
+ .join('\n\n');
357
+ }
358
+
359
+ function renderRawToolTrace(trace: ToolTrace): string {
360
+ return `Tool call (raw): ${JSON.stringify(trace)}`;
361
+ }
362
+
363
+ export function formatRawTranscript(messages: readonly RawMessage[]): string {
364
+ return messages
365
+ .flatMap((message) => [
366
+ `${roleLabel(message, true)}: ${message.content}`,
367
+ ...(message.toolCalls ?? []).map(renderRawToolTrace),
368
+ ])
369
+ .join('\n\n');
370
+ }
371
+
372
+ export function estimateTokens(value: string): number {
373
+ let tokens = 0;
374
+ let asciiRun = 0;
375
+ const flushAscii = (): void => {
376
+ if (asciiRun > 0) tokens += Math.ceil(asciiRun / 4);
377
+ asciiRun = 0;
378
+ };
379
+ for (const character of value) {
380
+ if (character.codePointAt(0)! <= 0x7f) asciiRun += 1;
381
+ else {
382
+ flushAscii();
383
+ tokens += 1;
384
+ }
385
+ }
386
+ flushAscii();
387
+ return tokens;
388
+ }
389
+
390
+ export function condenseTranscript(messages: readonly RawMessage[]): string {
391
+ const seen = new Set<string>();
392
+ return messages
393
+ .filter((message) => message.role !== 'system')
394
+ .flatMap((message) => {
395
+ const parts = [
396
+ ...condenseMessage(message.content),
397
+ ...(message.toolCalls ?? []).map((trace) => ({ text: summarizeToolTrace(trace), pasteCandidate: false })),
398
+ ];
399
+ const rendered = parts.map((part) => {
400
+ if (!part.pasteCandidate) return part.text;
401
+ const key = normalizedParagraph(part.text);
402
+ if (!seen.has(key)) {
403
+ seen.add(key);
404
+ return part.text;
405
+ }
406
+ return REPEATED_PASTE_MARKER;
407
+ });
408
+ return rendered.length > 0 ? [`${roleLabel(message)}: ${rendered.join('\n\n')}`] : [];
409
+ })
410
+ .join('\n\n');
411
+ }
412
+
413
+ export function cloneRawMessages(messages: readonly RawMessage[]): RawMessage[] {
414
+ return messages.map((message) => ({
415
+ ...message,
416
+ ...(message.toolCalls
417
+ ? { toolCalls: message.toolCalls.map((trace) => ({
418
+ ...trace,
419
+ ...(trace.arguments ? { arguments: { ...trace.arguments } } : {}),
420
+ })) }
421
+ : {}),
422
+ }));
423
+ }
424
+
425
+ export function deterministicBlockLayers(messages: readonly RawMessage[]): Pick<
426
+ import('./types.js').BlockLayers,
427
+ 'l3Condensed' | 'l4Readable' | 'l5Raw'
428
+ > {
429
+ const l5Rendered = formatRawTranscript(messages);
430
+ const readable = formatReadableTranscript(messages);
431
+ // Daily traces must never fall back to raw bodies, even for tiny calls where
432
+ // the explanatory summary is longer than the original JSON.
433
+ const hasDailyTrace = messages.some(message => message.toolCalls?.some(trace => dailyToolSummary(trace) !== undefined) || (message.role === 'tool' && dailyToolJson(message.content) !== undefined));
434
+ const l4Readable = hasDailyTrace || estimateTokens(readable) <= estimateTokens(l5Rendered) ? readable : l5Rendered;
435
+ const condensed = condenseTranscript(messages);
436
+ const l3Condensed = estimateTokens(condensed) <= estimateTokens(l4Readable) ? condensed : l4Readable;
437
+ return {
438
+ l3Condensed,
439
+ l4Readable,
440
+ l5Raw: cloneRawMessages(messages),
441
+ };
442
+ }