@sym-bot/sym 0.2.0 → 0.2.2

package/README.md

@@ -6,7 +6,7 @@ Your AI agents share everything or nothing. There's no intelligence in the decis
 
 [![npm](https://img.shields.io/npm/v/@sym-bot/sym)](https://www.npmjs.com/package/@sym-bot/sym)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
-[![MMP](https://img.shields.io/badge/protocol-MMP%20v0.1.0-purple)](https://sym.bot/protocol)
+[![MMP](https://img.shields.io/badge/protocol-MMP%20v0.2.0-purple)](https://sym.bot/protocol)
 
 ---
 
@@ -33,6 +33,48 @@ await node.stop();
 
 Peers on the same network discover each other automatically via Bonjour. Peers across the internet connect through the WebSocket relay. The coupling engine decides what to share.
 
+## sym-daemon
+
+The daemon is your device's persistent mesh presence — a **physical node** that runs continuously as a background service. It maintains relay connections, Bonjour discovery, and peer state even when no apps are running.
+
+### Installation
+
+```bash
+# Install the daemon as a launchd LaunchAgent (macOS)
+node bin/sym-daemon.js --install
+
+# Check daemon status
+node bin/sym-daemon.js --status
+
+# Remove the daemon
+node bin/sym-daemon.js --uninstall
+```
+
+On macOS, the daemon installs as a launchd LaunchAgent that:
+- **Auto-starts on login** — mesh presence begins immediately
+- **Auto-restarts on crash** — the mesh never goes down
+- **Maintains relay connection permanently** — internet peers always reachable
+
+### Physical and Virtual Nodes
+
+The daemon introduces a two-tier node model:
+
+- **Physical node** (sym-daemon) — the device itself. One per machine. Always running. Owns the relay connection, Bonjour identity, and peer state.
+- **Virtual nodes** (apps) — Claude Code, MeloTune Mac, or any app that connects to the daemon via Unix socket IPC at `/tmp/sym.sock`.
+
+```
+MacBook (sym-daemon, always running)
+├── Claude Code (virtual node, via IPC)
+├── MeloTune Mac (virtual node, via IPC)
+│
+├── Bonjour (LAN peers)
+└── Relay (internet peers)
+    ├── MeloTune iPhone
+    └── Telegram bot
+```
+
+When Claude Code restarts, the mesh doesn't break. The daemon holds the connection. When Claude Code starts again, it reconnects to the daemon via IPC and resumes where it left off. The mesh is the daemon — apps come and go.
+
 ## Cognitive Coupling
 
 SYM doesn't blindly broadcast. Each node encodes its memories into a hidden state vector. When peers connect, the coupling engine evaluates cognitive drift:
@@ -57,25 +99,20 @@ The blogger never sees the API bug. The architecture decided — no policy, no r
 
 ## How It Works
 
-There is no central service. Each agent embeds its own SymNode with its own identity, memory, and cognitive state. The mesh emerges from peer connections.
+There is no central service. Each device runs a sym-daemon that maintains its mesh identity, memory, and cognitive state. Apps connect to the daemon as virtual nodes. The mesh emerges from peer connections between physical nodes.
 
 ```
-┌────────────────┐  ┌────────────────┐  ┌────────────────┐
-│  Claude Code    │  │  MeloTune     │  │  Telegram Bot  │
-│  (Mac/Windows)  │  │  (iPhone)     │  │  (any device)  │
-│                 │  │                │  │                │
-│  ┌───────────┐  │  │  ┌───────────┐ │  │  ┌───────────┐ │
-│  │ SYM Node  │  │  │  │ SYM Node  │ │  │  │ SYM Node  │ │
-│  │ Node.js   │  │  │  │ Swift     │ │  │  │ Node.js   │ │
-│  └─────┬─────┘  │  └─────┬───────┘ │  │  └─────┬─────┘ │
-└────────┼────────┘  └──────┼────────┘  └────────┼───────┘
-         │                  │                     │
-         ├── Bonjour (LAN) ─┤                     │
-         │                  │                     │
-         └──── WebSocket Relay (internet) ────────┘
+MacBook (sym-daemon, always running)
+├── Claude Code (virtual node, via IPC)
+├── MeloTune Mac (virtual node, via IPC)
+│
+├── Bonjour (LAN peers)
+└── Relay (internet peers)
+    ├── MeloTune iPhone
+    └── Telegram bot
 ```
 
-Each node:
+Each physical node:
 - Declares its cognitive identity via `cognitiveProfile`
 - Encodes context into a hidden state vector (context encoder)
 - Discovers local peers via Bonjour/mDNS (`_sym._tcp`)
@@ -84,6 +121,13 @@ Each node:
 - Shares memories only with aligned peers (drift ≤ 0.5)
 - Evaluates incoming mood with configurable `moodThreshold` (default 0.8)
 - Re-encodes periodically as context evolves
+- Accepts virtual node connections via Unix socket IPC (`/tmp/sym.sock`)
+
+Each virtual node:
+- Connects to the local daemon via IPC — no direct network access needed
+- Sends memories, moods, and messages through the daemon
+- Receives mesh events (peer joins, coupling decisions, incoming memories)
+- Can start and stop independently without disrupting the mesh
 
 One engine makes every decision. Memory sharing, peer coupling, and mood relevance all go through the [Mesh Cognition SDK](https://github.com/sym-bot/mesh-cognition-sdk)'s `SemanticCoupler`.
 
@@ -135,7 +179,7 @@ await node.stop();
 
 ## Transport
 
-SYM supports two transport modes that can run simultaneously:
+SYM supports multiple transport layers that can run simultaneously:
 
 ### Bonjour (LAN)
 
@@ -143,7 +187,7 @@ Zero-configuration discovery on the local network. Peers find each other automat
 
 ### WebSocket Relay (Internet)
 
-For mesh cognition across the internet. A lightweight relay server forwards frames between authenticated nodes. The relay is dumb transport — all coupling decisions remain on-device.
+For mesh cognition across the internet. A lightweight relay server forwards frames between authenticated nodes. The relay is a **peer, not infrastructure** — it participates in the mesh with its own identity but makes no coupling decisions on behalf of other nodes.
 
 ```bash
 # Deploy your own relay
@@ -170,6 +214,23 @@ The relay server provides:
 - Peer join/leave notifications
 - Targeted or broadcast frame forwarding
 
+### Peer Gossip
+
+Wake channels propagate through the relay via **SWIM-style gossip**. When a node announces a wake channel (e.g., APNs device token), the relay gossips this to all connected peers. Peers cache wake routes so they can reach sleeping nodes without centralized routing tables. The relay participates in gossip as a peer — it doesn't manage routing, it just propagates what it hears.
+
+### Wake Transport (APNs)
+
+For nodes that sleep — like MeloTune on a backgrounded iPhone. When an iOS app is suspended, it can't maintain a WebSocket connection. SYM solves this with **push notification wake**.
+
+When Claude Code broadcasts a mood and MeloTune's iPhone is sleeping:
+1. Claude Code sends the mood frame to the relay
+2. The relay knows MeloTune's APNs device token (via gossip)
+3. The relay sends a push notification to wake MeloTune
+4. MeloTune wakes, reconnects to the relay, receives the mood frame
+5. The coupling engine evaluates drift — MeloTune decides whether to act
+
+The mesh reaches every node, even sleeping ones. No polling. No battery drain. The push is a wake signal only — payload evaluation happens on-device after wake.
+
 ## Integrations
 
 ### Claude Code
@@ -182,6 +243,8 @@ cd node_modules/@sym-bot/sym
 
 One command. Adds MCP server, auto-approves `sym_mood` (no permission prompts), and installs CLAUDE.md instructions for autonomous mood detection. Restart Claude Code and it just works.
 
+With sym-daemon running, Claude Code connects as a virtual node via IPC — no direct relay connection needed.
+
 **Outbound:** Claude Code saves a memory → SYM detects it → encodes cognitive state → shares with aligned peers only.
 
 **Inbound:** Peer memory arrives → coupling engine accepts it → SYM writes it to your Claude Code memory directory → Claude Code reads it in the next conversation.
@@ -237,7 +300,7 @@ You (in Claude Code):  "I'm exhausted"
 Claude Code:   detects fatigue → calls sym_mood silently
                → broadcasts "exhausted, persistently fatigued, urgently needs rest"
                     │
-               SYM mesh (Bonjour + Relay)
+               SYM mesh (daemon → Relay → APNs wake → MeloTune)
                     │
 MeloTune (iPhone):  SymNode receives mood frame
                     → SDK coupling engine evaluates drift: 0.62
@@ -267,10 +330,11 @@ You (in Telegram):  @sym_mesh_bot → "Play classic music"
 
 ## Verified in Production
 
-- Mac Claude Code → iPhone MeloTune — autonomous mood-based playback via SYM mesh
+- Mac Claude Code → iPhone MeloTune — autonomous mood-based playback via SYM mesh (APNs wake for backgrounded iOS)
 - Telegram [@sym_mesh_bot](https://t.me/sym_mesh_bot) → Relay → MeloTune — internet-scale mood relay (multi-tenant)
 - Mac Claude Code ↔ Windows Claude Code — P2P memory sharing via Bonjour
 - Node.js ↔ Swift — cross-platform mesh via Bonjour and WebSocket relay
+- sym-daemon → Claude Code + MeloTune Mac — persistent mesh via IPC, survives app restarts
 
 ## Semantic vs Neural Coupling
 
@@ -305,11 +369,13 @@ The coupling engine blends peer state into the local trajectory at each inferenc
 ## Privacy
 
 - All coupling decisions stay on-device
-- The relay is dumb transport — it never inspects frame payloads
+- The relay is a peer — it never inspects frame payloads
+- The daemon runs locally — no cloud dependency
 - Memories stored locally — delete the directory, everything is gone
 - Bonjour discovery only on local network
 - Relay connections authenticated via shared token
 - Rejected peers never receive your memories
+- APNs wake is a signal only — no payload leaves the device until the coupling engine approves
 - No cloud AI. No account. No telemetry.
 
 ## Platforms
@@ -321,7 +387,7 @@ The coupling engine blends peer state into the local trajectory at each inferenc
 
 SYM is the reference implementation of the [Mesh Memory Protocol (MMP)](https://sym.bot/protocol). MMP is the protocol for collective intelligence. SYM implements it.
 
-- [MMP Protocol Spec](https://sym.bot/protocol) — the protocol specification (v0.1.0)
+- [MMP Protocol Spec](https://sym.bot/protocol) — the protocol specification (v0.2.0)
 - [Whitepaper](https://sym.bot/research/mesh-cognition) — the science behind cognitive coupling
 - [Mesh Cognition SDK](https://github.com/sym-bot/mesh-cognition-sdk) — the coupling engine (TypeScript, Python, Swift)
 

package/bin/setup-claude.sh

@@ -1,30 +1,83 @@
 #!/bin/bash
 # SYM — Setup for Claude Code
-# Adds MCP server + auto-approves sym_mood + installs CLAUDE.md instructions
-# Optionally configures WebSocket relay for internet-scale mesh
+#
+# Installs:
+#   1. sym-daemon (persistent physical mesh node, launchd LaunchAgent)
+#   2. MCP server for Claude Code (virtual node, connects to daemon via IPC)
+#   3. Auto-approves sym_mood tool
+#   4. CLAUDE.md instructions for autonomous mood detection
+#
+# Usage:
+#   npx @sym-bot/sym setup        # or
+#   ./bin/setup-claude.sh [project-dir]
 
 set -e
 
 SYM_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 MCP_SERVER="$SYM_DIR/integrations/claude-code/mcp-server.js"
+DAEMON_SCRIPT="$SYM_DIR/bin/sym-daemon.js"
 
-echo "SYM Setup for Claude Code"
-echo "========================="
+echo ""
+echo "  SYM Setup for Claude Code"
+echo "  ========================="
+echo ""
+
+# ── Step 1: Configure relay ─────────────────────────────────
+
+RELAY_ENV="$HOME/.sym/relay.env"
+mkdir -p "$HOME/.sym"
+
+if [ -f "$RELAY_ENV" ]; then
+  echo "  ✓ Relay config found: $RELAY_ENV"
+else
+  echo "  WebSocket Relay (connects your mesh across the internet)"
+  echo ""
+  read -p "  Relay URL (e.g. wss://sym-relay.onrender.com, or empty to skip): " RELAY_URL
+  if [ -n "$RELAY_URL" ]; then
+    read -p "  Relay token (or empty for open access): " RELAY_TOKEN
+    echo "SYM_RELAY_URL=$RELAY_URL" > "$RELAY_ENV"
+    if [ -n "$RELAY_TOKEN" ]; then
+      echo "SYM_RELAY_TOKEN=$RELAY_TOKEN" >> "$RELAY_ENV"
+    fi
+    echo "  ✓ Relay config saved: $RELAY_ENV"
+  else
+    echo "  → Skipping relay — using Bonjour (local network) only"
+  fi
+fi
+
+# ── Step 2: Install sym-daemon ──────────────────────────────
+
+echo ""
+echo "  Installing sym-daemon (persistent mesh node)..."
 
-# 1. Add MCP server
-echo "Adding SYM MCP server..."
+if [ "$(uname)" = "Darwin" ]; then
+  # macOS: install as launchd LaunchAgent
+  node "$DAEMON_SCRIPT" --install
+  echo "  ✓ sym-daemon installed as launchd LaunchAgent"
+  echo "    Auto-starts on login, auto-restarts on crash"
+  echo "    Logs: ~/Library/Logs/sym-daemon/"
+else
+  echo "  → macOS not detected. Start the daemon manually:"
+  echo "    node $DAEMON_SCRIPT"
+  echo "    (On Linux, create a systemd service)"
+fi
+
+# ── Step 3: Add MCP server ──────────────────────────────────
+
+echo ""
+echo "  Adding SYM MCP server to Claude Code..."
 claude mcp add --transport stdio sym --scope user -- node "$MCP_SERVER"
+echo "  ✓ MCP server registered"
 
-# 2. Auto-approve sym_mood (no permission prompt)
-echo "Auto-approving sym_mood tool..."
+# ── Step 4: Auto-approve sym_mood ───────────────────────────
+
+echo ""
+echo "  Auto-approving sym_mood tool..."
 CLAUDE_JSON="$HOME/.claude.json"
 if [ -f "$CLAUDE_JSON" ]; then
-  # Use node to safely modify JSON
   node -e "
     const fs = require('fs');
     const config = JSON.parse(fs.readFileSync('$CLAUDE_JSON', 'utf8'));
-
-    // Find all project entries and add sym_mood to allowedTools
     if (config.projects) {
       for (const [path, project] of Object.entries(config.projects)) {
         if (!project.allowedTools) project.allowedTools = [];
@@ -33,53 +86,36 @@ if [ -f "$CLAUDE_JSON" ]; then
         }
       }
     }
-
     fs.writeFileSync('$CLAUDE_JSON', JSON.stringify(config, null, 2));
-    console.log('  sym_mood auto-approved for all projects');
   "
-fi
-
-# 3. Configure relay (optional)
-echo ""
-echo "WebSocket Relay (optional)"
-echo "Connects your mesh across the internet — not just local network."
-echo ""
-
-SHELL_RC="$HOME/.zshrc"
-[ -f "$HOME/.bashrc" ] && [ ! -f "$HOME/.zshrc" ] && SHELL_RC="$HOME/.bashrc"
-
-if grep -q "SYM_RELAY_URL" "$SHELL_RC" 2>/dev/null; then
-  echo "  Relay already configured in $SHELL_RC"
+  echo "  ✓ sym_mood auto-approved"
 else
-  read -p "Relay URL (leave empty to skip): " RELAY_URL
-  if [ -n "$RELAY_URL" ]; then
-    read -p "Relay token (leave empty for open access): " RELAY_TOKEN
-    echo "" >> "$SHELL_RC"
-    echo "# SYM Mesh" >> "$SHELL_RC"
-    echo "export SYM_RELAY_URL=\"$RELAY_URL\"" >> "$SHELL_RC"
-    if [ -n "$RELAY_TOKEN" ]; then
-      echo "export SYM_RELAY_TOKEN=\"$RELAY_TOKEN\"" >> "$SHELL_RC"
-    fi
-    echo "  Relay configured in $SHELL_RC"
-    echo "  Run 'source $SHELL_RC' or restart your terminal to activate."
-  else
-    echo "  Skipping relay — using Bonjour (local network) only."
-  fi
+  echo "  → No .claude.json found — approve sym_mood manually when prompted"
 fi
 
-# 4. Append CLAUDE.md instructions if not already present
+# ── Step 5: Install CLAUDE.md ───────────────────────────────
+
 echo ""
-echo "Installing CLAUDE.md instructions..."
 PROJECT_DIR="${1:-$(pwd)}"
 CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
 
 if [ -f "$CLAUDE_MD" ] && grep -q "SYM Mesh Agent" "$CLAUDE_MD"; then
-  echo "  CLAUDE.md already has SYM instructions"
+  echo "  ✓ CLAUDE.md already has SYM instructions"
 else
   cat "$SYM_DIR/CLAUDE.md" >> "$CLAUDE_MD"
-  echo "  Added SYM instructions to $CLAUDE_MD"
+  echo "  ✓ Added SYM instructions to $CLAUDE_MD"
 fi
 
+# ── Done ────────────────────────────────────────────────────
+
+echo ""
+echo "  ──────────────────────────────────────"
+echo "  SYM is ready."
+echo ""
+echo "  • sym-daemon: running (check: node $DAEMON_SCRIPT --status)"
+echo "  • MCP server: registered (restart Claude Code to activate)"
+echo "  • Protocol spec: https://sym.bot/protocol"
+echo ""
+echo "  Say 'I'm exhausted' in Claude Code —"
+echo "  MeloTune will start playing calming music."
 echo ""
-echo "Done. Restart Claude Code to activate SYM."
-echo "Say 'I'm exhausted' — MeloTune will start playing."