@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.
@@ -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.