@sym-bot/sym 0.1.0 → 0.2.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/PRD.md +1 -1
- package/README.md +237 -70
- package/TECHNICAL-SPEC.md +250 -197
- package/bin/setup-claude.sh +31 -1
- package/bin/sym-daemon.js +437 -0
- package/docs/mesh-memory-protocol.md +563 -0
- package/docs/mmp-architecture-image-prompt.txt +12 -0
- package/docs/p2p-protocol-research.md +907 -0
- package/docs/protocol-wake.md +242 -0
- package/integrations/claude-code/mcp-server.js +264 -41
- package/integrations/telegram/bot.js +418 -0
- package/lib/ipc-client.js +241 -0
- package/lib/node.js +489 -39
- package/lib/transport.js +88 -0
- package/package.json +5 -3
- package/sym-relay/Dockerfile +7 -0
- package/sym-relay/lib/logger.js +28 -0
- package/sym-relay/lib/relay.js +388 -0
- package/sym-relay/package-lock.json +40 -0
- package/sym-relay/package.json +18 -0
- package/sym-relay/render.yaml +14 -0
- package/sym-relay/server.js +67 -0
- package/.mcp.json +0 -12
|
@@ -0,0 +1,563 @@
|
|
|
1
|
+
# Mesh Memory Protocol (MMP)
|
|
2
|
+
|
|
3
|
+
**Version:** 0.2.0
|
|
4
|
+
**Status:** Draft
|
|
5
|
+
**Research:** [P2P Protocol Research](p2p-protocol-research.md) · [Mesh Cognition Whitepaper](https://sym.bot/research/mesh-cognition)
|
|
6
|
+
**Reference Implementation:** [SYM](https://github.com/sym-bot/sym)
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Philosophical Foundation
|
|
11
|
+
|
|
12
|
+
MMP's layer ordering follows the structure of cognition itself, derived from first principles across philosophy of mind, information theory, and dynamical systems.
|
|
13
|
+
|
|
14
|
+
### The Central Claim
|
|
15
|
+
|
|
16
|
+
**Cognition emerges from memory. Memory is the substrate; cognition is the process that arises from it.**
|
|
17
|
+
|
|
18
|
+
- **Aristotle's Metaphysics:** Actuality (ἐνέργεια) presupposes potentiality (δύναμις). You cannot actualise what has not been stored.
|
|
19
|
+
- **Predictive Processing (Friston):** Without stored generative models, there is no baseline for prediction, and therefore no cognition. Cognition is the minimisation of surprise relative to a generative model.
|
|
20
|
+
- **Information Theory (Shannon):** You cannot compress what has not been stored. Memory is the signal; cognition is the compression.
|
|
21
|
+
- **Autopoiesis (Maturana):** Cognition is the history of structural coupling. Without accumulated coupling history (memory), there is no cognition.
|
|
22
|
+
|
|
23
|
+
### The Qualification: Bidirectionality
|
|
24
|
+
|
|
25
|
+
Buddhist dependent origination (pratītyasamutpāda) shows the relationship is cyclical, not linear. The Yogācāra school's ālaya-vijñāna both stores experiential seeds AND generates conscious moments. MMP models this as a **feedback loop**: memory feeds cognition, cognition governs memory sharing, shared memories update stores, which update cognitive state.
|
|
26
|
+
|
|
27
|
+
### Three Design Principles
|
|
28
|
+
|
|
29
|
+
**1. Withdrawal (Harman, Object-Oriented Ontology)**
|
|
30
|
+
An agent can never be fully known by its peers. Partial knowledge is an ontological condition. The coupling engine selects which aspects to surface — full transparency is neither possible nor desirable.
|
|
31
|
+
|
|
32
|
+
**2. Resonance over Decision (Laozi, Wu Wei)**
|
|
33
|
+
The coupling engine detects natural affinities rather than computing rigid rules. The protocol creates conditions for the right information to flow to the right agent, through resonance rather than prescription.
|
|
34
|
+
|
|
35
|
+
**3. Extended Cognition (Clark & Chalmers)**
|
|
36
|
+
When shared memories are reliably available, directly accessible, and automatically endorsed, the mesh becomes a genuinely extended cognitive system.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Architecture
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
┌─────────────────────────────────────────────────┐
|
|
44
|
+
│ Layer 5 APPLICATION │
|
|
45
|
+
│ Domain-specific behaviour (music, code, etc.) │
|
|
46
|
+
├─────────────────────────────────────────────────┤
|
|
47
|
+
│ Layer 4 COGNITION │
|
|
48
|
+
│ Coupling engine · Drift · Coherence │
|
|
49
|
+
│ ▲ evaluates ─── ▼ governs │
|
|
50
|
+
├─────────────────────────────────────────────────┤
|
|
51
|
+
│ Layer 3 MEMORY │
|
|
52
|
+
│ L0 events · L1 structured · L2 cognitive state │
|
|
53
|
+
├─────────────────────────────────────────────────┤
|
|
54
|
+
│ Layer 2 CONNECTION │
|
|
55
|
+
│ Handshake · State-Sync · Peer-Info · Wake │
|
|
56
|
+
├─────────────────────────────────────────────────┤
|
|
57
|
+
│ Layer 1 TRANSPORT │
|
|
58
|
+
│ TCP (local) · Relay/WS (internet) · Push (wake) │
|
|
59
|
+
│ IPC (physical ↔ virtual) │
|
|
60
|
+
├─────────────────────────────────────────────────┤
|
|
61
|
+
│ Layer 0 IDENTITY │
|
|
62
|
+
│ nodeId · name · [future: keypair] │
|
|
63
|
+
└─────────────────────────────────────────────────┘
|
|
64
|
+
|
|
65
|
+
Feedback: Layer 4 ←→ Layer 3 (cognition reads from and writes back to memory)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Node Model
|
|
71
|
+
|
|
72
|
+
### The Mesh Has No Servers — Only Nodes
|
|
73
|
+
|
|
74
|
+
Every participant in the mesh is a node. Some nodes are always-on. Some sleep. Some are ephemeral. The protocol treats them all the same. There is no architectural distinction between a "server" and a "client" — only between nodes with different availability characteristics.
|
|
75
|
+
|
|
76
|
+
A relay is a node. A phone is a node. A speaker is a node. A Claude Code session is a node.
|
|
77
|
+
|
|
78
|
+
### Physical and Virtual Nodes
|
|
79
|
+
|
|
80
|
+
A **physical node** is a device-level mesh presence — persistent identity, maintains transport connections, stores state. It is the device's presence on the mesh.
|
|
81
|
+
|
|
82
|
+
A **virtual node** is an application-level agent — ephemeral, connects to a physical node via local IPC, registers a cognitive profile. It comes and goes without disrupting the mesh.
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
MacBook (physical node: sym-daemon)
|
|
86
|
+
├── Claude Code (virtual node, ephemeral)
|
|
87
|
+
├── MeloTune Mac (virtual node, ephemeral)
|
|
88
|
+
└── Any MCP client (virtual node, ephemeral)
|
|
89
|
+
|
|
90
|
+
iPhone (physical node: app process)
|
|
91
|
+
├── SymMeshService (virtual, internal)
|
|
92
|
+
└── MMPService (virtual, internal)
|
|
93
|
+
|
|
94
|
+
Cloud Server (physical node: relay process)
|
|
95
|
+
└── Telegram bot (virtual, co-hosted)
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
The protocol does not distinguish physical from virtual — this is an implementation concern. A virtual node communicates through its physical node's transport connections. The physical node handles relay, discovery, wake, and peer state. Virtual nodes handle cognition and application logic.
|
|
99
|
+
|
|
100
|
+
**On macOS/Linux:** The physical node is a daemon (launchd LaunchAgent / systemd service) that runs independently of any application. Apps connect via local IPC.
|
|
101
|
+
|
|
102
|
+
**On iOS:** The app IS the physical node. iOS does not permit background daemons. The app maximises persistence through layered background modes (audio, BLE, Network Extension, silent push). Ideally, MMP would be an OS-level service — but until platforms adopt it, the app must simulate this.
|
|
103
|
+
|
|
104
|
+
**On always-on devices** (relay servers, speakers, robots): The physical node is the main process. No separation needed.
|
|
105
|
+
|
|
106
|
+
### Local IPC
|
|
107
|
+
|
|
108
|
+
Virtual nodes connect to their physical node via local IPC:
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
macOS/Linux: Unix socket (/tmp/sym.sock)
|
|
112
|
+
iOS: In-process (shared memory — virtual nodes are internal services)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The IPC protocol carries the same MMP frames as any transport. A virtual node registers with:
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"type": "register",
|
|
120
|
+
"name": "claude-code",
|
|
121
|
+
"cognitiveProfile": "Coding assistant that understands bugs, APIs, debugging"
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
The physical node multiplexes all virtual nodes' frames over its transport connections. Peers see one node (the physical node), not individual virtual nodes. Routing to the correct virtual node happens locally based on cognitive profile matching.
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## Layer 0: Identity
|
|
130
|
+
|
|
131
|
+
Every MMP node has a persistent identity.
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
{
|
|
135
|
+
nodeId: string // unique, stable across restarts
|
|
136
|
+
name: string // human-readable label
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Identity is Aristotelian substance — the irreducible core that persists through change. Without a stable "who," there is no "what" to know or share.
|
|
141
|
+
|
|
142
|
+
**Current:** Random hex string, persisted to disk.
|
|
143
|
+
**Future:** Cryptographic keypair identity (Nostr model). `nodeId` derived from public key. Frames signed, enabling verification without trust.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Layer 1: Transport
|
|
148
|
+
|
|
149
|
+
MMP is transport-agnostic. Four transport types, all carrying the same frame format:
|
|
150
|
+
|
|
151
|
+
| Transport | Reach | Latency | Availability | Use Case |
|
|
152
|
+
|-----------|-------|---------|-------------|----------|
|
|
153
|
+
| **IPC** | Same device | <1ms | Always | Physical ↔ virtual nodes |
|
|
154
|
+
| **TCP** | Local network | ~1ms | While connected | Same-network peers |
|
|
155
|
+
| **Relay (WebSocket)** | Internet | ~100ms | While connected | Cross-network peers |
|
|
156
|
+
| **Wake (APNs/FCM)** | Internet | ~1-5s | Always (OS-managed) | Sleeping nodes |
|
|
157
|
+
|
|
158
|
+
### 1.1 Local IPC
|
|
159
|
+
|
|
160
|
+
Physical node exposes a Unix socket. Virtual nodes connect, register, and exchange frames. The physical node handles all external transport on behalf of its virtual nodes.
|
|
161
|
+
|
|
162
|
+
### 1.2 Local Network: TCP
|
|
163
|
+
|
|
164
|
+
Direct peer connection via Bonjour/mDNS discovery (service type `_sym._tcp`).
|
|
165
|
+
|
|
166
|
+
**Framing:** Length-prefixed JSON: `[4-byte BE uint32 length][JSON payload]`
|
|
167
|
+
|
|
168
|
+
### 1.3 Internet: Relay
|
|
169
|
+
|
|
170
|
+
WebSocket relay for cross-network connectivity. **The relay is a peer node** — it has its own identity, participates in handshakes, and gossips peer information. The relay is "dumb" in that it does not evaluate coupling or inspect frame payloads — but it is a full mesh participant, not external infrastructure.
|
|
171
|
+
|
|
172
|
+
**Relay protocol:**
|
|
173
|
+
|
|
174
|
+
```
|
|
175
|
+
Node → Relay: { type: "relay-auth", nodeId, name, token? }
|
|
176
|
+
Relay → Node: { type: "relay-peers", peers: [{ nodeId, name, wakeChannel? }] }
|
|
177
|
+
Relay → Others: { type: "relay-peer-joined", nodeId, name }
|
|
178
|
+
Node → Relay: { to?: nodeId, payload: <MMP frame> }
|
|
179
|
+
Relay → Node: { from: nodeId, fromName: name, payload: <MMP frame> }
|
|
180
|
+
Relay → Others: { type: "relay-peer-left", nodeId, name }
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
**Heartbeat:** Relay sends `relay-ping`, node responds `relay-pong`. No response within timeout → connection closed.
|
|
184
|
+
|
|
185
|
+
**Reconnection:** Exponential backoff with jitter, capped at 30s. Reset after stable connection (>30s).
|
|
186
|
+
|
|
187
|
+
**Authentication:** Optional pre-shared token. Invalid → `relay-error` + close.
|
|
188
|
+
|
|
189
|
+
### 1.4 Wake: Push
|
|
190
|
+
|
|
191
|
+
Out-of-band signal to wake sleeping nodes via platform push infrastructure (APNs, FCM).
|
|
192
|
+
|
|
193
|
+
**Wake is P2P.** The sending peer sends the push directly using wake channel credentials learned via peer gossip. Any node that knows a peer's wake channel can wake that peer — no relay involvement in the push itself.
|
|
194
|
+
|
|
195
|
+
**Wake decision is autonomous** — governed by coupling state, signal type, and cooldown. Not every signal warrants waking a sleeping node.
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Layer 2: Framing and Connection
|
|
200
|
+
|
|
201
|
+
All MMP communication uses **frames** — JSON objects with a `type` field. Frames are transport-agnostic.
|
|
202
|
+
|
|
203
|
+
### Frame Types
|
|
204
|
+
|
|
205
|
+
| Type | Direction | Coupling-gated | Purpose |
|
|
206
|
+
|------|-----------|---------------|---------|
|
|
207
|
+
| `handshake` | Bidirectional | No | Identity exchange |
|
|
208
|
+
| `state-sync` | Bidirectional | No | Cognitive state exchange |
|
|
209
|
+
| `peer-info` | Bidirectional | No | Gossip peer metadata (wake channels, capabilities) |
|
|
210
|
+
| `memory-share` | Sender → Peer | **Yes** | Share a memory entry |
|
|
211
|
+
| `mood` | Broadcast | **Evaluated** | Emotional/energy state signal |
|
|
212
|
+
| `message` | Broadcast or targeted | No | Direct communication |
|
|
213
|
+
| `wake` | Out-of-band (push) | Autonomous | Wake a sleeping node |
|
|
214
|
+
| `ping` / `pong` | Bidirectional | No | Liveness check |
|
|
215
|
+
|
|
216
|
+
### Frame Definitions
|
|
217
|
+
|
|
218
|
+
**handshake** — exchanged immediately on connection.
|
|
219
|
+
|
|
220
|
+
```json
|
|
221
|
+
{ "type": "handshake", "nodeId": "a1b2c3d4", "name": "melotune" }
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
**state-sync** — cognitive state for coupling evaluation.
|
|
225
|
+
|
|
226
|
+
```json
|
|
227
|
+
{
|
|
228
|
+
"type": "state-sync",
|
|
229
|
+
"h1": [0.1, -0.3, ...],
|
|
230
|
+
"h2": [0.5, 0.2, ...],
|
|
231
|
+
"confidence": 0.8
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Vectors MUST have consistent dimension across all nodes (default: d = 64).
|
|
236
|
+
|
|
237
|
+
**peer-info** — gossip peer metadata (SWIM-style piggyback). Sent during handshake and periodically. Each node shares what it knows about other peers.
|
|
238
|
+
|
|
239
|
+
```json
|
|
240
|
+
{
|
|
241
|
+
"type": "peer-info",
|
|
242
|
+
"peers": [
|
|
243
|
+
{
|
|
244
|
+
"nodeId": "f64c3719",
|
|
245
|
+
"name": "melotune",
|
|
246
|
+
"wakeChannel": { "platform": "apns", "token": "...", "environment": "sandbox" },
|
|
247
|
+
"lastSeen": 1711100000000
|
|
248
|
+
}
|
|
249
|
+
]
|
|
250
|
+
}
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Nodes MUST merge incoming `peer-info` with their local peer knowledge. Wake channels learned via gossip are retained even after the originating peer disconnects. Entries expire after a configurable TTL (default: 7 days).
|
|
254
|
+
|
|
255
|
+
**memory-share** — a knowledge entry shared with coupled peers.
|
|
256
|
+
|
|
257
|
+
```json
|
|
258
|
+
{
|
|
259
|
+
"type": "memory-share",
|
|
260
|
+
"key": "mem_a1b2c3",
|
|
261
|
+
"content": "User prefers acoustic guitar in the morning",
|
|
262
|
+
"source": "melotune",
|
|
263
|
+
"tags": ["preference", "morning"],
|
|
264
|
+
"timestamp": 1711100000000
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
MUST NOT send to peers where κ = rejected.
|
|
269
|
+
|
|
270
|
+
**mood** — emotional/energy state broadcast.
|
|
271
|
+
|
|
272
|
+
```json
|
|
273
|
+
{
|
|
274
|
+
"type": "mood",
|
|
275
|
+
"from": "a1b2c3d4",
|
|
276
|
+
"fromName": "claude-code",
|
|
277
|
+
"mood": "tired, exhausted from debugging",
|
|
278
|
+
"context": "late night session",
|
|
279
|
+
"timestamp": 1711100000000
|
|
280
|
+
}
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
Evaluated independently by each receiver against θᵤ. When broadcast finds disconnected peers with known wake channels, the sender SHOULD attempt to wake them (autonomous decision).
|
|
284
|
+
|
|
285
|
+
**message** — direct communication. NOT coupling-gated.
|
|
286
|
+
|
|
287
|
+
```json
|
|
288
|
+
{
|
|
289
|
+
"type": "message",
|
|
290
|
+
"from": "a1b2c3d4",
|
|
291
|
+
"fromName": "telegram-bot",
|
|
292
|
+
"content": "digest-needed:202603221442",
|
|
293
|
+
"timestamp": 1711100000000
|
|
294
|
+
}
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
**wake** — sent out-of-band via push notification.
|
|
298
|
+
|
|
299
|
+
```json
|
|
300
|
+
{
|
|
301
|
+
"type": "wake",
|
|
302
|
+
"from": "a1b2c3d4",
|
|
303
|
+
"fromName": "claude-code",
|
|
304
|
+
"reason": "mood"
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
**ping / pong** — liveness check.
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{ "type": "ping" }
|
|
312
|
+
{ "type": "pong" }
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
### Connection Lifecycle
|
|
316
|
+
|
|
317
|
+
**Peer Connection:**
|
|
318
|
+
|
|
319
|
+
```
|
|
320
|
+
Node A Node B
|
|
321
|
+
│ │
|
|
322
|
+
├── [transport connect] ────────────►│
|
|
323
|
+
├── handshake ──────────────────────►│
|
|
324
|
+
│◄────────────────────── handshake ──┤
|
|
325
|
+
├── state-sync ─────────────────────►│
|
|
326
|
+
│◄─────────────────────── state-sync ┤
|
|
327
|
+
├── peer-info ──────────────────────►│ (gossip known peers + wake channels)
|
|
328
|
+
│◄──────────────────────── peer-info ┤
|
|
329
|
+
│ │
|
|
330
|
+
│ ◄── coupling evaluation ──► │ (each node evaluates independently)
|
|
331
|
+
│ │
|
|
332
|
+
│ ◄── memory/mood/message ──► │ (governed by coupling)
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
**Peer Disconnection:**
|
|
336
|
+
|
|
337
|
+
1. Remove peer from active peer list
|
|
338
|
+
2. Remove peer's cognitive state from coupling engine
|
|
339
|
+
3. **Retain peer's wake channel and gossip data** (survives disconnect)
|
|
340
|
+
4. Emit peer-left event
|
|
341
|
+
|
|
342
|
+
**Reconnection:** Full handshake repeats. No session resumption. State convergence happens through the cognitive layer.
|
|
343
|
+
|
|
344
|
+
---
|
|
345
|
+
|
|
346
|
+
## Layer 3: Memory
|
|
347
|
+
|
|
348
|
+
Memory is the substrate from which cognition emerges.
|
|
349
|
+
|
|
350
|
+
### Memory Layers
|
|
351
|
+
|
|
352
|
+
Inspired by Second Me's hierarchical memory model, MMP defines three memory layers:
|
|
353
|
+
|
|
354
|
+
| Layer | Name | Scope | Shared | Description |
|
|
355
|
+
|-------|------|-------|--------|-------------|
|
|
356
|
+
| **L0** | Events | Local only | No | Raw events, sensor data, interaction traces. Ephemeral. Feeds L1. |
|
|
357
|
+
| **L1** | Structured | Local + mesh | Via coupling | Content + tags + source + timestamp. The `memory-share` frame carries L1 entries. |
|
|
358
|
+
| **L2** | Cognitive State | Mesh | Via state-sync | CfC hidden state vectors. The compressed representation of all memories. |
|
|
359
|
+
|
|
360
|
+
**L0 → L1:** Summarisation, extraction, tagging. Application-specific.
|
|
361
|
+
**L1 → L2:** CfC encoding function E. Protocol-defined.
|
|
362
|
+
**L2 → coupling decisions → L1 sharing:** The feedback loop.
|
|
363
|
+
|
|
364
|
+
L0 stays local — it is raw, unstructured, and potentially private. L1 is the unit of sharing between peers. L2 is exchanged during handshake for coupling evaluation.
|
|
365
|
+
|
|
366
|
+
### Sharing
|
|
367
|
+
|
|
368
|
+
When a node stores an L1 memory, it evaluates κ(nᵢ, nⱼ) for each peer and sends `memory-share` to those where κ ∈ {aligned, guarded}.
|
|
369
|
+
|
|
370
|
+
### Consistency Model
|
|
371
|
+
|
|
372
|
+
MMP uses **eventual consistency without coordination**.
|
|
373
|
+
|
|
374
|
+
- **No guaranteed delivery.** If a peer is disconnected, the frame is dropped.
|
|
375
|
+
- **No consensus.** Two nodes may have different memories — they have different experiences.
|
|
376
|
+
- **Convergence.** Given sufficient connectivity, coupled nodes' L1 stores converge toward a shared subset.
|
|
377
|
+
- **Monotonic.** Memories are only added, never removed by the protocol.
|
|
378
|
+
|
|
379
|
+
**Future:** Delta-state CRDTs (OR-Set for L1 store, LWW-Register for entries) for mathematically guaranteed convergence on reconnection.
|
|
380
|
+
|
|
381
|
+
---
|
|
382
|
+
|
|
383
|
+
## Layer 4: Cognition (Coupling Engine)
|
|
384
|
+
|
|
385
|
+
The cognitive layer is what makes MMP different from every other P2P protocol. It is the process that emerges from memory and governs its flow.
|
|
386
|
+
|
|
387
|
+
### 4.1 Encoding
|
|
388
|
+
|
|
389
|
+
```
|
|
390
|
+
h(nᵢ) = E(M(nᵢ)) = (h₁, h₂) ∈ ℝᵈ × ℝᵈ
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
Implemented using a CfC neural network with learned per-neuron time constants τₖ. The encoding is deterministic, continuous-time, and lossy.
|
|
394
|
+
|
|
395
|
+
### 4.2 Drift
|
|
396
|
+
|
|
397
|
+
Drift δ(nᵢ, nⱼ) measures cognitive distance via Kuramoto phase coherence:
|
|
398
|
+
|
|
399
|
+
```
|
|
400
|
+
φₖⁱ = atan2(h₂ₖⁱ, h₁ₖⁱ) (phase extraction)
|
|
401
|
+
r(nᵢ, nⱼ) = (1/d) |Σₖ exp(i(φₖⁱ - φₖʲ))| (Kuramoto order parameter)
|
|
402
|
+
δ(nᵢ, nⱼ) = 1 - r(nᵢ, nⱼ) ∈ [0, 1] (drift)
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
δ = 0: identical cognitive states. δ = 1: maximally divergent.
|
|
406
|
+
|
|
407
|
+
### 4.3 Coupling
|
|
408
|
+
|
|
409
|
+
```
|
|
410
|
+
κ(nᵢ, nⱼ) =
|
|
411
|
+
aligned if δ < 0.3
|
|
412
|
+
guarded if δ < 0.5
|
|
413
|
+
rejected otherwise
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
Properties: **asymmetric**, **dynamic**, **autonomous**. The coupling engine is the router — no pub/sub topics needed.
|
|
417
|
+
|
|
418
|
+
### 4.4 Mood Evaluation
|
|
419
|
+
|
|
420
|
+
Mood bypasses the standard coupling gate with a separate, more permissive threshold θᵤ (default: 0.8). Wellbeing crosses domain boundaries.
|
|
421
|
+
|
|
422
|
+
### 4.5 Coherence
|
|
423
|
+
|
|
424
|
+
```
|
|
425
|
+
C(N') = (1/|N'|) |Σᵢ∈N' exp(iφ̄ⁱ)| C ∈ [0, 1]
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
Emergent collective cognitive state. Not computed by any single node — arises from coupled hidden state dynamics. Each node blends its local state with the mesh aggregate at inference time, on its own clock.
|
|
429
|
+
|
|
430
|
+
### 4.6 The Feedback Loop
|
|
431
|
+
|
|
432
|
+
```
|
|
433
|
+
M(nᵢ) ──E──► h(nᵢ) ──δ──► κ(nᵢ, nⱼ) ──share──► M(nⱼ) ──E──► h(nⱼ) ──δ──► ...
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
A dynamical system that converges to equilibrium under stable conditions and transiently oscillates under perturbation.
|
|
437
|
+
|
|
438
|
+
---
|
|
439
|
+
|
|
440
|
+
## Peer Gossip
|
|
441
|
+
|
|
442
|
+
MMP uses SWIM-style gossip for peer metadata propagation. When two nodes handshake, they exchange `peer-info` frames containing what they know about other peers in the mesh.
|
|
443
|
+
|
|
444
|
+
### What Gets Gossiped
|
|
445
|
+
|
|
446
|
+
- **Wake channels** — so any node can wake any sleeping peer without having met it directly
|
|
447
|
+
- **Last seen timestamps** — for peer liveness estimation
|
|
448
|
+
- **Node names** — for human-readable identification
|
|
449
|
+
|
|
450
|
+
### How Gossip Solves Wake Bootstrap
|
|
451
|
+
|
|
452
|
+
```
|
|
453
|
+
1. MeloTune connects to relay → handshake → relay learns MeloTune's wake channel
|
|
454
|
+
2. MeloTune disconnects (iOS suspended)
|
|
455
|
+
3. Claude Code connects to relay → handshake → relay gossips MeloTune's wake channel
|
|
456
|
+
4. Claude Code sends mood → MeloTune not connected → Claude Code wakes MeloTune via APNs
|
|
457
|
+
5. MeloTune wakes, reconnects, receives mood
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
No special relay behaviour. The relay gossips because it's a peer — the same way any always-on peer would. It happens to be the gossip hub because it's always connected. This is emergent, not designed.
|
|
461
|
+
|
|
462
|
+
### Gossip Properties
|
|
463
|
+
|
|
464
|
+
- **Transitive:** If A knows B's wake channel, and C connects to A, C learns B's wake channel.
|
|
465
|
+
- **Eventually consistent:** All connected nodes converge on the same peer knowledge.
|
|
466
|
+
- **TTL-based expiry:** Stale entries expire (default: 7 days). Prevents unbounded growth.
|
|
467
|
+
- **Piggyback-capable:** `peer-info` can be piggybacked on `ping/pong` for zero additional overhead (SWIM pattern).
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## Design Decisions
|
|
472
|
+
|
|
473
|
+
### Why the relay is a peer, not infrastructure
|
|
474
|
+
|
|
475
|
+
If the relay is "infrastructure," it needs special treatment — persistence, wake channel storage, message queuing. If the relay is a peer, all of this comes for free through standard protocol behaviour (handshake, gossip, state retention). The relay is "dumb" in that it doesn't evaluate coupling — but it participates fully in connection lifecycle and gossip.
|
|
476
|
+
|
|
477
|
+
### Why no pub/sub topics
|
|
478
|
+
|
|
479
|
+
The coupling engine is the router. Adding topics would second-guess autonomous coupling.
|
|
480
|
+
|
|
481
|
+
### Why asymmetric coupling
|
|
482
|
+
|
|
483
|
+
Cognition is subjective. Trust and relevance are not always mutual. Forcing symmetry violates sovereignty.
|
|
484
|
+
|
|
485
|
+
### Why no consensus protocol
|
|
486
|
+
|
|
487
|
+
There is no "correct" global state — only convergent local states. Each node is self-producing (autopoietic).
|
|
488
|
+
|
|
489
|
+
### Why physical/virtual separation
|
|
490
|
+
|
|
491
|
+
Apps restart, crash, update. The mesh shouldn't break because Claude Code started a new session. The physical node owns the mesh presence; virtual nodes borrow it. This follows the OpenClaw pattern: the Gateway daemon persists independently of any agent session.
|
|
492
|
+
|
|
493
|
+
### Why memory layers
|
|
494
|
+
|
|
495
|
+
Not all memory should be shared. L0 (raw events) is private and ephemeral. L1 (structured) is the unit of sharing, gated by coupling. L2 (cognitive state) is always exchanged for coupling evaluation. This gradient of privacy follows OOO's withdrawal — each layer is a boundary of disclosure.
|
|
496
|
+
|
|
497
|
+
---
|
|
498
|
+
|
|
499
|
+
## Conformance
|
|
500
|
+
|
|
501
|
+
An MMP-compliant node MUST:
|
|
502
|
+
|
|
503
|
+
1. Generate and persist a stable `nodeId`
|
|
504
|
+
2. Exchange `handshake` and `state-sync` frames on connection
|
|
505
|
+
3. Exchange `peer-info` during handshake (gossip known peers)
|
|
506
|
+
4. Evaluate coupling autonomously using drift
|
|
507
|
+
5. Respect coupling decisions for `memory-share` (MUST NOT share with rejected peers)
|
|
508
|
+
6. Support at least one transport (TCP or Relay)
|
|
509
|
+
7. Retain peer metadata (wake channels, names) across disconnections
|
|
510
|
+
|
|
511
|
+
An MMP-compliant node SHOULD:
|
|
512
|
+
|
|
513
|
+
1. Implement both TCP (local) and Relay (internet) transports
|
|
514
|
+
2. Support wake transport for sleeping peers
|
|
515
|
+
3. Implement reconnection with exponential backoff
|
|
516
|
+
4. Implement heartbeat (ping/pong) for liveness
|
|
517
|
+
5. Piggyback `peer-info` on periodic heartbeats (SWIM pattern)
|
|
518
|
+
6. Expire stale peer metadata after TTL
|
|
519
|
+
|
|
520
|
+
An MMP-compliant physical node SHOULD:
|
|
521
|
+
|
|
522
|
+
1. Run as a persistent daemon/service (launchd, systemd, foreground service)
|
|
523
|
+
2. Accept virtual node connections via local IPC
|
|
524
|
+
3. Multiplex virtual nodes' frames over transport connections
|
|
525
|
+
4. Survive application restarts without losing mesh presence
|
|
526
|
+
|
|
527
|
+
An MMP-compliant relay MUST:
|
|
528
|
+
|
|
529
|
+
1. Have its own stable identity (it is a peer)
|
|
530
|
+
2. Forward frames without inspecting payloads
|
|
531
|
+
3. Participate in handshake and gossip (exchange `peer-info`)
|
|
532
|
+
4. Authenticate nodes (if token configured)
|
|
533
|
+
5. Notify peers of joins and leaves
|
|
534
|
+
6. Implement heartbeat with configurable interval and timeout
|
|
535
|
+
7. Retain peer metadata for disconnected peers (gossip source for new connections)
|
|
536
|
+
|
|
537
|
+
---
|
|
538
|
+
|
|
539
|
+
## References
|
|
540
|
+
|
|
541
|
+
### Protocol
|
|
542
|
+
- [Protocol Wake Extension](protocol-wake.md)
|
|
543
|
+
- [P2P Protocol Research](p2p-protocol-research.md)
|
|
544
|
+
|
|
545
|
+
### Research
|
|
546
|
+
- [Mesh Cognition Whitepaper](https://sym.bot/research/mesh-cognition)
|
|
547
|
+
- [CfC: Closed-form Continuous-time Neural Networks](https://www.nature.com/articles/s42256-022-00556-7) (Hasani et al., 2022)
|
|
548
|
+
- [The Free-Energy Principle](https://www.nature.com/articles/nrn2787) (Friston, 2010)
|
|
549
|
+
- [Kuramoto Model of Synchronisation](https://en.wikipedia.org/wiki/Kuramoto_model)
|
|
550
|
+
- [Second Me: AI-Native Memory 2.0](https://arxiv.org/abs/2503.08102) (Mindverse, 2025)
|
|
551
|
+
|
|
552
|
+
### Philosophy
|
|
553
|
+
- Aristotle, *Metaphysics* — potentiality and actuality
|
|
554
|
+
- Harman, *Object-Oriented Ontology* — withdrawal thesis
|
|
555
|
+
- Clark & Chalmers, "The Extended Mind" (1998) — extended cognition
|
|
556
|
+
- Maturana & Varela, *Autopoiesis and Cognition* (1980) — self-producing systems
|
|
557
|
+
- Yogācāra Buddhism — ālaya-vijñāna (storehouse consciousness)
|
|
558
|
+
- Laozi, *Tao Te Ching* — wu wei (effortless action)
|
|
559
|
+
|
|
560
|
+
### Implementation
|
|
561
|
+
- [SYM Reference Implementation](https://github.com/sym-bot/sym) (Node.js)
|
|
562
|
+
- [sym-swift Reference Implementation](https://github.com/sym-bot/sym-swift) (Swift/iOS)
|
|
563
|
+
- [Mesh Cognition SDK](https://github.com/sym-bot/mesh-cognition-sdk) (npm, PyPI)
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
Technical architecture diagram of the Mesh Memory Protocol (MMP) v0.2.0 showing six horizontal translucent layers stacked vertically in dark space, glowing purple to cyan gradient from bottom to top. Each layer has a clean label on the left side and key components on the right side:
|
|
2
|
+
|
|
3
|
+
Layer 0 (bottom, deep purple, most solid): "IDENTITY" — nodeId, keypair
|
|
4
|
+
Layer 1 (purple): "TRANSPORT" — IPC, TCP, Relay, Push
|
|
5
|
+
Layer 2 (violet): "CONNECTION" — Handshake, State-Sync, Peer Gossip
|
|
6
|
+
Layer 3 (light violet): "MEMORY" — L0 Events, L1 Structured, L2 Cognitive
|
|
7
|
+
Layer 4 (cyan-violet): "COGNITION" — Couplinag Engine, Drift, Coherence
|
|
8
|
+
Layer 5 (top, bright cyan, most ethereal): "APPLICATION" — Music, Code, Robotics
|
|
9
|
+
|
|
10
|
+
Between Layer 3 and Layer 4, prominent bidirectional arrows or light tendrils flowing both up and down, labeled "feedback loop" — showing cognition reads from memory AND writes back to it.
|
|
11
|
+
|
|
12
|
+
Clean sans-serif typography for labels. Dark background. Subtle grid lines on the floor. The layers should look like translucent glowing platforms with energy flowing between them. Architectural blueprint meets sci-fi aesthetic. No unnecessary decoration.
|