@mastra/mongodb 1.23.0-alpha.1 → 1.23.1-alpha.0
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.
- package/dist/_types/@internal_core/dist/memory/index.d.ts +102 -0
- package/dist/_types/@internal_core/package.json +1 -0
- package/dist/docs/SKILL.md +1 -1
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/reference-storage-retention.md +21 -18
- package/dist/index.cjs +618 -292
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +618 -292
- package/dist/index.js.map +1 -1
- package/dist/storage/domains/memory/index.d.ts +3 -0
- package/dist/storage/domains/memory/index.d.ts.map +1 -1
- package/package.json +7 -6
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
//#region src/memory/index.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Shared rules for observational memory lifecycle writes. Every storage adapter applies
|
|
4
|
+
* these inside its own atomic section (lock, transaction, or conditional update), so the
|
|
5
|
+
* decisions are identical across adapters.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Observational memory columns that lifecycle writes depend on. Storage adapters merge these
|
|
9
|
+
* into the table schema they get from `@mastra/core`, so the columns exist even when the
|
|
10
|
+
* installed core predates them.
|
|
11
|
+
*/
|
|
12
|
+
declare const OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS: {
|
|
13
|
+
readonly supersededBy: {
|
|
14
|
+
readonly type: 'text';
|
|
15
|
+
readonly nullable: true;
|
|
16
|
+
};
|
|
17
|
+
};
|
|
18
|
+
/** `schema` plus {@link OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS}; `undefined` when `schema` is. */
|
|
19
|
+
declare function withObservationalMemoryLifecycleColumns<T extends object>(schema: T | undefined): (T & typeof OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS) | undefined;
|
|
20
|
+
/**
|
|
21
|
+
* Result of `commitActiveObservations`.
|
|
22
|
+
*/
|
|
23
|
+
interface UpdateActiveObservationsResult {
|
|
24
|
+
/** Whether the observations were written. */
|
|
25
|
+
applied: boolean;
|
|
26
|
+
/**
|
|
27
|
+
* Why nothing was written: `retired` — the target record was superseded by a newer
|
|
28
|
+
* generation; `conflict` — `expectedActiveObservations` no longer matches the stored text.
|
|
29
|
+
*/
|
|
30
|
+
reason?: 'retired' | 'conflict';
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Result of `appendBufferedObservations`.
|
|
34
|
+
*
|
|
35
|
+
* The append targets the head generation: when `input.id` was superseded, the chunk is
|
|
36
|
+
* appended to the current head instead. The append is skipped (`persisted: false`) when the
|
|
37
|
+
* head already holds a chunk with the same `cycleId`, or when the chunk is wholly covered by
|
|
38
|
+
* the head's cursor. Chunks carry `lastObservedAt = max message time + 1ms`, so a chunk is
|
|
39
|
+
* wholly covered iff `head.lastObservedAt >= chunk.lastObservedAt - 1ms`.
|
|
40
|
+
*/
|
|
41
|
+
interface UpdateBufferedObservationsResult {
|
|
42
|
+
/** Whether the chunk was stored. */
|
|
43
|
+
persisted: boolean;
|
|
44
|
+
/** The record the chunk was written to (or would have been written to). */
|
|
45
|
+
recordId: string;
|
|
46
|
+
}
|
|
47
|
+
/** The fields of an observational memory record that decide head order. */
|
|
48
|
+
interface ObservationalMemoryHeadOrderFields {
|
|
49
|
+
generationCount: number;
|
|
50
|
+
createdAt: Date | string;
|
|
51
|
+
id: string;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Canonical head order: `generationCount DESC, createdAt ASC, id ASC`.
|
|
55
|
+
* Returns a negative number when `a` sorts before `b` (i.e. `a` is the better head candidate).
|
|
56
|
+
*/
|
|
57
|
+
declare function compareObservationalMemoryHeadOrder(a: ObservationalMemoryHeadOrderFields, b: ObservationalMemoryHeadOrderFields): number;
|
|
58
|
+
/**
|
|
59
|
+
* A buffered chunk stores `lastObservedAt = max message time + 1ms`. It is wholly covered
|
|
60
|
+
* (every message it observed is already at or before the cursor) iff
|
|
61
|
+
* `cursor >= chunk.lastObservedAt - 1ms`.
|
|
62
|
+
*/
|
|
63
|
+
declare function isBufferedChunkCoveredByCursor(chunkLastObservedAt: Date | string, cursor: Date | string | null | undefined): boolean;
|
|
64
|
+
/** The later of two cursors; `undefined` only when both are absent. */
|
|
65
|
+
declare function maxObservationCursor(a: Date | string | null | undefined, b: Date | string | null | undefined): Date | undefined;
|
|
66
|
+
interface ReflectionTextPlan {
|
|
67
|
+
/** `equal`: stored text equals the snapshot. `append`: observations were appended after the snapshot. */
|
|
68
|
+
mode: 'equal' | 'append';
|
|
69
|
+
observations: string;
|
|
70
|
+
tokenCount: number;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Decide the new generation's text when a reflection built from `snapshot` commits against
|
|
74
|
+
* the stored record.
|
|
75
|
+
*
|
|
76
|
+
* - Stored text equals the snapshot: the reflection replaces it.
|
|
77
|
+
* - Stored text extends the snapshot (activation only appends): the appended tail is kept
|
|
78
|
+
* after the reflection, and its tokens are added.
|
|
79
|
+
* - Anything else (a non-append rewrite): `null` — the reflection must not be applied.
|
|
80
|
+
*/
|
|
81
|
+
declare function planReflectionGenerationText(input: {
|
|
82
|
+
storedObservations: string;
|
|
83
|
+
storedObservationTokenCount: number;
|
|
84
|
+
snapshotObservations: string;
|
|
85
|
+
snapshotObservationTokenCount: number;
|
|
86
|
+
reflection: string;
|
|
87
|
+
tokenCount: number;
|
|
88
|
+
}): ReflectionTextPlan | null;
|
|
89
|
+
/**
|
|
90
|
+
* Backs `updateActiveObservations` in adapters that implement `commitActiveObservations`.
|
|
91
|
+
* Callers of `updateActiveObservations` (which resolves `void`) can't see a commit result, so a
|
|
92
|
+
* write that was not applied throws instead of resolving as if it had committed.
|
|
93
|
+
*/
|
|
94
|
+
declare function assertActiveObservationsApplied(result: UpdateActiveObservationsResult, id: string): void;
|
|
95
|
+
/**
|
|
96
|
+
* Whether the stored text can still accept a reflection built from `snapshot`
|
|
97
|
+
* (equal, or only appended to since).
|
|
98
|
+
*/
|
|
99
|
+
declare function isAppendOnlySince(storedObservations: string, snapshotObservations: string): boolean;
|
|
100
|
+
//#endregion
|
|
101
|
+
export { OBSERVATIONAL_MEMORY_LIFECYCLE_COLUMNS, ObservationalMemoryHeadOrderFields, ReflectionTextPlan, UpdateActiveObservationsResult, UpdateBufferedObservationsResult, assertActiveObservationsApplied, compareObservationalMemoryHeadOrder, isAppendOnlySince, isBufferedChunkCoveredByCursor, maxObservationCursor, planReflectionGenerationText, withObservationalMemoryLifecycleColumns };
|
|
102
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"type":"module"}
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-mongodb
|
|
|
3
3
|
description: Documentation for @mastra/mongodb. Use when working with @mastra/mongodb APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/mongodb"
|
|
6
|
-
version: "1.23.
|
|
6
|
+
version: "1.23.1-alpha.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -95,29 +95,32 @@ Set the `retention` field on the store config.
|
|
|
95
95
|
|
|
96
96
|
Each domain specifies its age-prunable tables and the timestamp column that anchors comparison, chosen so `maxAge` matches the meaning of the data. Append-only logs use creation time, live state uses last activity, and jobs or runs use completion time so in-flight work isn't pruned.
|
|
97
97
|
|
|
98
|
-
| Domain | Table key | Anchor column | `maxAge` measures
|
|
99
|
-
| ----------------- | ------------------ | ---------------- |
|
|
100
|
-
| `memory` | `threads` | `createdAt` | Thread age
|
|
101
|
-
| `memory` | `messages` | `createdAt` | Message age
|
|
102
|
-
| `memory` | `resources` | `createdAt` | Resource age
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `observability` | `
|
|
106
|
-
| `observability` | `
|
|
107
|
-
| `observability` | `
|
|
108
|
-
| `observability` | `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
98
|
+
| Domain | Table key | Anchor column | `maxAge` measures |
|
|
99
|
+
| ----------------- | ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
100
|
+
| `memory` | `threads` | `createdAt` | Thread age |
|
|
101
|
+
| `memory` | `messages` | `createdAt` | Message age |
|
|
102
|
+
| `memory` | `resources` | `createdAt` | Resource age |
|
|
103
|
+
| `memory` | `runFences` | `retiredAt` | Time since the durable agent execution holding the fence settled. Fences of running executions (`NULL`) are never pruned |
|
|
104
|
+
| `threadState` | `threadState` | `updatedAt` | Inactivity: state for still-active threads survives |
|
|
105
|
+
| `observability` | `spans` | `startedAt` | Span age |
|
|
106
|
+
| `observability` | `metrics` | `timestamp` | Metric event age (vNext only) |
|
|
107
|
+
| `observability` | `logs` | `timestamp` | Log event age (vNext only) |
|
|
108
|
+
| `observability` | `scores` | `timestamp` | Score event age (vNext only) |
|
|
109
|
+
| `observability` | `feedback` | `timestamp` | Feedback event age (vNext only) |
|
|
110
|
+
| `scores` | `scorers` | `createdAt` | Score record age |
|
|
111
|
+
| `workflows` | `workflowSnapshot` | `updatedAt` | Inactivity, suspended or long-running workflows survive |
|
|
112
|
+
| `workflows` | `runOwnership` | `updatedAt` | Inactivity. A running durable agent execution renews its claim every 10 seconds, so keep `maxAge` well above its 30-second lease |
|
|
113
|
+
| `backgroundTasks` | `backgroundTasks` | `completedAt` | Time since completion, in-flight tasks (`NULL`) are never pruned |
|
|
114
|
+
| `experiments` | `experiments` | `completedAt` | Time since completion, running experiments are never pruned |
|
|
115
|
+
| `notifications` | `notifications` | `createdAt` | Notification age |
|
|
116
|
+
| `harness` | `sessions` | `createdAt` | Session record age |
|
|
117
|
+
| `schedules` | `triggers` | `actual_fire_at` | Fire-history age (epoch-ms column) |
|
|
116
118
|
|
|
117
119
|
> **Note:**
|
|
118
120
|
>
|
|
119
121
|
> - The memory `observational_memory` table has no timestamp anchor, so it can't be age-pruned and isn't a valid retention key.
|
|
120
122
|
> - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
|
|
123
|
+
> - `runOwnership` and `runFences` hold the run fencing records of durable agents, one small record per run in each. If the `runOwnership` `maxAge` is too short, a running execution can lose its run, but an execution that lost a run still can't write. A fence is retired only when its execution settles, so the fence of a run that crashed and was never recovered is never pruned.
|
|
121
124
|
> - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
|
|
122
125
|
> - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
|
|
123
126
|
> - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.
|