darwin-agents 0.4.8 → 0.5.0-alpha.1

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/CHANGELOG.md CHANGED
@@ -1,5 +1,218 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.5.0-alpha.1] — 2026-05-24
4
+
5
+ **Phase 2 A1: Execution-Trace-Capture.** First pre-release of Darwin's
6
+ Phase 2 tech roadmap. Unblocks GEPA-style reflective optimizers (A2)
7
+ and validate-by-reproduce drift-detection (A5) by giving them a
8
+ structured trajectory to consume.
9
+
10
+ Industry-aligned with the 2026 agent-observability consensus (Braintrust,
11
+ Langfuse, Strands SDK, Microsoft Foundry, OTEL GenAI semantic conventions):
12
+ three span types — Tool / Reasoning / Turn-level errors — captured into a
13
+ single `ExecutionTrace` object, persisted as JSONB (Postgres) or TEXT
14
+ (SQLite), and tagged with a forward-compatible `version: 1` discriminator.
15
+
16
+ ### Added
17
+
18
+ - **`ExecutionTrace` schema** (`src/types.ts`) — versioned trajectory shape:
19
+ `toolCalls[]` (with OTEL-mappable `id` / `tool` / `args` / `resultSummary`
20
+ (2000-char cap) / `outcome` / `durationMs` / `retryCount?` / `errorClass?` /
21
+ `errorMessage?` / `turn`), `textBlockCount` (honest name — NOT a thinking-
22
+ block counter, V2 will add typed `reasoningBlocks`), `turnCount`,
23
+ `mcpInvocations`, `errors[]` (turn-level), `tokenUsage?` (OTEL `gen_ai.usage.*`
24
+ fields: input/output/cache_read/cache_creation tokens), `capturedAt`. Plus
25
+ optional `trajectory?: ExecutionTrace` on `DarwinExperiment` (additive —
26
+ pre-A1 callers unaffected).
27
+
28
+ - **`createTraceCapture()` factory** (`src/core/trace-capture.ts`) — pure,
29
+ transport-agnostic capturer. The runtime feeds tool events; the capturer
30
+ aggregates into a typed trajectory. API:
31
+
32
+ ```ts
33
+ const trace = createTraceCapture();
34
+ trace.startTurn();
35
+ trace.recordToolUse('toolu_01AB', 'mcp__nex__search', { query: 'x' });
36
+ trace.recordToolResult('toolu_01AB', 'success', { resultSummary: '3 hits' });
37
+ trace.recordTextBlock();
38
+ trace.addTokens({ inputTokens: 1200, outputTokens: 340 });
39
+ trace.recordError('parse_error', 'invalid JSON');
40
+ const trajectory = trace.finalize();
41
+ ```
42
+
43
+ Unpaired `recordToolUse` calls (no matching `recordToolResult` before
44
+ `finalize`) surface as `outcome: 'error', errorClass: 'unpaired_call'`
45
+ so silent SDK hangs remain visible in the trace. Customizable via
46
+ `TraceCaptureOptions`: `now?` (clock injection for tests),
47
+ `isMcpTool?` (predicate override for non-`mcp__`-prefixed servers).
48
+
49
+ - **`addTokens()` aggregator** — lossy-merge of per-turn LLM usage. Missing
50
+ fields (`NaN` / `Infinity` / `undefined`) skip silently rather than
51
+ defaulting to zero — preserves the distinction between "provider didn't
52
+ report" and "actually zero tokens".
53
+
54
+ - **JSONB persistence** in `darwin_experiments.trajectory` column +
55
+ `idx_darwin_exp_trajectory_gin` GIN index (Postgres) for `@>`
56
+ containment queries from A2 / A5 consumers. SQLite stores the same
57
+ shape as JSON-stringified TEXT.
58
+
59
+ - **`scripts/migrate-add-trajectory.ts`** — idempotent migration script.
60
+ Pre-checks column + index existence (filtered by `current_schema()`
61
+ for multi-schema-safe operation), runs `ALTER TABLE … ADD COLUMN IF
62
+ NOT EXISTS trajectory JSONB` + `CREATE INDEX IF NOT EXISTS`, then
63
+ verifies. Rollback path documented inline.
64
+
65
+ ```bash
66
+ DARWIN_POSTGRES_URL=postgresql://… npx tsx scripts/migrate-add-trajectory.ts
67
+ ```
68
+
69
+ - **Defensive parsing** in both memory backends — `parseTrajectory` /
70
+ `parseTrajectoryColumn` drop malformed values (wrong `version`,
71
+ non-object, invalid JSON) to `undefined` instead of crashing the
72
+ load. Future schema versions (`version !== 1`) are silently ignored
73
+ so v0.5 consumers don't break on v0.6 trajectories.
74
+
75
+ - **39 new tests** across two suites (all green):
76
+ - `tests/trace-capture.test.ts` (32 unit tests): basic flow,
77
+ defensive behaviour, truncation (2000-char `resultSummary`),
78
+ MCP-heuristic, schema invariants, tool_call_id passthrough,
79
+ `addTokens` aggregate semantics
80
+ - `tests/memory-trajectory.test.ts` (7 tests): SQLite roundtrip,
81
+ backward-compat with pre-A1 rows, defensive parsing, idempotent
82
+ migration, Postgres-gated JSONB roundtrip
83
+
84
+ ### Changed
85
+
86
+ - **DDL single-source-of-truth** — the trajectory column is defined
87
+ ONLY in the additive `ALTER TABLE … ADD COLUMN IF NOT EXISTS` path
88
+ (Postgres) / PRAGMA-guarded ALTER (SQLite), never inline in the
89
+ `CREATE TABLE`. Schema-evolution lives in one place; fresh installs
90
+ reach the same end-state as legacy installs.
91
+
92
+ - **Postgres `ON CONFLICT` preserves trajectory** on feedback-only
93
+ re-saves via `COALESCE(EXCLUDED.trajectory, darwin_experiments.trajectory)`.
94
+ This means a second `saveExperiment(exp)` call that omits trajectory
95
+ doesn't zero out the previously-stored trace.
96
+
97
+ **NOTE — SQLite asymmetry:** SQLite uses `INSERT OR REPLACE` which
98
+ drops + re-inserts the row, so callers wanting to preserve a prior
99
+ trajectory across re-saves MUST include it in the new payload. This
100
+ asymmetry is documented on `MemoryProvider.saveExperiment` in the
101
+ interface JSDoc.
102
+
103
+ ### Backwards compatibility
104
+
105
+ 100% backwards-compatible. The new `trajectory` field is optional, the
106
+ new column is nullable, the new methods on `MemoryProvider` are
107
+ additive. Existing v0.4.x consumers see no behavioural changes.
108
+
109
+ Verified on a live `darwin_db` with 341 experiments, 339 of which
110
+ pre-date A1 — all loaded cleanly with `trajectory: undefined`.
111
+
112
+ ### Why "alpha.1"
113
+
114
+ `textBlockCount` is honest but limited — V2 will replace it with a
115
+ typed `reasoningBlocks: ReasoningBlock[]` sequence carrying the actual
116
+ text content per reasoning step, which is what GEPA reflectors need
117
+ for per-decision blame attribution. Existing `textBlockCount` will stay
118
+ as a fast aggregate. The `alpha.1` tag signals the schema is subject to
119
+ this kind of additive evolution before `0.5.0` final.
120
+
121
+ Three known minor gaps (deferred to follow-up patches):
122
+
123
+ - Per-call cost attribution (token usage per tool invocation, not just
124
+ per-run aggregate)
125
+ - Trace-capture lazy-load flag stays permanent on transient import
126
+ failure (low impact: Darwin is either built or not)
127
+ - Token extraction in the SDK adapter is Anthropic-shaped (`message.usage`)
128
+ and may silently miss tokens for non-Anthropic providers — by design
129
+ (token usage is documented optional), but a debug-level log line in a
130
+ follow-up patch will make this easier to spot.
131
+
132
+ Install: `npm install darwin-agents@alpha`. The default `latest` tag
133
+ remains on `0.4.9` until `0.5.0` final ships.
134
+
135
+ ## [0.4.9] — 2026-05-22
136
+
137
+ Polish on top of v0.4.8. Adds spec-compliance, error classification,
138
+ per-call timeouts, and a Mem0 preset — all derived from a deep read of
139
+ the MCP TypeScript SDK + MCP spec 2025-11-25 + Mem0 MCP server source
140
+ (`mem0ai/mem0-mcp`).
141
+
142
+ ### Added
143
+
144
+ - **`McpBridgeError` / `McpBridgeProtocolError` / `McpBridgeTransportError`** —
145
+ exported error classes that discriminate JSON-RPC server errors
146
+ (`kind: 'protocol'`, numeric `code`) from local transport errors
147
+ (`kind: 'transport'`, stable string `code` ∈ `timeout` / `closed` /
148
+ `transient` / `child_exit` / `spawn_failed` / `http_status`). Callers
149
+ can `instanceof`-check to decide retry vs fail-loud without parsing
150
+ message text. Mirrors the `ProtocolError` vs `SdkError` split that
151
+ the MCP TypeScript SDK v2 uses internally; we keep our own classes to
152
+ preserve the zero-hard-deps policy.
153
+
154
+ - **Per-call `timeoutMs` override** on `save()` and `fetchRelevant()`.
155
+ Mirrors `client.callTool(..., { timeout })` from the MCP SDK. Useful
156
+ for one-off slow operations (large embedding searches) without
157
+ cranking the bridge-wide `requestTimeoutMs`.
158
+
159
+ ```ts
160
+ await memory.fetchRelevant({ query: 'X', limit: 5, timeoutMs: 30_000 });
161
+ await memory.save(record, { timeoutMs: 5_000 });
162
+ ```
163
+
164
+ - **`mem0Preset()`** — drop-in `Partial<McpMemoryConfig>` that wires
165
+ Darwin to the official `mem0ai/mem0-mcp` server with the right tool
166
+ names (`add_memory` + `search_memories` — NOT the `mem0_add` /
167
+ `mem0_search` guess from earlier docs) and arg shapes. Handles
168
+ user/agent/run scoping, default metadata, and the `memory` field in
169
+ result rows.
170
+
171
+ ```ts
172
+ const memory = remoteMemory('https://api.mem0.ai/mcp', {
173
+ authHeader: `Bearer ${process.env.MEM0_KEY}`,
174
+ ...mem0Preset({ userId: 'darwin-agent', defaultMetadata: { project: 'darwin' } }),
175
+ });
176
+ ```
177
+
178
+ ### Fixed
179
+
180
+ - **MCP-Protocol-Version HTTP header** is now sent on every HTTP request,
181
+ per MCP spec 2025-11-25 §"HTTP Protocol Versioning". Without it,
182
+ strict servers MAY respond `400 Bad Request`. Previously the bridge
183
+ only carried the version inside the `initialize` payload, which left
184
+ every subsequent `tools/call` un-versioned at the transport layer.
185
+ The version defaults to `2025-11-25` and is honored when overridden
186
+ via `protocolVersion` in the bridge config.
187
+
188
+ - Internal raw `Error` throws in `rpcStdio` / `rpcHttp` / `onChildExit`
189
+ / `ensureReady` / `close()` are now wrapped in the typed bridge error
190
+ classes above. Existing message-substring regex tests still pass.
191
+
192
+ ### Changed
193
+
194
+ - `McpMemoryBridge.save(record, opts?)` accepts an optional second
195
+ argument with `{ timeoutMs }`. This is a structural super-type of
196
+ `FeedbackStore.save(record)` — callers using the base interface keep
197
+ working unchanged; the typed Darwin path now gets the extra knob.
198
+
199
+ ### Tests
200
+
201
+ 225/225 pass (was 211, +14). New coverage:
202
+ - HTTP header presence on initialize + tools/call (2 tests).
203
+ - Error-class discrimination — protocol vs http-status vs closed-bridge (3 tests).
204
+ - Per-call timeout precedence over bridge-level timeout, on both stdio
205
+ and http transports (2 tests).
206
+ - `mem0Preset()` — tool names, write-arg shape, scope alternatives,
207
+ read-result parsing (Mem0 `memory` field), structuredContent
208
+ shortcut, unknown-shape tolerance, end-to-end spread integration with
209
+ a mock Mem0 server (7 tests).
210
+
211
+ ### Recommendation
212
+
213
+ Upgrade from v0.4.8 to v0.4.9 (`npm install darwin-agents@latest`). No
214
+ breaking changes to existing callers — all additions are opt-in.
215
+
3
216
  ## [0.4.8] — 2026-05-22
4
217
 
5
218
  Hotfix on top of v0.4.7. Path resolution in the `exports` map pointed at
package/README.md CHANGED
@@ -161,12 +161,11 @@ const memory = localMemory();
161
161
  // Or any remote MCP-Memory server
162
162
  // const memory = remoteMemory('https://your-mcp.example.com/mcp', { authHeader: `Bearer ${KEY}` });
163
163
 
164
- // Or Mem0 with tool-name + arg aliasing
164
+ // Or Mem0 with the built-in preset — handles tool names + arg shape for you
165
+ // import { mem0Preset } from 'darwin-agents/memory/bridge';
165
166
  // const memory = remoteMemory('https://api.mem0.ai/mcp', {
166
167
  // authHeader: `Bearer ${process.env.MEM0_KEY}`,
167
- // writeTool: 'mem0_add',
168
- // readTool: 'mem0_search',
169
- // mapWriteArgs: (rec) => ({ messages: [{ role: 'user', content: rec.content }], metadata: { tags: rec.tags } }),
168
+ // ...mem0Preset({ userId: 'darwin-agent', defaultMetadata: { project: 'darwin' } }),
170
169
  // });
171
170
 
172
171
  const result = await runClosedLoopTurn(
@@ -182,7 +181,7 @@ const result = await runClosedLoopTurn(
182
181
  |---|---|---|---|
183
182
  | **`@studiomeyer/local-memory-mcp`** (default) | `memory_learn` | `memory_search` | zero-config, single SQLite file, no cloud |
184
183
  | Any self-hosted MCP-Memory server | `memory_learn` | `memory_search` | same wire, remote endpoint |
185
- | Mem0 MCP | `mem0_add` | `mem0_search` | needs `mapWriteArgs` for the `messages` shape |
184
+ | **Mem0 MCP** (`mem0ai/mem0-mcp`) | `add_memory` | `search_memories` | use `...mem0Preset({ userId })` handles tool names + arg shape + the `memory` field in result rows |
186
185
  | Zep MCP | `zep_add` | `zep_search` | optional `mapWriteArgs` for `group_id` |
187
186
  | Letta MCP | `archival_insert` | `archival_search` | optional `mapReadResult` for their envelope |
188
187
  | Cognee MCP | `cognee_add` | `cognee_search` | optional mappers |
@@ -192,6 +191,50 @@ and arg shapes vary. One bridge, one reconnect path, one timeout policy.
192
191
  The pattern matches the [MCP Bridge proxy paper (arXiv 2504.08999)](https://arxiv.org/html/2504.08999v2)
193
192
  but stays inside the Darwin process — no extra service to deploy.
194
193
 
194
+ ### v0.4.9 polish (2026-05-22)
195
+
196
+ - **Spec-compliant transport.** Every HTTP request now carries the
197
+ `MCP-Protocol-Version: 2025-11-25` header, per MCP spec 2025-11-25
198
+ §"HTTP Protocol Versioning". Strict servers MAY return `400` without
199
+ it; pre-v0.4.9 only sent the version inside the `initialize` payload.
200
+
201
+ - **Typed errors.** Bridge errors are now instances of
202
+ `McpBridgeProtocolError` (JSON-RPC errors from the server, numeric
203
+ `code`) or `McpBridgeTransportError` (local timeouts, EPIPE, network
204
+ resets, child exits — stable string `code`). Branch on `instanceof`
205
+ to decide retry vs fail-loud without parsing message text.
206
+
207
+ ```typescript
208
+ import {
209
+ McpBridgeProtocolError,
210
+ McpBridgeTransportError,
211
+ } from 'darwin-agents/memory/bridge';
212
+
213
+ try {
214
+ await memory.save(record);
215
+ } catch (err) {
216
+ if (err instanceof McpBridgeTransportError && err.code === 'timeout') {
217
+ // local timeout — safe to retry
218
+ } else if (err instanceof McpBridgeProtocolError && err.code === -32602) {
219
+ // server said our args are invalid — fail loud, don't retry
220
+ }
221
+ }
222
+ ```
223
+
224
+ - **Per-call timeouts.** `save()` and `fetchRelevant()` accept a
225
+ `timeoutMs` override that beats the bridge-level default, mirroring
226
+ the MCP SDK's `client.callTool(..., { timeout })`. Useful for one-off
227
+ slow embedding searches without raising `requestTimeoutMs` globally.
228
+
229
+ ```typescript
230
+ await memory.fetchRelevant({ query: 'audit', limit: 5, timeoutMs: 30_000 });
231
+ await memory.save(record, { timeoutMs: 5_000 });
232
+ ```
233
+
234
+ - **Mem0 preset.** `...mem0Preset({ userId })` wires the right tool
235
+ names (`add_memory` + `search_memories`) and arg shapes for the
236
+ official `mem0ai/mem0-mcp` server. See the example above.
237
+
195
238
  See [`examples/memory-darwin-integration.ts`](examples/memory-darwin-integration.ts)
196
239
  for the full closed-loop pattern: fetch relevant lessons → render them as
197
240
  prompt context → run the agent → persist critic findings → next run sees
@@ -40,6 +40,20 @@ export interface FetchRelevantOptions {
40
40
  limit?: number;
41
41
  /** Optional tag filter — passed through to the read tool if it honours it. */
42
42
  tags?: string[];
43
+ /**
44
+ * Per-call timeout override in ms. Falls back to `requestTimeoutMs` from
45
+ * the bridge config (default 10 000 ms). Useful for slow embedding-backed
46
+ * stores or when a particular query is known to be expensive.
47
+ */
48
+ timeoutMs?: number;
49
+ }
50
+ /** Options bag for `save()`. Mirrors the per-call timeout knob on read. */
51
+ export interface SaveOptions {
52
+ /**
53
+ * Per-call timeout override in ms. Falls back to `requestTimeoutMs` from
54
+ * the bridge config (default 10 000 ms).
55
+ */
56
+ timeoutMs?: number;
43
57
  }
44
58
  /** Darwin-side store contract extended with retrieval + lifecycle. */
45
59
  export interface RetrievableFeedbackStore extends FeedbackStore {
@@ -87,6 +101,52 @@ export interface McpMemoryConfig {
87
101
  debug?: (msg: string) => void;
88
102
  };
89
103
  }
104
+ /**
105
+ * Base class for bridge errors. Discriminates protocol-level (server-side
106
+ * JSON-RPC error responses) from transport-level (local timeouts, network
107
+ * resets, EPIPE, child process exits). Callers can branch on `kind` to
108
+ * decide retry-vs-fail-loud without parsing the message text.
109
+ *
110
+ * Mirrors the split MCP TypeScript SDK v2 uses internally (`ProtocolError`
111
+ * vs `SdkError`). We keep our own classes to preserve the bridge's
112
+ * zero-hard-dep policy.
113
+ */
114
+ export declare class McpBridgeError extends Error {
115
+ /** 'protocol' = JSON-RPC error from the server, 'transport' = local. */
116
+ readonly kind: 'protocol' | 'transport';
117
+ /** JSON-RPC error code for protocol errors, or a stable string for transport errors. */
118
+ readonly code: number | string;
119
+ /** Which transport produced the error. */
120
+ readonly transport: 'stdio' | 'http';
121
+ constructor(opts: {
122
+ message: string;
123
+ kind: 'protocol' | 'transport';
124
+ code: number | string;
125
+ transport: 'stdio' | 'http';
126
+ cause?: unknown;
127
+ });
128
+ }
129
+ /** JSON-RPC error from the server. `code` is the numeric JSON-RPC code. */
130
+ export declare class McpBridgeProtocolError extends McpBridgeError {
131
+ constructor(opts: {
132
+ code: number;
133
+ serverMessage: string;
134
+ transport: 'stdio' | 'http';
135
+ });
136
+ }
137
+ /**
138
+ * Local transport-layer error (timeout, EPIPE, network reset, child exit,
139
+ * abort, DNS). `code` is a short stable string for branching:
140
+ * 'timeout' | 'closed' | 'transient' | 'child_exit' | 'spawn_failed' | 'http_status'
141
+ */
142
+ export declare class McpBridgeTransportError extends McpBridgeError {
143
+ constructor(opts: {
144
+ message: string;
145
+ code: 'timeout' | 'closed' | 'transient' | 'child_exit' | 'spawn_failed' | 'http_status';
146
+ transport: 'stdio' | 'http';
147
+ cause?: unknown;
148
+ });
149
+ }
90
150
  /** Default mapping for `memory_learn` shape (local-memory-mcp, mcp-nex). */
91
151
  export declare function defaultMapWriteArgs(rec: FeedbackRecord): Record<string, unknown>;
92
152
  /**
@@ -120,7 +180,13 @@ export declare class McpMemoryBridge implements RetrievableFeedbackStore {
120
180
  private initInFlight;
121
181
  private closed;
122
182
  constructor(config: McpMemoryConfig);
123
- save(record: FeedbackRecord): Promise<void>;
183
+ /**
184
+ * Persist a feedback record. Accepts an optional second arg for per-call
185
+ * overrides (currently `timeoutMs`). The signature stays a structural
186
+ * super-type of `FeedbackStore.save(record)`, so callers using the base
187
+ * interface keep working unchanged.
188
+ */
189
+ save(record: FeedbackRecord, opts?: SaveOptions): Promise<void>;
124
190
  fetchRelevant(queryOrOpts: string | FetchRelevantOptions, legacyLimit?: number): Promise<Lesson[]>;
125
191
  close(): Promise<void>;
126
192
  private ensureReady;
@@ -136,14 +202,24 @@ export declare class McpMemoryBridge implements RetrievableFeedbackStore {
136
202
  * F1: no inline respawn — ensureReady/initialize is the only path that
137
203
  * spawns. This avoids the double-spawn race where rpc() and ensureReady()
138
204
  * both spawn children competing for `this.child`.
205
+ *
206
+ * `timeoutMs` overrides the bridge-level `requestTimeoutMs` for this call.
139
207
  */
140
208
  private rpc;
141
209
  private rpcStdio;
142
210
  /**
143
211
  * HTTP transport with bounded retries on 5xx + transient network errors.
144
212
  * Per-attempt timeout via AbortController. Honors `httpMaxRetries`.
213
+ *
214
+ * Sends the `MCP-Protocol-Version` HTTP header per MCP spec 2025-11-25
215
+ * §"HTTP Protocol Versioning". Strict servers MAY return 400 if it is
216
+ * missing or unsupported.
145
217
  */
146
218
  private rpcHttp;
219
+ /**
220
+ * Invoke a tool. Accepts a per-call `opts.timeoutMs` override that takes
221
+ * precedence over the bridge-level `requestTimeoutMs` config.
222
+ */
147
223
  private callTool;
148
224
  }
149
225
  /**
@@ -171,13 +247,50 @@ export declare function localMemory(overrides?: Partial<McpMemoryConfig>): McpMe
171
247
  * Example: connect to your hosted memory.studiomeyer.io endpoint
172
248
  * remoteMemory('https://memory.studiomeyer.io/mcp', { authHeader: `Bearer ${KEY}` })
173
249
  *
174
- * Example: Mem0 with tool-name + arg aliasing
175
- * remoteMemory('https://api.mem0.ai/mcp', {
176
- * authHeader: `Bearer ${process.env.MEM0_KEY}`,
177
- * writeTool: 'mem0_add',
178
- * readTool: 'mem0_search',
179
- * mapWriteArgs: (rec) => ({ content: rec.content, metadata: { tags: rec.tags } }),
180
- * })
250
+ * Example: Mem0 with tool-name + arg aliasing — see `mem0Preset()` below
251
+ * for a one-line spread that handles all of this for you.
181
252
  */
182
253
  export declare function remoteMemory(url: string, overrides?: Partial<McpMemoryConfig>): McpMemoryBridge;
254
+ /**
255
+ * Mem0 MCP server preset — drop-in overrides that match the exact tool
256
+ * names + arg shapes the `mem0ai/mem0-mcp` server expects.
257
+ *
258
+ * Reference: github.com/mem0ai/mem0-mcp — tools are `add_memory` (NOT
259
+ * `mem0_add` or `add_memories`) and `search_memories` (NOT `search_memory`).
260
+ * Add-args require one of `text`/`messages` + at least one of
261
+ * `user_id`/`agent_id`/`run_id`. Search-result rows expose the lesson
262
+ * text under `memory` (not `content`/`body`/`text`).
263
+ *
264
+ * Usage with the hosted Mem0 platform:
265
+ * \`\`\`ts
266
+ * const memory = remoteMemory('https://api.mem0.ai/mcp', {
267
+ * authHeader: `Bearer ${process.env.MEM0_KEY}`,
268
+ * ...mem0Preset({ userId: 'darwin-agent' }),
269
+ * });
270
+ * \`\`\`
271
+ *
272
+ * Usage with a locally spawned mem0-mcp server (stdio):
273
+ * \`\`\`ts
274
+ * const memory = new McpMemoryBridge({
275
+ * transport: 'stdio',
276
+ * endpoint: ['uvx', 'mem0-mcp'],
277
+ * ...mem0Preset({ userId: 'darwin-agent' }),
278
+ * });
279
+ * \`\`\`
280
+ *
281
+ * Spread order matters: put `...mem0Preset(...)` AFTER other overrides if
282
+ * you want the preset to win, or BEFORE if you want to override the
283
+ * preset's defaults yourself.
284
+ */
285
+ export declare function mem0Preset(opts?: {
286
+ /**
287
+ * Mem0 scope identifier. Required because `add_memory` rejects writes
288
+ * without at least one of user_id / agent_id / run_id.
289
+ */
290
+ userId?: string;
291
+ agentId?: string;
292
+ runId?: string;
293
+ /** Extra metadata merged into every write under the `metadata` key. */
294
+ defaultMetadata?: Record<string, unknown>;
295
+ }): Partial<McpMemoryConfig>;
183
296
  //# sourceMappingURL=mcp-memory-bridge.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"mcp-memory-bridge.d.ts","sourceRoot":"","sources":["../../examples/mcp-memory-bridge.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"mcp-memory-bridge.d.ts","sourceRoot":"","sources":["../../examples/mcp-memory-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAI/E,0FAA0F;AAC1F,MAAM,WAAW,MAAM;IACrB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sEAAsE;AACtE,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC7D;;;;OAIG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChE,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,MAAM,EAAE,CAAC;IAClD,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CACzE;AAaD;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC;IACxC,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;gBACzB,IAAI,EAAE;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC;QAC/B,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QACtB,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;QAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAQF;AAED,2EAA2E;AAC3E,qBAAa,sBAAuB,SAAQ,cAAc;gBAC5C,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAAA;KAAE;CASvF;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,cAAc;gBAC7C,IAAI,EAAE;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,aAAa,CAAC;QACzF,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;QAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CAUF;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAShF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,EAAE,CAmC3D;AA6BD;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,wBAAwB;IAC9D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGrB;IACF,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,eAAe;IAqBnC;;;;;OAKG;IACG,IAAI,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnE,aAAa,CACjB,WAAW,EAAE,MAAM,GAAG,oBAAoB,EAC1C,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC;IAcd,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YA2Bd,WAAW;YA6BX,UAAU;IAwBxB,OAAO,CAAC,UAAU;IA8BlB,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,kBAAkB;IA8B1B,OAAO,CAAC,SAAS;IAWjB;;;;;;;;OAQG;YACW,GAAG;IAWjB,OAAO,CAAC,QAAQ;IAqChB;;;;;;;OAOG;YACW,OAAO;IAoIrB;;;OAGG;YACW,QAAQ;CAQvB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAmBrH;AAaD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAMrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GAAG,eAAe,CAMnG;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,GAAG,OAAO,CAAC,eAAe,CAAC,CA6DhC"}