@sym-bot/sym 0.1.0 → 0.2.0

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.1.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,7 @@ 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.
 
 ## Cognitive Coupling
 
@@ -41,12 +44,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)
 ```
 
@@ -58,37 +61,45 @@ There is no central service. Each agent embeds its own SymNode with its own iden
 
 ```
 ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
-│  Claude Code    │  │  MeloTune     │  │    Agent X     │
-│  (Mac/Windows)  │  │  (iPhone)     │  │  (any platform)│
+│  Claude Code    │  │  MeloTune     │  │  Telegram Bot  │
+│  (Mac/Windows)  │  │  (iPhone)     │  │  (any device)  │
 │                 │  │                │  │                │
 │  ┌───────────┐  │  │  ┌───────────┐ │  │  ┌───────────┐ │
 │  │ SYM Node  │  │  │  │ SYM Node  │ │  │  │ SYM Node  │ │
-│  │ Node.js   │  │  │  │ Swift     │ │  │  │ Any lang  │ │
-│  └─────┬─────┘  │  │  └─────┬─────┘ │  │  └─────┬─────┘ │
-└────────┼────────┘  └────────┼───────┘  └────────┼───────┘
-         │                    │                    │
-         └──── MMP P2P ───────┴──── MMP P2P ──────┘
-
-  discover → encode → exchange state → evaluate drift → couple or reject
+│  │ Node.js   │  │  │  │ Swift     │ │  │  │ Node.js   │ │
+│  └─────┬─────┘  │  └─────┬───────┘ │  │  └─────┬─────┘ │
+└────────┼────────┘  └──────┼────────┘  └────────┼───────┘
+         │                  │                     │
+         ├── Bonjour (LAN) ─┤                     │
+         │                  │                     │
+         └──── WebSocket Relay (internet) ────────┘
 ```
 
 Each node:
-- Encodes its memories into a hidden state vector (context encoder)
-- Discovers peers via Bonjour/mDNS (`_sym._tcp`)
+- 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
 
-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.
+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 +119,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,15 +133,50 @@ node.on('memory-received', ({ from, entry, decision }) => {});
 await node.stop();
 ```
 
+## Transport
+
+SYM supports two transport modes 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 dumb transport — all coupling decisions remain on-device.
+
+```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
+
 ## 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
 ```
 
@@ -140,30 +186,50 @@ One command. Adds MCP server, auto-approves `sym_mood` (no permission prompts),
 
 **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 +237,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 (Bonjour + Relay)
                     │
 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 +253,75 @@ 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
+## Verified in Production
 
-- 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
+- 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
+
+## Semantic vs Neural Coupling
+
+The SDK supports two coupling modes through the same API. The mode is selected automatically based on whether per-neuron time constants (τ) are provided.
+
+### 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 dumb transport — it never inspects frame payloads
 - 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
+- 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.1.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)