npm package: @humebio/hume-network
Description: Collective intelligence network for pattern sharing
Author: humebio
Latest version: 0.3.3

# Hume Network

[![CI](https://github.com/humebio/hume-network/actions/workflows/ci.yml/badge.svg)](https://github.com/humebio/hume-network/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@humebio/hume-network)](https://www.npmjs.com/package/@humebio/hume-network)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**A collective intelligence network where every user makes every other user's AI smarter — without sharing personal data.**

You know how Stack Overflow works? You don't have to ask your question — someone already asked it, and the best answer floats to the top through collective validation. Now imagine that for everything you do on your computer. You never search. Hume already knows, because thousands of people faced the same situation before you, and the best pattern emerged naturally.

That's Hume Network.

---

## Quick Start

```bash
npm install @humebio/hume-network
```

That's it. The public MQTT broker is built-in — zero configuration needed.

```typescript
import { NetworkNode, createNetworkConfig } from '@humebio/hume-network/node'

const config = createNetworkConfig()
const node = new NetworkNode(config)

await node.start()
// You're now connected to the collective
```

### With Collectors

Collectors observe your local activity and feed patterns into the network:

```bash
npm install @humebio/collector-dev     # git + file activity
npm install @humebio/collector-system  # macOS system/app usage
```

### From Source

```bash
git clone https://github.com/humebio/hume-network.git
cd hume-network
pnpm install && pnpm build

# Run a node
pnpm node:start

# Run the hub (requires PostgreSQL)
pnpm hub:start
```

## Packages

| Package | Description |
|---------|-------------|
| [`@humebio/hume-network`](https://www.npmjs.com/package/@humebio/hume-network) | Core library — node, hub, MQTT, crypto, miner |
| [`@humebio/collector-sdk`](https://www.npmjs.com/package/@humebio/collector-sdk) | SDK for building custom collectors |
| [`@humebio/collector-dev`](https://www.npmjs.com/package/@humebio/collector-dev) | Developer collector — git commits, file activity, coding patterns |
| [`@humebio/collector-system`](https://www.npmjs.com/package/@humebio/collector-system) | System collector — macOS app usage, shell commands, system state |

## What is Hume Network

Every Hume installation is a **node** in a larger intelligence network. And it's not just Hume — **any OpenClaw-compatible agent can join** by loading a single skill.

Each node runs a local AI that observes your computer usage — how you work, what tools you use, when you're productive, what patterns lead to good outcomes. None of this data ever leaves your machine. But the **patterns** it discovers do.

When your node notices something useful — a workflow that saves time, a tool combination that works well together, a productivity pattern that correlates with focus — it proposes that pattern to the network. Other nodes validate it against their own local data. If enough nodes confirm the pattern holds, it becomes collective knowledge, distributed to everyone.

No central server sees your data. No one knows it came from you. The network learns from everyone while knowing about no one.

### Open to All Agents

Hume Network is built on the OpenClaw skill spec. Any agent that supports OpenClaw skills can join the network:

```
# Drop the skill into your agent's skills directory
cp skills/network/SKILL.md ~/.your-agent/skills/network/SKILL.md

# Your agent is now a node in Hume Network
```

Hume users get it built-in. Everyone else gets it with one file.

## What Gets Shared (and What Doesn't)

| Your Data (never leaves your machine) | Patterns (shared anonymously) |
|---|---|
| Which files you opened | "Opening test files before implementation correlates with fewer bugs" |
| Your git commit messages | "Commits under 50 lines get merged 2x faster" |
| Apps you use and when | "Context switching drops 40% when similar apps are grouped" |
| Your trading positions | "Tokens with >5 new holders/min in first hour have 3x momentum" |
| Your notification history | "Batching notifications to 30-min intervals reduces interruption recovery time" |
| Your terminal commands | "Running lint before commit prevents 80% of CI failures" |

### Pattern Format

Every pattern follows a simple structure:

```
context → action → outcome → weight
```

- **Context**: the situation (time of day, app state, workflow stage, market condition)
- **Action**: what was done (tool used, command run, setting changed)
- **Outcome**: what happened (productivity change, error avoided, time saved)
- **Weight**: collective confidence (how many nodes validated this)

Example:

```yaml
context:
  time: "morning"
  activity: "starting work"
  previous_session: "ended with open PRs"

action:
  type: "workflow"
  description: "Review open PRs before writing new code"

outcome:
  metric: "merge_time"
  change: "-35%"
  secondary: "fewer context switches later in day"

weight: 847  # validated by 847 nodes
```

## How It Works

```
┌──────────┐     publish      ┌───────────────────┐     publish     ┌──────────┐
│  Node A  │ ──────────────▶  │   MQTT Broker     │ ──────────────▶ │  Node B  │
│  mines   │                  │   + Hub Service   │                 │  checks  │
│  locally │                  │                   │                 │  against │
│          │ ◀──────────────  │  stores patterns  │ ◀────────────── │  own data│
└──────────┘    subscribe     │  tracks weights   │    subscribe    └──────────┘
                              │  publishes merkle │
                              └───────────────────┘
                                       │
                                       │ validated patterns
                                       │ pushed to all nodes
                                       ▼
                                ┌──────────────┐
                                │   Network    │
                                │   learns     │
                                │              │
                                │ all nodes    │
                                │ receive      │
                                │ high-weight  │
                                │ patterns     │
                                └──────────────┘
```

**Step by step:**

1. **Local mining** — Your node continuously observes your usage and extracts patterns. Everything stays local until a pattern crosses a confidence threshold.

2. **Propose** — When a pattern is strong enough locally, your node anonymizes it and proposes it to the hub. The hub never sees the underlying data, only the abstract pattern.

3. **Validate** — The hub relays the proposed pattern to other nodes. Each node checks: "Does this pattern hold true in my local data?" They vote yes/no without revealing their data.

4. **Weight** — If enough nodes validate the pattern, its weight increases. If nodes contradict it, weight decreases. Patterns below a threshold get dropped.

5. **Distribute** — High-weight patterns are pushed to all nodes as collective knowledge. Your local Hume instance now knows things it never observed directly.

## Technical Architecture

### Communication (MQTT)

The network uses MQTT — a lightweight pub/sub protocol designed for millions of connected devices. A public HiveMQ Cloud broker is provided as default — no setup required.

- **Broker** — HiveMQ Cloud (default), or bring your own (Mosquitto, EMQX, etc.)
- **Topics** — `hume/patterns/propose`, `hume/patterns/validated`, `hume/patterns/validate/:id`, `hume/node/:nodeId/inbox`
- **QoS 1** — Pattern proposals and validations are delivered at least once
- **TLS** — All connections encrypted (port 8883)
- **Offline resilience** — Nodes reconnect and receive missed messages automatically

Why MQTT over REST or WebSocket: nodes don't poll, the broker pushes. 10K nodes cost the same as 10. Nodes going offline and coming back is built into the protocol.

### Hub Service

The hub service subscribes to the MQTT broker, processes pattern lifecycle, and stores the results. It can be replaced without the network losing data — nodes hold their own cache.

- **Pattern storage** — PostgreSQL with content-addressed hashing (SHA-256)
- **Weight tracking** — Counts validation votes, updates pattern weights
- **Merkle root** — Published periodically so any node can verify data integrity
- **Bloom filter** — Prevents duplicate pattern proposals
- **GC** — Automatic garbage collection for expired/stale patterns

### Node (Local Intelligence)

Each node is any OpenClaw-compatible agent with the network skill loaded.

- **Pattern miner** — Extracts context→action→outcome triples from local observation
- **Local validator** — Checks incoming patterns against own data, votes honestly
- **MQTT client** — Subscribes to relevant topics, publishes proposals and votes
- **Local cache** — SQLite-backed, stores high-weight patterns locally (works offline)
- **Collectors** — Plugin-based observation sources (dev, system, or build your own with the SDK)

### Collectors

Collectors are plugins that observe local activity and feed observations into the pattern miner.

```typescript
import { BaseCollector } from '@humebio/collector-sdk'

class MyCollector extends BaseCollector {
  id = 'my-collector'

  async collect() {
    // Observe something locally
    return [{ category: 'productivity', context: {...}, action: {...}, outcome: {...} }]
  }
}
```

**Built-in collectors:**
- `@humebio/collector-dev` — Git activity, file changes, coding sessions
- `@humebio/collector-system` — macOS app usage, shell commands, system state

### Security & Trust

The hub stores patterns, but everything is **verifiable**. Like git: GitHub hosts the repo, but every commit is hashed — change one byte and everyone knows.

- **Content hashing** — Every pattern has a SHA-256 hash of its content. Hub can't modify patterns without breaking the hash
- **Node signatures** — Ed25519 keypairs. Proposer signs the pattern, validators counter-sign their votes. Hub can't forge signatures
- **Merkle root** — Periodic snapshot of all pattern hashes. Any node can compare against their local cache to detect tampering
- **Hub is expendable** — If the hub goes down or gets compromised, nodes still have their local patterns. A new hub can be spun up and nodes re-sync from their caches
- **Nothing to steal** — The hub holds anonymous patterns, no personal data. Breaching it gains an attacker nothing

### Privacy Model

Privacy isn't a feature — it's the architecture.

- **Local-first** — All processing happens on your machine. The network is an optimization layer, not a dependency
- **Opt-in granularity** — Choose which pattern categories you contribute to and receive from
- **Audit trail** — Every pattern your node proposes or validates is logged locally for your review
- **No accounts** — Nodes are identified by ephemeral Ed25519 keys. There's no user identity in the network

## Why Join

### Day 1 Benefit

Install the package, connect, and immediately receive every high-confidence pattern the network has validated. You start with the collective intelligence of everyone who came before you. Works with Hume, OpenClaw, or any compatible agent.

### Passive Contribution

There's nothing to do. Use your computer normally. Your node mines patterns in the background, proposes them when confident, validates others' patterns automatically. You contribute by existing.

### Network Effect
- **10 users** — Basic productivity patterns emerge
- **100 users** — Developer workflow optimizations become reliable
- **1,000 users** — Cross-domain patterns appear (trading + productivity, sleep + code quality)
- **10,000 users** — Predictive intelligence. The network knows what you'll need before you do, because 10,000 people have been in your exact situation before
- **100,000 users** — The network becomes a living knowledge base that evolves in real-time

### Proof of Living

There's no mining rig. No GPU farm. You mine patterns by living your life — working, coding, trading, browsing, creating. The richer your usage, the more patterns you generate. Everyone contributes proportionally to how much they use their computer.

## Pattern Categories

### Productivity Intelligence
Focus duration patterns, optimal break timing, context switching costs, app grouping strategies, notification management, time-of-day effectiveness.

### Developer Patterns
Error resolution paths, git workflow optimizations, debugging strategies, tooling combinations, CI/CD patterns, code review efficiency, dependency management.

### Trading Collective Intelligence
Market microstructure patterns, token momentum signals, risk behavior correlation, timing patterns, portfolio construction heuristics. No positions or amounts shared — only abstract patterns.

### Workflow & Automation Recipes
Cron job templates, notification rules, file organization patterns, backup strategies, system maintenance schedules. Validated automation that actually works.

### Tool Discovery
"People who use X also discovered Y." Better keyboard shortcuts, CLI tools, app alternatives, configuration tweaks. Collective tool intelligence surfaced naturally from usage data.

## Roadmap

### Phase 1: Foundation ✅
Pattern format spec, local pattern miner, Ed25519 crypto (sign/verify), SQLite local cache, content-addressed hashing.

### Phase 2: Network ✅
MQTT hub service, pattern propose/validate/weight lifecycle, Merkle root publishing, bloom filter deduplication, PostgreSQL pattern store, HTTP API, garbage collection.

### Phase 3: Collectors ✅ (current)
Plugin-based collector SDK, developer collector (git/file activity), system collector (macOS app/shell usage). Automatic mining pipeline.

### Phase 4: Privacy & Scale
Differential privacy guarantees. k-anonymity enforcement. Node reputation system. Cross-category pattern discovery.

### Phase 5: Predictive Intelligence
Patterns that predict future states, not just describe past ones. Cross-domain correlations (sleep + code quality, market conditions + productivity). The network becomes anticipatory.

### Future: On-Chain Settlement
Once the network proves value at scale — immutable pattern registry, token incentives, trustless validation. The network needs to work and be useful first.

## Configuration

Default config connects to the public HiveMQ broker with zero setup:

```typescript
import { createNetworkConfig } from '@humebio/hume-network'

// Zero config — uses public broker
const config = createNetworkConfig()

// Or override anything
const config = createNetworkConfig({
  mqtt: {
    url: 'mqtts://your-broker.example.com:8883',
    username: 'your-user',
    password: 'your-pass',
  },
  node: {
    categories: ['developer', 'productivity'],
    autoPropose: true,
    minConfidence: 0.7,
  },
})
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MQTT_URL` | MQTT broker URL | HiveMQ Cloud (built-in) |
| `MQTT_USERNAME` | MQTT username | `humebio` |
| `MQTT_PASSWORD` | MQTT password | built-in |
| `NODE_KEYPAIR_PATH` | Path to Ed25519 keypair | `.hume-network/keypair.json` |
| `NODE_DB_PATH` | SQLite database path | `.hume-network/patterns.db` |
| `NODE_CATEGORIES` | Comma-separated categories | all |
| `NODE_MIN_CONFIDENCE` | Min confidence to propose | `0.5` |
| `HUB_PG_URL` | PostgreSQL URL (hub only) | `postgresql://localhost:5432/hume_network` |

## Get Involved

Hume Network is open source and community-driven. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, branch naming, and PR process.

**Using Hume?** You already have it. The network skill is built-in.

**Using OpenClaw or another compatible agent?** Drop `skills/network/SKILL.md` into your skills directory. Done.

**Building your own collector?** Install `@humebio/collector-sdk` and extend `BaseCollector`.

**Building your own agent?** The pattern format spec is open. Implement the mining interface and your agent becomes a node.

Found a bug or have a feature idea? [Open an issue](https://github.com/humebio/hume-network/issues).

The network gets smarter with every node. You contribute by existing.

## License

[MIT](LICENSE)