@sym-bot/sym 0.1.0 → 0.2.1

package/PRD.md

@@ -166,7 +166,7 @@ SYM is the product layer. The SDK is the engine.
 | **Audience** | App developers | AI tool users |
 | **Decision** | Drift evaluation | Memory, mood, peer coupling |
 | **Platform** | TypeScript, Python, Swift | Node.js, Swift |
-| **Install** | `npm install mesh-cognition` | `npm install sym` / SPM |
+| **Install** | `npm install mesh-cognition` | `npm install @sym-bot/sym` / SPM |
 
 ---
 

package/README.md

@@ -1,25 +1,28 @@
 # SYM
 
-**Local AI mesh with cognitive coupling — every agent is a sovereign node.**
+**Reference implementation of the [Mesh Memory Protocol (MMP)](https://sym.bot/protocol) — every agent is a sovereign node.**
 
 Your AI agents share everything or nothing. There's no intelligence in the decision. SYM adds the missing layer — each node encodes its context into a cognitive state, and the coupling engine evaluates drift before sharing. Aligned agents share knowledge. Divergent agents stay independent. The architecture decides, not policy.
 
-[![npm](https://img.shields.io/npm/v/sym)](https://www.npmjs.com/package/sym)
+[![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.2.0-purple)](https://sym.bot/protocol)
 
 ---
 
 ## Quick Start
 
 ```bash
-git clone https://github.com/sym-bot/sym.git
-cd sym && npm install
+npm install @sym-bot/sym
 ```
 
 ```javascript
-const { SymNode } = require('./lib/node');
+const { SymNode } = require('@sym-bot/sym');
 
-const node = new SymNode({ name: 'my-agent' });
+const node = new SymNode({
+  name: 'my-agent',
+  cognitiveProfile: 'Coding assistant that understands bugs, APIs, and debugging',
+});
 await node.start();
 
 node.remember('race condition in order processing', { tags: ['bug'] });
@@ -28,7 +31,49 @@ node.recall('order');
 await node.stop();
 ```
 
-Three lines to join the mesh. Peers on the same network discover each other automatically via Bonjour. The coupling engine decides what to share.
+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
 
@@ -41,12 +86,12 @@ SYM doesn't blindly broadcast. Each node encodes its memories into a hidden stat
 ```
 Three agents. Two work on APIs. One writes a food blog.
 
-API Dev ↔ API Fix:   drift 0.633 → guarded (related context)
-API Dev ↔ Blogger:   drift 1.185 → rejected (unrelated context)
-API Fix ↔ Blogger:   drift 1.187 → rejected (unrelated context)
+API Dev ↔ API Fix:   drift 0.38 → guarded (related context, shared with reduced confidence)
+API Dev ↔ Blogger:   drift 1.19 → rejected (unrelated context)
+API Fix ↔ Blogger:   drift 1.18 → rejected (unrelated context)
 
 API Dev remembers "race condition in order processing"
-  → Shared with API Fix ✓
+  → Shared with API Fix ✓ (guarded — related domain)
   → Not shared with Blogger ✗ (rejected by coupling engine)
 ```
 
@@ -54,41 +99,51 @@ 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     │  │    Agent X     │
-│  (Mac/Windows)  │  │  (iPhone)     │  │  (any platform)│
-│                 │  │                │  │                │
-│  ┌───────────┐  │  │  ┌───────────┐ │  │  ┌───────────┐ │
-│  │ SYM Node  │  │  │  │ SYM Node  │ │  │  │ SYM Node  │ │
-│  │ Node.js   │  │  │  │ Swift     │ │  │  │ Any lang  │ │
-│  └─────┬─────┘  │  │  └─────┬─────┘ │  │  └─────┬─────┘ │
-└────────┼────────┘  └────────┼───────┘  └────────┼───────┘
-         │                    │                    │
-         └──── MMP P2P ───────┴──── MMP P2P ──────┘
-
-  discover → encode → exchange state → evaluate drift → couple or reject
+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:
-- Encodes its memories into a hidden state vector (context encoder)
-- Discovers peers via Bonjour/mDNS (`_sym._tcp`)
+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`)
+- Connects to remote peers via WebSocket relay
 - Exchanges cognitive state with peers
-- Evaluates drift — how similar is this peer's focus to mine?
-- Shares memories only with aligned peers
-- Evaluates incoming mood against own cognitive state — the SDK's coupling engine decides whether to act
+- 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`)
 
-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`. No routing tables. No capability registration. The coupling engine decides.
+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`.
 
 ## API
 
 ```javascript
-const { SymNode } = require('sym');
-
-const node = new SymNode({ name: 'my-agent' });
+const { SymNode } = require('@sym-bot/sym');
+
+const node = new SymNode({
+  name: 'my-agent',
+  cognitiveProfile: 'What this agent understands and responds to',
+  moodThreshold: 0.8,   // how permissive to mood signals (default 0.8)
+  relay: 'wss://your-relay.example.com',  // optional relay for internet mesh
+  relayToken: 'shared-secret',            // optional relay auth token
+  relayOnly: false,      // skip Bonjour, relay only (default false)
+});
 await node.start();
 
 // Memory (shared only with cognitively aligned peers)
@@ -108,8 +163,8 @@ node.on('mood-rejected', ({ from, mood, drift }) => {
 node.send(message);
 node.on('message', (from, content) => {});
 
-// Monitoring (includes coupling state per peer)
-node.peers();       // [{ name, coupling: 'aligned', drift: 0.12 }, ...]
+// Monitoring
+node.peers();       // [{ name, coupling: 'aligned', drift: 0.12, source: 'relay' }, ...]
 node.coherence();   // Overall mesh coherence
 node.status();      // Full node status
 
@@ -122,48 +177,122 @@ node.on('memory-received', ({ from, entry, decision }) => {});
 await node.stop();
 ```
 
+## Transport
+
+SYM supports multiple transport layers that can run simultaneously:
+
+### Bonjour (LAN)
+
+Zero-configuration discovery on the local network. Peers find each other automatically via `_sym._tcp` mDNS. Direct TCP connections with length-prefixed JSON framing. No setup required.
+
+### WebSocket Relay (Internet)
+
+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
+cd sym-relay
+npm install
+SYM_RELAY_TOKEN=your-secret node server.js
+```
+
+```javascript
+// Connect a node to the relay
+const node = new SymNode({
+  name: 'my-agent',
+  relay: 'wss://your-relay.example.com',
+  relayToken: 'your-secret',
+});
+```
+
+**Hybrid mode** (default): nodes discover local peers via Bonjour AND connect to the relay for remote peers. Same node, same coupling engine, two transport layers.
+
+The relay server provides:
+- Token-based authentication
+- Health endpoint (`GET /health`)
+- 30-second heartbeat (keeps connections alive on cloud platforms)
+- 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
 
-SYM bridges Claude Code's memory system to the mesh. No extra commands needed.
-
 ```bash
-git clone https://github.com/sym-bot/sym.git
-cd sym && npm install
+npm install @sym-bot/sym
+cd node_modules/@sym-bot/sym
 ./bin/setup-claude.sh /path/to/your/project
 ```
 
 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.
 
-Explicit tools are also available for direct mesh interaction:
-
 | Tool | What it does |
 |------|-------------|
+| `sym_mood` | Proactively broadcasts detected mood to the mesh |
 | `sym_remember` | Store a memory directly to the mesh |
 | `sym_recall` | Search memories across the mesh |
+| `sym_send` | Send a message to all peers |
 | `sym_peers` | Show connected peers with coupling state and drift |
 | `sym_status` | Full node status — identity, peers, memory count, coherence |
 
-## Multi-Device
-
-Start agents on different machines on the same network. Bonjour discovers peers automatically. No configuration.
+To connect Claude Code to the relay, set environment variables:
 
+```bash
+export SYM_RELAY_URL=wss://your-relay.example.com
+export SYM_RELAY_TOKEN=your-secret
 ```
-Machine A (Mac):     SymNode('my-agent')  ──┐
-                                             ├── MMP P2P
-Machine B (Windows): SymNode('my-agent')  ──┘
+
+### Telegram
+
+A multi-tenant Telegram bot — each user gets their own isolated SYM mesh node with separate identity, memory, and coupling state.
+
+**Public bot:** Message [@sym_mesh_bot](https://t.me/sym_mesh_bot) on Telegram and send `/start` to connect.
+
+**Self-hosted:**
+
+```bash
+TELEGRAM_BOT_TOKEN=your-bot-token \
+SYM_RELAY_TOKEN=your-secret \
+node integrations/telegram/bot.js
 ```
 
-Cognitive coupling works across devices — the coupling engine evaluates drift the same way regardless of whether the peer is on the same machine or across the network.
+Commands:
+- `/start` — connect to the SYM mesh
+- `/peers` — connected mesh peers
+- `/mood <text>` — broadcast mood to mesh
+- `/remember <text>` — store memory in mesh
+- `/recall <query>` — search mesh memories
+- `/stop` — disconnect from mesh
+- Any plain text — broadcast as a mood signal
+
+Mesh events (peer joins, messages, mood signals, coupling decisions) are forwarded to your chat. Sessions auto-disconnect after 30 minutes of inactivity.
 
 ## Demo: Autonomous Mood Detection
 
-You're coding with Claude Code for hours. You say "I'm exhausted." You didn't ask for music. But Claude Code detected your fatigue, broadcast your mood to the mesh, and MeloTune on your iPhone started playing Spa music. Autonomously.
+You're coding with Claude Code for hours. You say "I'm exhausted." You didn't ask for music. But Claude Code detected your fatigue, broadcast your mood to the mesh, and MeloTune on your iPhone started playing spa music. Autonomously.
 
 ```
 You (in Claude Code):  "I'm exhausted"
@@ -171,14 +300,14 @@ 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 P2P)
+               SYM mesh (daemon → Relay → APNs wake → MeloTune)
                     │
 MeloTune (iPhone):  SymNode receives mood frame
-                    → SDK coupling engine evaluates drift: 0.75
+                    → SDK coupling engine evaluates drift: 0.62
                     → cognitiveProfile includes "tired, exhausted, rest"
-                    → drift 0.75 < moodThreshold 0.80 → ACCEPTED
+                    → drift 0.62 ≤ moodThreshold 1.2 → ACCEPTED
                     → rule-based parser: recovery, rest → Healing
-                    → Apple Music: Spa playlist, 88 tracks
+                    → Apple Music: spa playlist
                     → zero LLM tokens
                     → you didn't ask — the agents decided
 ```
@@ -187,40 +316,78 @@ MeloTune (iPhone):  SymNode receives mood frame
 
 | Evaluation | Drift | Threshold | Decision |
 |-----------|-------|-----------|----------|
-| Memory coupling | 1.16 | 0.50 | Rejected — coding memories don't leak into music context |
-| Mood coupling | 0.75 | 0.80 | Accepted — "exhausted" aligns with MeloTune's cognitiveProfile |
+| Memory coupling | 1.06 | 0.50 | Rejected — coding memories don't leak into music context |
+| Mood coupling | 0.62 | 1.20 | Accepted — "exhausted" aligns with MeloTune's cognitiveProfile |
 
 The SDK's `SemanticCoupler` makes every decision. The agent's `cognitiveProfile` declares what it understands. The `moodThreshold` controls how permissive the agent is to mood signals. No routing tables. No capability registration. The engine decides.
 
-Also works with explicit commands:
+Also works via Telegram:
 
 ```
-"play some sleep music, I want a 1 hour break"
-  → Dark Ambient playlist + 60min sleep timer
+You (in Telegram):  @sym_mesh_bot → "Play classic music"
+  → MeloTune plays Modern Classical via Apple Music
 ```
 
-**Platforms:**
-- [sym](https://github.com/sym-bot/sym) — Node.js (npm)
-- [sym-swift](https://github.com/sym-bot/sym-swift) — Swift (SPM) for iOS/macOS
+## Verified in Production
+
+- 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
 
-## Verified
+The SDK supports two coupling modes through the same API. The mode is selected automatically based on whether per-neuron time constants (τ) are provided.
 
-- Mac Claude Code ↔ Windows Claude Code — P2P memory sharing
-- Mac Claude Code → iPhone MeloTune — autonomous mood-based playback via SYM mesh
-- Mac Claude Code → iPhone MeloTune — explicit command with sleep timer
+### Semantic Coupling
+
+For AI agents sharing memory. Uniform coupling across all hidden state dimensions. No trained model needed. Used by Claude Code, Telegram, LangChain, and multi-agent coordination.
+
+```
+Claude Code ↔ Claude Code:  drift 0.38 → guarded → share memories with reduced confidence
+Claude Code ↔ Food Blogger: drift 1.19 → rejected → no sharing
+```
+
+### Neural Coupling
+
+For trained CfC neural networks with per-neuron time constants. Fast-τ neurons (emotion, ~1s) sync quickly between devices. Slow-τ neurons (context/memory, ~5s) stay independent. Real Kuramoto phase coherence r(t).
+
+**In practice — two MeloTune devices on the same mesh:**
+
+| What | Behaviour |
+|------|-----------|
+| **Fast neurons** (low τ) | Sync quickly — both devices converge on emotional trajectory |
+| **Slow neurons** (high τ) | Stay independent — each device retains its own listening context |
+| **Genre selection** | Per-device — iPhone plays Ambient, Mac plays Lo-Fi |
+| **Track selection** | Per-device — never the same tracks |
+| **Mood trajectory** | Shared — iPhone at E:45 N:25, Mac drifts toward E:46 N:36 |
+| **Coherence** | r(t) = 0.94 — high alignment, strong mutual influence |
+
+The coupling engine blends peer state into the local trajectory at each inference step. Influence strength scales with coherence — highly aligned peers have more effect. If you shift one device to high energy, the other gradually follows (fast neurons). But each device's genre, history, and track selection remain sovereign.
 
 ## Privacy
 
-- All data stays on your machines
-- No cloud. No server. No account. No telemetry.
+- All coupling decisions stay on-device
+- 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
+
+- [@sym-bot/sym](https://www.npmjs.com/package/@sym-bot/sym) — Node.js (npm)
+- [sym-swift](https://github.com/sym-bot/sym-swift) — Swift (SPM) for iOS/macOS
 
 ## Built On
 
-SYM is built on the [Mesh Cognition SDK](https://github.com/sym-bot/mesh-cognition-sdk) and the Mesh Memory Protocol (MMP). The SDK provides the coupling engine. SYM makes it usable for AI agents.
+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.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)