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 +213 -0
- package/README.md +48 -5
- package/dist/examples/mcp-memory-bridge.d.ts +121 -8
- package/dist/examples/mcp-memory-bridge.d.ts.map +1 -1
- package/dist/examples/mcp-memory-bridge.js +297 -35
- package/dist/examples/mcp-memory-bridge.js.map +1 -1
- package/dist/src/core/trace-capture.d.ts +107 -0
- package/dist/src/core/trace-capture.d.ts.map +1 -0
- package/dist/src/core/trace-capture.js +183 -0
- package/dist/src/core/trace-capture.js.map +1 -0
- package/dist/src/index.d.ts +3 -1
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +1 -0
- package/dist/src/index.js.map +1 -1
- package/dist/src/memory/postgres-memory.d.ts.map +1 -1
- package/dist/src/memory/postgres-memory.js +38 -3
- package/dist/src/memory/postgres-memory.js.map +1 -1
- package/dist/src/memory/sqlite-memory.d.ts.map +1 -1
- package/dist/src/memory/sqlite-memory.js +47 -2
- package/dist/src/memory/sqlite-memory.js.map +1 -1
- package/dist/src/types.d.ts +136 -0
- package/dist/src/types.d.ts.map +1 -1
- package/dist/src/types.js.map +1 -1
- package/package.json +1 -1
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
|
|
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
|
-
//
|
|
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 | `
|
|
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
|
-
|
|
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
|
-
*
|
|
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":"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;
|
|
1
|
+
{"version":3,"file":"mcp-memory-bridge.d.ts","sourceRoot":"","sources":["../../examples/mcp-memory-bridge.ts"],"names":[],"mappings":"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"}
|