@clusteragent/cluster-mcp 1.0.0 → 1.0.2

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.
Files changed (9) hide show
  1. package/README.md +67 -59
  2. package/SKILL.md +85 -123
  3. package/package.json +4 -3
  4. package/skills/crypto-intel/SKILL.md +122 -0
  5. package/skills/finance/SKILL.md +127 -0
  6. package/skills/llm-gateway/SKILL.md +122 -0
  7. package/skills/memory/SKILL.md +136 -0
  8. package/skills/research/SKILL.md +116 -0
  9. package/skills/trading/SKILL.md +137 -0
package/README.md CHANGED
@@ -1,90 +1,98 @@
1
1
  # cluster
2
2
 
3
- **The runtime layer for agentic finance on Robinhood Chain.** Self-hostable index of
4
- AI financial agents — tokenized stocks + crypto, real Uniswap v3 swaps, persistent
5
- memory, and a 24-model LLM gateway in one MCP server.
3
+ <p align="center">
4
+ <a href="https://github.com/clusteragent/cluster"><img src="https://img.shields.io/badge/chain-Robinhood%20%234663-7b5cff.svg?style=flat-square" alt="Chain"></a>
5
+ <a href="https://www.npmjs.com/package/@clusteragent/cluster-mcp"><img src="https://img.shields.io/npm/v/@clusteragent/cluster-mcp.svg?style=flat-square" alt="npm"></a>
6
+ <img src="https://img.shields.io/badge/license-MIT-yellow.svg?style=flat-square" alt="MIT">
7
+ </p>
6
8
 
7
- ```bash
9
+ **The runtime layer for agentic finance on Robinhood Chain.** Self-hostable index
10
+ of AI financial agents — 192 tokenized stocks + native crypto, real Uniswap v3
11
+ swaps (non-custodial), persistent memory, and a 24-model LLM gateway.
12
+
13
+ ```
8
14
  npx @clusteragent/cluster-mcp
9
15
  ```
10
16
 
11
- ## What it does
17
+ ```bash
18
+ npx skills add clusteragent/cluster # any skills-CLI agent
19
+ pip install cluster-agent # Python SDK
20
+ ```
21
+
22
+ ## Repo Layout
12
23
 
13
- | Capability | Tools |
14
- |---|---|
15
- | Live market data — 192 tokenized stocks/ETFs + native crypto (PONS, WETH, USDG, CLIPPY, KARMA, …) | `get_quotes` `get_movers` `get_news` `get_chart` |
16
- | Real swaps on Robinhood Chain (4663) — quoted here, **signed by your wallet** (non-custodial) | `quote_swap` `trade_status` `wallet_balances` |
17
- | Payout basket & distributions — the public record of every $CLST cycle | `get_payout_basket` `get_distributions` |
18
- | Persistent memory per wallet — deduped, recency-scored, survives sessions | `memory_retain` `memory_recall` |
19
- | LLM gateway — 24 models incl. GPT-6 Astra, Claude, GLM; `thinking` mode for deep reasoning | `chat` `get_models` `get_credits` |
20
- | API keys with per-request metering (requests / tokens / USD) | `create_key` `key_usage` |
24
+ ```
25
+ ├── SKILL.md main installer skill (any agent)
26
+ ├── index.mjs MCP server — 17 tools (@clusteragent/cluster-mcp)
27
+ ├── skills/
28
+ │ ├── trading/ quotes, swap lifecycle, receipt proof (4663)
29
+ │ ├── memory/ built-in memory + Hindsight backend
30
+ │ ├── finance/ portfolio, payouts, keys & metering, Maybe fork
31
+ │ ├── crypto-intel/ wallet forensics, pool forensics, scout swarm
32
+ │ ├── research/ Scout/Sifter/Quill/Census + OpenBB integration
33
+ │ └── llm-gateway/ 24 models, thinking mode, credit accounting
34
+ ├── python/ cluster-agent PyPI SDK
35
+ ├── server/ FastAPI backend (self-hostable, SQLite default)
36
+ ├── app/ React/Vite frontend (landing, dashboard, docs)
37
+ ├── bot/ keeper bot (DRY default; --confirm-real-money for live)
38
+ └── docs/self-hosting.md full deployment guide
39
+ ```
21
40
 
22
- ## Install
41
+ ## Quick Start
23
42
 
24
- ### MCP (Claude, Codex, Hermes, OpenClaw, any MCP runtime)
43
+ **Agent users** — see [SKILL.md](./SKILL.md). MCP config:
25
44
 
26
45
  ```json
27
- {
28
- "mcpServers": {
29
- "cluster": {
30
- "command": "npx",
31
- "args": ["-y", "@clusteragent/cluster-mcp"],
32
- "env": {
33
- "CLUSTER_API_URL": "https://your-cluster-host",
34
- "CLUSTER_API_KEY": "clst_...",
35
- "CLUSTER_WALLET": "0x..."
36
- }
37
- }
38
- }
39
- }
46
+ { "mcpServers": { "cluster": {
47
+ "command": "npx", "args": ["-y", "@clusteragent/cluster-mcp"],
48
+ "env": { "CLUSTER_API_URL": "https://your-host", "CLUSTER_API_KEY": "clst_...", "CLUSTER_WALLET": "0x..." }
49
+ }}}
40
50
  ```
41
51
 
42
- ### Skill
43
-
44
- Copy [SKILL.md](./SKILL.md) into your agent's skills directory — it teaches the
45
- agent the full flow: key creation, market data, swap building, receipt proof.
52
+ **Self-hosters** — see [docs/self-hosting.md](./docs/self-hosting.md). Backend +
53
+ frontend + keeper bot, all local, SQLite default, zero external services except
54
+ one LLM key for chat.
46
55
 
47
- ### Self-host the backend
56
+ **Python** — see [python/](./python):
48
57
 
49
- ```bash
50
- git clone https://github.com/clusteragent/cluster
51
- cd cluster/server
52
- cp .env.example .env # set LLM gateway key etc.
53
- pip install -r requirements.txt
54
- uvicorn app.main:app --port 8000
58
+ ```python
59
+ from cluster import Cluster
60
+ c = Cluster(api_url="https://your-host", api_key="clst_...")
61
+ c.quotes(["NVDA", "PONS"]); c.payout_basket(); c.chat("hi", thinking=True)
55
62
  ```
56
63
 
57
- Then point `CLUSTER_API_URL` at it. Market data works out of the box; the LLM
58
- gateway needs your own provider key.
59
-
60
- ## The mechanism
64
+ ## The Mechanism
61
65
 
62
66
  ```
63
67
  fees in ──▶ vault ──▶ keeper bot buys the 19-name basket ──▶ $CLST holders paid pro-rata
64
68
  ```
65
69
 
66
- Every agent action accrues fees. The keeper bot sweeps the payout basket at live
67
- market prices. Holding is the position — no staking, no claiming. Every cycle is
68
- public: `GET /api/distributions`.
69
-
70
- ## The agents
70
+ Holding is the position. Every cycle is public: `GET /api/distributions`.
71
71
 
72
- Sixteen capabilities, each with its own skill pack:
72
+ ## Integrations
73
73
 
74
- **Trading** Relay · Pivot — **Research** Scout · Sifter · Quill — **Analysis** Argus · Prism · Census — **Finance** Ledger · Remit · Margin — **Memory** Memoria · Echo — **Crypto** Nexus · Vault · Oracle
74
+ | Project | Role | Guide |
75
+ |---|---|---|
76
+ | [Hindsight](https://github.com/vectorize-io/hindsight) | learning memory backend (observations, mental models) | `skills/memory/` |
77
+ | [OpenBB](https://github.com/OpenBB-finance/OpenBB) | institutional market data (fundamentals, macro) via MCP/Python | `skills/research/` |
78
+ | [Maybe](https://github.com/maybe-finance/maybe) | self-hosted personal finance UI (AGPLv3 — rename your fork) | `skills/finance/` |
79
+ | [OpenCatz](https://github.com/dizcorvus/opencatz-ai-robinhood-chain) | multi-agent scout swarm pattern on 4663 | `skills/crypto-intel/` |
80
+ | [Uniswap AI](https://github.com/Uniswap/uniswap-ai) | skills architecture this repo follows | structure |
75
81
 
76
- ## Honesty by construction
82
+ ## The Agents
77
83
 
78
- - No fabricated numbers: pre-launch payout data returns honest zeros, never invented rows
79
- - Swaps never touch a private key on our side — the API quotes, your wallet signs
80
- - API keys are stored as SHA-256 hashes and shown exactly once
81
- - A quote is a prediction; the receipt is the proof — parse Transfer logs to see what actually arrived
84
+ **Trading** Relay · Pivot — **Research** Scout · Sifter · Quill — **Analysis** Argus ·
85
+ Prism · Census — **Finance** Ledger · Remit · Margin — **Memory** Memoria · Echo —
86
+ **Crypto** Nexus · Vault · Oracle
82
87
 
83
- ## Chain info
88
+ ## Honesty by Construction
84
89
 
85
- Robinhood Chain · chain id **4663** · Uniswap v3 ·
86
- Router `0xcaf681a6…5cb2` · QuoterV2 `0x33e885ed…a9e7`
90
+ - Pre-launch payout data = honest zeros, never fabricated
91
+ - Swaps: API quotes, your wallet signs — no private keys server-side
92
+ - Keys: SHA-256 at rest, shown once
93
+ - Quote = prediction; receipt = proof (parse the Transfer logs)
87
94
 
88
95
  ## License
89
96
 
90
- MIT
97
+ MIT. Backend and skills are original work. The Maybe Finance fork note applies if
98
+ you self-host that integration (AGPLv3, trademark rules in `skills/finance/`).
package/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: cluster
3
- description: Cluster — self-hostable index of AI financial agents. Trade tokenized stocks and crypto on Robinhood Chain (4663) with real Uniswap v3 swaps, get live quotes for 193 tokenized instruments, read the payout basket, check distribution cycles, use persistent memory per wallet, and chat with 24 LLM models. Use when the user wants tokenized stock or crypto prices, swap execution on Robinhood Chain, portfolio and basket data, agent run logs, persistent memory storage, or an LLM gateway — including agents like Relay (trading), Scout (research), Argus (on-chain analysis), Vault (treasury), and Oracle (price feeds). Supports the full 192-instrument tokenized stock universe plus native crypto (PONS, WETH, USDG, CLIPPY, KARMA and more).
3
+ description: Cluster — the runtime layer for agentic finance on Robinhood Chain. Trade tokenized stocks and crypto on chain 4663 with real Uniswap v3 swaps (client-side signing, non-custodial), get live quotes for 192 tokenized instruments plus native crypto (PONS, WETH, USDG, CLIPPY, KARMA), read the $CLST payout basket and distribution cycles, use persistent per-wallet memory, and reach a 24-model LLM gateway ($5 free credit). Use when the user wants tokenized stock or crypto prices, swap execution, portfolio/basket data, agent runs (Relay, Scout, Argus, Vault, Oracle and 12 more), memory storage, or LLM access. Install sub-skills for trading, memory, finance, crypto-intel, research, and the LLM gateway.
4
4
  metadata:
5
5
  {
6
6
  "clawdbot":
@@ -14,59 +14,36 @@ metadata:
14
14
 
15
15
  # Cluster
16
16
 
17
- The runtime layer for agentic finance on Robinhood Chain. Persistent memory, live
18
- market data over a 193-instrument tokenized stock universe, real Uniswap v3 swaps,
19
- and a 24-model LLM gateway — one skill, every MCP runtime.
17
+ **fees in → basket out.** The runtime layer for agentic finance on Robinhood Chain
18
+ (EVM L2, chain id 4663). One MCP server + six sub-skills. Self-hostable. Non-custodial.
20
19
 
21
- Two ways to run it:
20
+ ## Install
22
21
 
23
- 1. **Hosted API (default)** — no install beyond this skill; point tools at the public
24
- cluster endpoint and authenticate with a cluster API key
25
- 2. **Self-hosted** — run the cluster backend yourself (Docker or bare Node/Python);
26
- all tools work identically against your own deployment
27
-
28
- ## Getting an API Key
29
-
30
- Every wallet gets **$5 of inference credit** on first connect. Two ways:
31
-
32
- **Option A: In-app (recommended)**
33
-
34
- 1. Open the cluster app and connect your wallet
35
- 2. Sign once — a session starts; no more prompts for 60 minutes
36
- 3. Go to **API & Settings → Generate new key**
37
- 4. Copy the key (`clst_<prefix>_<secret>`) — it is shown **exactly once**
38
-
39
- **Option B: Headless (agents)**
22
+ ### Skills CLI (any agent)
40
23
 
41
24
  ```bash
42
- # 1. Get a signing challenge for your wallet
43
- curl "https://YOUR-CLUSTER-HOST/api/auth/challenge?wallet=0xYOUR_ADDRESS"
25
+ npx skills add clusteragent/cluster
26
+ ```
44
27
 
45
- # 2. Sign the message with personal_sign (any EVM signer), then exchange it
46
- curl -X POST "https://YOUR-CLUSTER-HOST/api/auth/session" \
47
- -H "Content-Type: application/json" \
48
- -d '{"wallet":"0xYOUR_ADDRESS","signature":"0xSIGNED_MESSAGE"}'
49
- # → { "session_token": "...", "expires_in": 3600 }
28
+ Or install individual sub-skills:
50
29
 
51
- # 3. Create a key with the session token
52
- curl -X POST "https://YOUR-CLUSTER-HOST/api/keys" \
53
- -H "Content-Type: application/json" \
54
- -d '{"wallet":"0xYOUR_ADDRESS","session_token":"...","name":"my-agent"}'
55
- # → { "key": "clst_...", ... } — store it, it cannot be recovered
30
+ ```bash
31
+ npx skills add clusteragent/cluster --skill trading # swaps + market data
32
+ npx skills add clusteragent/cluster --skill memory # persistent memory
33
+ npx skills add clusteragent/cluster --skill finance # portfolio + ledger
34
+ npx skills add clusteragent/cluster --skill crypto-intel # on-chain intelligence
35
+ npx skills add clusteragent/cluster --skill research # market research agents
36
+ npx skills add clusteragent/cluster --skill llm-gateway # 24-model chat
56
37
  ```
57
38
 
58
- ## Option 1: MCP Server (Recommended)
59
-
60
- ### Install
39
+ ### Claude Code / plugin marketplace
61
40
 
62
41
  ```bash
63
- bunx @clusteragent/cluster-mcp # run directly
64
- # or
65
- npm install -g @clusteragent/cluster-mcp
66
- cluster-mcp # starts the MCP server on stdio
42
+ /plugin marketplace add clusteragent/cluster
43
+ /plugin install cluster-core
67
44
  ```
68
45
 
69
- ### Wire it into your runtime
46
+ ### MCP server (recommended runtime)
70
47
 
71
48
  ```json
72
49
  {
@@ -75,98 +52,69 @@ cluster-mcp # starts the MCP server on stdio
75
52
  "command": "npx",
76
53
  "args": ["-y", "@clusteragent/cluster-mcp"],
77
54
  "env": {
78
- "CLUSTER_API_URL": "https://YOUR-CLUSTER-HOST",
79
- "CLUSTER_API_KEY": "clst_your_key_here"
55
+ "CLUSTER_API_URL": "https://your-cluster-host",
56
+ "CLUSTER_API_KEY": "clst_...",
57
+ "CLUSTER_WALLET": "0x..."
80
58
  }
81
59
  }
82
60
  }
83
61
  }
84
62
  ```
85
63
 
86
- `CLUSTER_API_URL` defaults to the hosted endpoint; set it to your own deployment for
87
- self-hosting. `CLUSTER_API_KEY` is required for wallet-scoped tools (chat, memory,
88
- keys); market data tools work without one.
89
-
90
- ## Option 2: REST API (Direct)
64
+ ### Python SDK
91
65
 
92
- No MCP needed — call the API with curl, fetch, or any HTTP client.
93
-
94
- ### Authentication
66
+ ```bash
67
+ pip install cluster-agent
68
+ ```
95
69
 
96
- Wallet-scoped requests accept either:
70
+ ```python
71
+ from cluster import Cluster
72
+ c = Cluster(api_url="https://your-cluster-host", api_key="clst_...")
97
73
 
98
- - `session_token` — from the sign-once session flow above (60 minutes)
99
- - `X-API-Key: clst_...` — for external callers; usage is metered per request
74
+ c.quotes(["NVDA", "PONS"]) # live quotes + daily closes
75
+ c.payout_basket() # the 19-name basket, weights sum to 100
76
+ c.quote_swap(token="0x...", side="buy", amount_wei=10**16)
77
+ c.chat("Analyze NVDA momentum", model="openai/gpt-6-astra", thinking=True)
78
+ c.memory.retain("User watches semis; largest position NVDA")
79
+ c.memory.recall("NVDA position")
80
+ ```
100
81
 
101
- Market data needs no auth.
82
+ ## Getting an API Key
102
83
 
103
- ### Endpoints Summary
84
+ Every wallet starts with **$5 of inference credit**. The wallet is the account.
104
85
 
105
- | Endpoint | Method | Auth | Description |
106
- |----------|--------|------|-------------|
107
- | `/api/market/quotes?symbols=NVDA,TSLA` | GET | none | Batch quotes + ~1 month of daily closes |
108
- | `/api/market/movers` | GET | none | Gainers, losers, sector heat (192 covered) |
109
- | `/api/market/news` | GET | none | Yahoo Finance headlines |
110
- | `/api/market/chart/{symbol}` | GET | none | Candles + series per timeframe |
111
- | `/api/index` | GET | none | Index composition, on-chain verified count |
112
- | `/api/index/payout-basket` | GET | none | The 19-name payout basket with weights |
113
- | `/api/distributions` | GET | none | Distribution cycles, payroll, treasury |
114
- | `/api/trade/quote` | GET | none | Uniswap v3 quote (token, side, amount in wei, via) |
115
- | `/api/trade/status` | GET | none | Router, quoter, gas, ETH price |
116
- | `/api/trade/wallet/{address}` | GET | none | On-chain balances: native ETH + all holdings |
117
- | `/api/chat` | POST | wallet/key | One completion — 24 models, `thinking` flag for extended reasoning |
118
- | `/api/chat/models` | GET | none | Model list with context windows and pricing |
119
- | `/api/chat/credits` | GET | none | Credit balance for a wallet |
120
- | `/api/memory/retain` | POST | wallet/key | Store a durable memory note (deduped) |
121
- | `/api/memory/recall` | POST | wallet/key | Semantic-ish recall of stored notes |
122
- | `/api/keys` | GET/POST | wallet/key | List / create API keys |
123
- | `/api/keys/usage` | GET | wallet/key | Metered usage: requests, tokens, USD |
86
+ **In-app:** connect wallet → sign once → **API & Settings → Generate new key** →
87
+ copy `clst_...` (shown exactly once, stored as SHA-256).
124
88
 
125
- ### Quick Examples
89
+ **Headless:**
126
90
 
127
91
  ```bash
128
- # Live quotes
129
- curl "https://YOUR-CLUSTER-HOST/api/market/quotes?symbols=NVDA,SPY,PONS"
130
-
131
- # The payout basket — 19 instruments, weights sum to 100
132
- curl "https://YOUR-CLUSTER-HOST/api/index/payout-basket"
133
-
134
- # Quote a swap: 0.01 ETH → NVDA (amount in wei)
135
- curl "https://YOUR-CLUSTER-HOST/api/trade/quote?token=0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC&side=buy&amount=10000000000000000"
136
-
137
- # Chat with extended reasoning
138
- curl -X POST "https://YOUR-CLUSTER-HOST/api/chat" \
92
+ # 1. challenge
93
+ curl "https://HOST/api/auth/challenge?wallet=0xYOUR_ADDRESS"
94
+ # 2. sign the message (personal_sign), exchange for a 60-minute session
95
+ curl -X POST "https://HOST/api/auth/session" \
96
+ -H "Content-Type: application/json" \
97
+ -d '{"wallet":"0xYOUR_ADDRESS","signature":"0xSIGNED"}'
98
+ # 3. mint a key
99
+ curl -X POST "https://HOST/api/keys" \
139
100
  -H "Content-Type: application/json" \
140
- -d '{"wallet":"0xYOUR_ADDRESS","model":"openai/gpt-6-astra","thinking":true,"messages":[{"role":"user","content":"Analyze NVDA momentum"}]}'
101
+ -d '{"wallet":"0xYOUR_ADDRESS","session_token":"...","name":"my-agent"}'
141
102
  ```
142
103
 
143
- ### Executing Swaps (client-side, non-custodial)
144
-
145
- Cluster never touches a private key. The API quotes and builds calldata; **your
146
- wallet signs and broadcasts**:
147
-
148
- 1. `GET /api/trade/quote` — get the best route + `amountOut`
149
- 2. Build the tx: buy = `multicall([exactInput, refundETH])` with `msg.value`;
150
- sell = approve the router, then `multicall([exactInput, unwrapWETH9])`
151
- 3. Sign with your own signer (wagmi, ethers, viem) and broadcast
152
- 4. Poll `eth_getTransactionReceipt` — parse Transfer logs to confirm what actually
153
- arrived (a quote is a prediction; a receipt is proof)
154
-
155
- Key addresses on Robinhood Chain (4663):
104
+ ## Tool Map
156
105
 
157
- | Contract | Address |
158
- |----------|---------|
159
- | SwapRouter02 | `0xcaf681a66d020601342297493863e78c959e5cb2` |
160
- | QuoterV2 | `0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7` |
161
- | WETH | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` |
162
- | USDG | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` |
106
+ | Domain | MCP tools | Sub-skill |
107
+ |---|---|---|
108
+ | Market data (192 stocks + crypto) | `get_quotes` `get_movers` `get_news` `get_chart` | trading |
109
+ | Swaps on 4663 (non-custodial) | `quote_swap` `trade_status` `wallet_balances` | trading |
110
+ | $CLST payouts | `get_payout_basket` `get_distributions` | finance |
111
+ | Memory (built-in + Hindsight backend) | `memory_retain` `memory_recall` | memory |
112
+ | LLM gateway (24 models, thinking mode) | `chat` `get_models` `get_credits` | llm-gateway |
113
+ | API keys & metering | `create_key` `key_usage` | finance |
114
+ | Agents (16 capabilities) | REST `/api/agents`, `/api/runs` | research |
163
115
 
164
116
  ## The Agents
165
117
 
166
- Sixteen agent capabilities, each with its own skill pack. Running one logs the
167
- interaction to your wallet's history; after the $CLST token launch, fees from agent
168
- work stream to holders through the payout basket.
169
-
170
118
  | Agent | Ticker | Category | Trigger |
171
119
  |-------|--------|----------|---------|
172
120
  | Relay | RLY | Trading | Per swap |
@@ -186,17 +134,31 @@ work stream to holders through the payout basket.
186
134
  | Oracle | ORC | Crypto | Per query |
187
135
  | Margin | MRG | Finance | Per task |
188
136
 
189
- ## The Payout Mechanism
137
+ ## The Mechanism
138
+
139
+ ```
140
+ fees in ──▶ vault ──▶ keeper bot buys the 19-name basket ──▶ $CLST holders paid pro-rata
141
+ ```
142
+
143
+ Holding is the position — no staking, no claiming. Every cycle is public:
144
+ `GET /api/distributions`.
145
+
146
+ ## Honesty by Construction
147
+
148
+ - Pre-launch payout data returns honest zeros — never fabricated rows
149
+ - Swaps never touch a private key on our side; the API quotes, your wallet signs
150
+ - API keys stored as SHA-256, shown exactly once
151
+ - A quote is a prediction; the receipt is the proof — parse Transfer logs to confirm
152
+ what actually arrived
153
+
154
+ ## Chain Reference
190
155
 
191
- Fees in → basket out. Every agent action accrues fees in the vault; the keeper bot
192
- sweeps the **19-name payout basket** at live market prices; $CLST holders are paid
193
- pro-rata every cycle. No staking, no claiming — holding is the position. All
194
- distribution data is public: `GET /api/distributions` returns every cycle, per
195
- address, from the first one onward.
156
+ Robinhood Chain · **4663** · Uniswap v3 ·
157
+ Router `0xcaf681a6…5cb2` · QuoterV2 `0x33e885ed…a9e7` ·
158
+ WETH `0x0Bd7…AD73` · USDG `0x5fc5…d168`
196
159
 
197
- ## Rate Limits & Credits
160
+ ## Credits & Limits
198
161
 
199
- - Chat: 30 requests/minute per wallet
200
- - Every wallet starts with **$5 of inference credit** — metered per token, per model
201
- - API key calls are metered the same way and visible in realtime under `/api/keys/usage`
202
- - Top-ups are not open yet; credit is the only gate
162
+ - Chat: 30 req/min per wallet
163
+ - $5 inference credit per wallet, metered per token per model
164
+ - Top-ups not open yet
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@clusteragent/cluster-mcp",
3
- "version": "1.0.0",
4
- "description": "Cluster MCP \u2014 self-hostable index of AI financial agents. Tokenized stocks + crypto on Robinhood Chain, persistent memory, 24-model LLM gateway.",
3
+ "version": "1.0.2",
4
+ "description": "Cluster MCP + skills \u2014 self-hostable index of AI financial agents. Tokenized stocks + crypto on Robinhood Chain, persistent memory, 24-model LLM gateway.",
5
5
  "main": "index.mjs",
6
6
  "bin": {
7
7
  "cluster-mcp": "index.mjs"
@@ -10,7 +10,8 @@
10
10
  "files": [
11
11
  "index.mjs",
12
12
  "SKILL.md",
13
- "README.md"
13
+ "README.md",
14
+ "skills"
14
15
  ],
15
16
  "keywords": [
16
17
  "mcp",
package/skills/crypto-intel/SKILL.md ADDED
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: crypto-intel
3
+ description: On-chain crypto intelligence on Robinhood Chain (4663). Use when the user wants wallet analysis (balances, positions, concentration), whale watching and flow analysis (Argus), live DEX token data for native tokens (PONS, SWOGE, RHAGENT, NOXA, CLIPPY, KARMA and the pons-ecosystem), liquidity and pool discovery via DexScreener, token verification against the canonical factory, or autonomous multi-agent scouting coordination. Covers the Argus (analysis), Nexus (portfolio), Oracle (price feeds), and Vault (treasury) agent workflows.
4
+ allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(python:*)
5
+ license: MIT
6
+ metadata:
7
+ author: clusteragent
8
+ version: "1.0.0"
9
+ ---
10
+
11
+ # Crypto Intelligence — Robinhood Chain
12
+
13
+ On-chain truth for chain 4663. Every claim below is verifiable against the
14
+ explorer: https://robinhoodchain.blockscout.com
15
+
16
+ ## Wallet Analysis
17
+
18
+ ```bash
19
+ # Full balance sheet — native ETH + every held token, one call
20
+ curl "https://HOST/api/trade/wallet/0xADDRESS"
21
+ ```
22
+
23
+ - Values are raw on-chain reads via **Multicall3** (`0xcA11…CA11`, live on 4663) —
24
+ one round-trip reads ETH + all token balances
25
+ - Report: total USD (× ETH price from `/api/trade/status`), per-token breakdown,
26
+ concentration warnings (any single token > 40% = flag it)
27
+
28
+ ## Token Universe
29
+
30
+ **Canonical V3 factory** (swap-able via SwapRouter02):
31
+
32
+ ```
33
+ PONS 0x39dBED3a2bd333467115dE45665cC57F813C4571 liq ~$6.6M, pool 0x10cc…26ba
34
+ CLIPPY 0x85856f025bf13b8fd2aae2f6da458318744f1e18
35
+ KARMA 0xb47f4702deb124cb4eb6286be83c9d84277c6239
36
+ WETH 0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
37
+ USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168
38
+ ```
39
+
40
+ **Pons launchpad factory** (`0x1f7d7550…` — separate Uniswap V3 factory; not
41
+ routable by SwapRouter02, QuoterV2 reverts):
42
+
43
+ ```
44
+ FINCH 0x879f29204a5ff842c66f0f65e0f2e422073acce7
45
+ SWOGE 0xdb87393727b666c43f5aecb03d8b419ba54d9b03
46
+ RHAGENT 0x894fac757250f8e02180e1856957274d84ac4ba3
47
+ NOXA 0x39e0d9057bd9039cd14590f54de20b9d3457c56e
48
+ PONSTR 0x4a76d884bb9cbbf2138fbe47e99584eb5168dde2
49
+ ARENA 0x14dad3f05f7e25ee79b780119db96baa6b30e7c0
50
+ IF 0x232cdfc415d10b673845d83dc02ba2eabe7e30d1
51
+ BUTTER 0xcdd50d73b45085d71cb05e2ca238d12c3bd7bebd
52
+ WALLET 0x0339f5459fc690ac85f1782e15782a151b4a9e1b
53
+ SQUEEZE 0xf444f3c77c77a33f7c8d8fcab8a1e88afb843da5
54
+ ```
55
+
56
+ Verify a pool's factory yourself:
57
+
58
+ ```bash
59
+ # factory() on the pool address — compare against the canonical factory
60
+ cast call 0xPOOL_ADDRESS "factory()(address)" --rpc-url https://rpc.mainnet.chain.robinhood.com
61
+ ```
62
+
63
+ ## Live DEX Data (DexScreener)
64
+
65
+ ```bash
66
+ # One call, up to 30 token addresses — returns every robinhood-chain pair
67
+ curl "https://api.dexscreener.com/latest/dex/tokens/0x39dBED…4571,0x8585…1e18"
68
+ ```
69
+
70
+ - Filter `chainId == "robinhood"`, sort by `liquidity.usd` for the deepest pool
71
+ - `priceUsd` is valid **when your token is the base side**; when it's the quote
72
+ side the price refers to the other token
73
+ - `volume.h24`, `txns` (buys/sells) and `priceChange.h24` give momentum context
74
+
75
+ ## Pool Forensics
76
+
77
+ For any V3 pool, read on-chain (no indexer needed):
78
+
79
+ ```bash
80
+ # slot0 → sqrtPriceX96 (spot), tick
81
+ cast call 0xPOOL "slot0()(uint160,int24,uint16,uint16,uint16,uint8,bool)" \
82
+ --rpc-url https://rpc.mainnet.chain.robinhood.com
83
+ # fee tier + liquidity
84
+ cast call 0xPOOL "fee()(uint24)" --rpc-url https://rpc.mainnet.chain.robinhood.com
85
+ cast call 0xPOOL "liquidity()(uint128)" --rpc-url https://rpc.mainnet.chain.robinhood.com
86
+ cast call 0xPOOL "factory()(address)" --rpc-url https://rpc.mainnet.chain.robinhood.com
87
+ ```
88
+
89
+ Spot price from `sqrtPriceX96`: `price = (sqrtPriceX96 / 2^96)^2` (token1 per
90
+ token0, raw decimals — adjust). If `price` is implausible vs DexScreener, the pool
91
+ is likely a launchpad-factory pool with non-standard math — flag it.
92
+
93
+ ## The Intelligence Agents
94
+
95
+ | Agent | Role | Workflow |
96
+ |---|---|---|
97
+ | **Argus** (ARG) | On-chain flows | Wallet forensics, whale movement, transfer watching via `/api/trade/wallet` + Blockscout |
98
+ | **Nexus** (NXS) | Portfolio | Cross-token positions + yield view from the wallet balance sheet |
99
+ | **Oracle** (ORC) | Price feeds | Quote-cache from `/api/market/quotes` + DexScreener; every feed call is metered |
100
+ | **Vault** (VLT) | Treasury | `distributions.treasury.eth` monitoring, accumulation reporting |
101
+
102
+ ## Scout Swarm Pattern (OpenCatz-style)
103
+
104
+ Multi-agent monitoring with a consensus gate — N scouts each watch one domain and
105
+ report, an 80%-confidence gate blocks low-conviction calls:
106
+
107
+ 1. **DEX scout** — new pools / liq changes via DexScreener polling (30s)
108
+ 2. **Whale scout** — large transfers via Blockscout address tx feeds
109
+ 3. **Price scout** — deviation alerts: |quote − spot| > threshold
110
+ 4. **Risk scout** — concentration + drawdown checks per wallet
111
+ 5. **Feed scout** — Yahoo news crosses (`/api/market/news`)
112
+
113
+ Each scout writes findings to `memory_retain` tagged `scout:<domain>`. A
114
+ coordinator agent recalls them (`memory_recall`) and only acts when ≥80% of
115
+ relevant scouts agree. This is the same shape as OpenCatz's swarm protocol,
116
+ implemented entirely with cluster primitives.
117
+
118
+ ## Blockscout Notes
119
+
120
+ The Blockscout UI sits behind Cloudflare bot protection — API scraping with plain
121
+ curl gets 403. Prefer: raw RPC (`eth_call`) for everything state-based, DexScreener
122
+ for pricing, and the cluster API (which caches) for aggregates.
package/skills/finance/SKILL.md ADDED
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: finance
3
+ description: Portfolio, ledger and payout finance operations for cluster. Use when the user wants their portfolio value and holdings, the $CLST payout basket composition and weights, distribution cycles and history (who got paid, when, how much), treasury status, API key management with usage metering (requests/tokens/USD), or double-entry style bookkeeping of agent activity. Covers the ledger agent (Ledger/FIN), payments agent (Remit/RMT), risk agent (Margin/MRG), and treasury agent (Vault/VLT) workflows.
4
+ allowed-tools: Read, Write, Edit, Bash(curl:*)
5
+ license: MIT
6
+ metadata:
7
+ author: clusteragent
8
+ version: "1.0.0"
9
+ ---
10
+
11
+ # Cluster Finance
12
+
13
+ Portfolio truth, payout records, and metering. Every number here is either read
14
+ on-chain or from the public keeper-bot feed — never fabricated. Pre-launch payout
15
+ data returns honest zeros by design.
16
+
17
+ ## Portfolio
18
+
19
+ ```bash
20
+ # Portfolio + history (wallet-scoped, auth required)
21
+ curl "https://HOST/api/portfolio?wallet=0xUSER&session_token=…"
22
+ curl "https://HOST/api/portfolio/history?wallet=0xUSER&session_token=…"
23
+ ```
24
+
25
+ - The real "position" is the wallet's **$CLST token balance**, read on-chain
26
+ (`AGENTINDEX_CLST_TOKEN_ADDRESS` / `AGENTINDEX_CLST_TOKEN_ADDRESS` env on the server)
27
+ - Before $CLST deploys, portfolio is honest zeros with a note — no invented rows
28
+ - On-chain balances for any address, no auth needed:
29
+
30
+ ```bash
31
+ curl "https://HOST/api/trade/wallet/0xADDRESS"
32
+ # → native ETH + every held token, raw values from Multicall3.aggregate
33
+ ```
34
+
35
+ ## The Payout Basket
36
+
37
+ 19 curated instruments, weights sum to 100. The keeper bot buys this basket from
38
+ accumulated fees at live market prices.
39
+
40
+ ```bash
41
+ curl "https://HOST/api/index/payout-basket"
42
+ ```
43
+
44
+ ```json
45
+ { "count": 19, "weight_sum": 100.0, "universe_count": 193,
46
+ "note": "Holders are paid from this curated basket. The full 193-instrument
47
+ universe is tradeable; the basket is the payout vehicle." }
48
+ ```
49
+
50
+ 19 payout names vs **193 tradeable instruments** — different things, keep them
51
+ distinct when answering users.
52
+
53
+ ## Distributions — the public record
54
+
55
+ ```bash
56
+ curl "https://HOST/api/distributions"
57
+ ```
58
+
59
+ ```json
60
+ { "live": true, "mode": "dry",
61
+ "totals": { "cycles": 0, "distributed_usd": 0.0, "recipients": 0 },
62
+ "treasury": { "address": "0xcdfc…8827", "eth": 0.004169 },
63
+ "cycles": [], "payroll": [], "recent_buys": [] }
64
+ ```
65
+
66
+ - `mode: "dry"` = keeper bot running without settling; `live` = real cycles
67
+ - `payroll` = holder leaderboard (ranked by payout, from cycle 1 onward)
68
+ - `recent_buys` = every keeper basket purchase with tx
69
+ - `treasury.eth` = live vault balance, refreshed ~60s
70
+
71
+ ## API Keys & Metering
72
+
73
+ ```bash
74
+ # create (raw key shown ONCE — SHA-256 stored)
75
+ curl -X POST "https://HOST/api/keys" -H "Content-Type: application/json" \
76
+ -d '{"wallet":"0xUSER","session_token":"…","name":"prod"}'
77
+
78
+ # list
79
+ curl "https://HOST/api/keys?wallet=0xUSER&session_token=…"
80
+
81
+ # usage: requests, tokens, USD per key
82
+ curl "https://HOST/api/keys/usage?wallet=0xUSER&session_token=…"
83
+ ```
84
+
85
+ Limits: 20 active keys per wallet. Keys are wallet-bound — a key can never touch
86
+ another wallet's data.
87
+
88
+ ## Credit Accounting
89
+
90
+ Every wallet gets **$5 inference credit**. Chat requests reserve worst-case cost
91
+ up front, then true-up from actual token usage — two concurrent requests cannot
92
+ double-spend the remainder. Rate limit: 30 chat requests/minute.
93
+
94
+ ```bash
95
+ curl "https://HOST/api/chat/credits?wallet=0xUSER"
96
+ # → { "granted_usd": 5.0, "used_usd": 0.0, "remaining_usd": 5.0 }
97
+ ```
98
+
99
+ ## The Finance Agents
100
+
101
+ | Agent | Role | Workflow |
102
+ |---|---|---|
103
+ | **Ledger** (FIN) | Bookkeeping & reconciliation | Log every agent interaction to the wallet history; settle in $CLST post-launch |
104
+ | **Remit** (RMT) | Payments & invoicing | Record tip intents between wallets (`POST /api/social/tip`, self-tip blocked, 0x-address validated) |
105
+ | **Margin** (MRG) | Risk & margin | Track exposure across holdings (`/api/trade/wallet`), flag concentration, keep books balanced |
106
+ | **Vault** (VLT) | Treasury | Monitor `distributions.treasury.eth`, report vault accumulation, compound idle balances post-launch |
107
+
108
+ ## Maybe Finance (self-hosted personal finance UI)
109
+
110
+ For a full double-entry personal finance UI on top of cluster data, self-host
111
+ [Maybe](https://github.com/maybe-finance/maybe) (AGPLv3, unmaintained upstream —
112
+ fork under the license terms: keep the LICENSE, state the fork is not affiliated
113
+ with Maybe Finance Inc., do not use the "Maybe" trademark or logo):
114
+
115
+ ```bash
116
+ git clone https://github.com/maybe-finance/maybe
117
+ cd maybe
118
+ # Docker self-host
119
+ docker compose up -d
120
+ ```
121
+
122
+ Maybe's account/transaction model maps well: cluster wallet = Maybe "account",
123
+ keeper-bot distributions = "transactions", the payout basket = an investment
124
+ "portfolio". Pull cluster data into it via the REST API.
125
+
126
+ > Trademark note: rename the deployment (e.g. "Cluster Ledger") in any user-facing
127
+ > surface.
package/skills/llm-gateway/SKILL.md ADDED
@@ -0,0 +1,122 @@
1
+ ---
2
+ name: llm-gateway
3
+ description: The cluster LLM gateway — 24 models with per-token metering against a $5 free credit. Use when the user wants to chat with or route work to specific models (GPT-6 Astra, the model 4, GPT-5.6 Terra, Kimi K3, DeepSeek V4 Pro, Qwen, GLM, MiniMax, Gemini), enable extended thinking/reasoning for hard problems, pick the cheapest model for a task, check remaining credit, or integrate completions programmatically via REST or the Python SDK.
4
+ allowed-tools: Read, Bash(curl:*), Bash(pip:*)
5
+ license: MIT
6
+ metadata:
7
+ author: clusteragent
8
+ version: "1.0.0"
9
+ ---
10
+
11
+ # Cluster LLM Gateway
12
+
13
+ 24 models, one endpoint, metered per token against the wallet's credit ($5 free).
14
+ Same shape as [OI] — swap the base URL and key.
15
+
16
+ ## Models
17
+
18
+ ```bash
19
+ curl "https://HOST/api/chat/models"
20
+ ```
21
+
22
+ ```
23
+ → { "models": [
24
+ { "id": "openai/gpt-6-astra", "label": "GPT-6 Astra", "group": "Frontier", "context": 400000 },
25
+ { "id": "anthropic/…", "label": "the model 4", "group": "Reasoning", … },
26
+ { "id": "openai/gpt-5.6-terra", "label": "GPT-5.6 Terra", "group": "Frontier", … },
27
+ { "id": "google/gemini-3.8-flash","label": "Gemini 3.8 Flash", "group": "Fast", … },
28
+ { "id": "deepseek/deepseek-v4-pro","label": "DeepSeek V4 Pro", "group": "Reasoning", … },
29
+ { "id": "moonshot/kimi-k3", "label": "Kimi K3", … },
30
+ { "id": "glm/glm-5.3-flash", "label": "GLM 5.3 Flash", … }, # cheapest
31
+ … 24 total
32
+ ]}
33
+ ```
34
+
35
+ Pricing is USD per 1M tokens (in / out) — included in the models response. Pick
36
+ the cheapest model that handles the task; reserve Frontier models + `thinking`
37
+ for genuinely hard problems.
38
+
39
+ ## Chat
40
+
41
+ ```bash
42
+ curl -X POST "https://HOST/api/chat" \
43
+ -H "Content-Type: application/json" \
44
+ -d '{
45
+ "wallet": "0xUSER",
46
+ "model": "openai/gpt-6-astra",
47
+ "thinking": true,
48
+ "messages": [{"role":"user","content":"Analyze NVDA momentum for a swing entry"}]
49
+ }'
50
+ ```
51
+
52
+ Response:
53
+
54
+ ```json
55
+ { "reply": "…",
56
+ "model": "openai/gpt-6-astra",
57
+ "usage": { "prompt_tokens": 812, "completion_tokens": 640, "cost_usd": 0.0041 },
58
+ "credit": { "remaining_usd": 4.9959 } }
59
+ ```
60
+
61
+ ## Thinking Mode
62
+
63
+ `"thinking": true` inserts a rigor directive and doubles the token budget — the
64
+ model works step-by-step, considers multiple approaches, self-checks before
65
+ answering. Use for: valuation, route analysis, multi-constraint decisions, code
66
+ that touches money. Skip for lookups and rewrites (2× cost, no benefit).
67
+
68
+ Auth: either a fresh wallet signature / 60-minute session token, or an API key
69
+ (`clst_...`) via the `api_key` field for external callers. Rate limit 30/min.
70
+
71
+ ## Credits
72
+
73
+ ```bash
74
+ curl "https://HOST/api/chat/credits?wallet=0xUSER"
75
+ ```
76
+
77
+ Reserve-then-true-up accounting: worst-case cost is committed before the gateway
78
+ call so concurrent requests can't overdraw; actual usage reconciles after.
79
+ Top-ups not open yet — the $5 grant is the only credit source.
80
+
81
+ ## Python SDK
82
+
83
+ ```bash
84
+ pip install cluster-agent
85
+ ```
86
+
87
+ ```python
88
+ from cluster import Cluster
89
+ c = Cluster(api_url="https://HOST", api_key="clst_...")
90
+
91
+ r = c.chat(
92
+ "Draft a one-page thesis on the PONS ecosystem",
93
+ model="anthropic/…",
94
+ thinking=True,
95
+ )
96
+ print(r["reply"], r["usage"]["cost_usd"])
97
+ ```
98
+
99
+ ## Conversation Memory
100
+
101
+ Pass `conversation_id` to group turns server-side (each project = one id):
102
+
103
+ ```json
104
+ { "wallet": "0x…", "conversation_id": "proj-1734", "messages": [...] }
105
+ ```
106
+
107
+ Grouped turns are queryable via `GET /api/chat/conversations?wallet=…`
108
+ (wallet-authenticated — titles are derived from user content, so it's private).
109
+ For cross-session *knowledge* (not just transcripts), use the memory skill's
110
+ `memory_retain` / `memory_recall` — or the Hindsight backend for learning memory.
111
+
112
+ ## Model Selection Guide
113
+
114
+ | Task | Model class |
115
+ |---|---|
116
+ | Quick lookups, formatting, rewrites | `glm/glm-5.3-flash` (cheapest) |
117
+ | Code, structured extraction | Terra / Kimi class |
118
+ | Financial analysis, multi-step reasoning | Frontier + `thinking: true` |
119
+ | Long documents (100k+) | models with 400k context |
120
+
121
+ Metering is per-token against the *wallet* — the same credit powers chat in the
122
+ app, MCP tool calls, and API-key integrations.
package/skills/memory/SKILL.md ADDED
@@ -0,0 +1,136 @@
1
+ ---
2
+ name: memory
3
+ description: Persistent memory for cluster agents. Use when the user wants the agent to remember something across sessions (watchlists, positions, research findings, preferences), recall what was stored before, or set up a dedicated memory backend (Hindsight for learning-over-time memory with observations and mental models). Covers the built-in cluster memory API (retain/recall, deduped, recency-scored, per-wallet banks) and the Hindsight integration for production-grade memory.
4
+ allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(docker:*), Bash(pip:*)
5
+ license: MIT
6
+ metadata:
7
+ author: clusteragent
8
+ version: "1.0.0"
9
+ ---
10
+
11
+ # Cluster Memory
12
+
13
+ Two tiers:
14
+
15
+ 1. **Built-in memory** — zero-setup, part of every cluster deployment. Notes are
16
+ deduped (identical content skipped), scored by recency decay, and stored per
17
+ wallet/bank. Backs the `memory_retain` / `memory_recall` MCP tools.
18
+ 2. **Hindsight backend** — production memory that *learns*: observations, mental
19
+ models, knowledge pages. Self-hosted via Docker, or Hindsight Cloud.
20
+
21
+ ## Built-in Memory (default)
22
+
23
+ ### Retain
24
+
25
+ ```bash
26
+ curl -X POST "https://HOST/api/memory/retain" \
27
+ -H "Content-Type: application/json" \
28
+ -d '{
29
+ "bank_id": "0xUSER_WALLET",
30
+ "content": "User watches semiconductors; largest position NVDA, entry ~$210",
31
+ "title": "Portfolio focus",
32
+ "tags": ["portfolio", "semis"],
33
+ "session_token": "…"
34
+ }'
35
+ ```
36
+
37
+ - `content` max **4000 chars** — a memory is a fact, not a document
38
+ - Duplicate content (normalized) is **skipped** unless `force: true`
39
+ - `bank_id` is the wallet address by default — memories are per-wallet private
40
+ (wallet-scoped auth required)
41
+
42
+ ### Recall
43
+
44
+ ```bash
45
+ curl -X POST "https://HOST/api/memory/recall" \
46
+ -H "Content-Type: application/json" \
47
+ -d '{"bank_id":"0xUSER_WALLET","query":"what does the user hold?","limit":10}'
48
+ ```
49
+
50
+ Results are scored by recency decay — newest relevant facts win. Use recall
51
+ **before** acting on portfolio or preference questions; never ask the user for
52
+ something they already told the agent.
53
+
54
+ ### What to store (and what not)
55
+
56
+ Store: watchlists, position notes, risk preferences, research conclusions, key
57
+ decisions ("user prefers limit orders"), recurring instructions.
58
+
59
+ Do not store: raw market snapshots (re-fetch — they rot), secrets (keys never
60
+ belong in memory), anything the user asked to forget — delete the bank instead.
61
+
62
+ ## Hindsight Backend (learning memory)
63
+
64
+ Cluster's memory layer is pluggable — set `MEMORY_BACKEND=hindsight` on the server
65
+ and point it at a Hindsight instance. Hindsight does not just recall conversation;
66
+ it extracts **observations** and compiles them into **mental models** so agents get
67
+ smarter over time. LongMemEval SOTA benchmark holder.
68
+
69
+ ### Start a server
70
+
71
+ ```bash
72
+ docker run -it --pull always --name hindsight --restart unless-stopped \
73
+ -p 8888:8888 -p 9999:9999 \
74
+ -e HINDSIGHT_API_LLM_PROVIDER=openai \
75
+ -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
76
+ -v hindsight-data:/home/hindsight/.pg0 \
77
+ ghcr.io/vectorize-io/hindsight:latest
78
+ ```
79
+
80
+ API on `:8888`, UI on `:9999`. Works with 25+ LLM providers (OpenAI, Anthropic,
81
+ Gemini, DeepSeek, Ollama/local, [OI]-compatible endpoints, and subscription-backed
82
+ providers like `openai-codex` / `claude-code` / `github-copilot` — no API key needed
83
+ for those).
84
+
85
+ Bare metal: `pip install hindsight-api`. Managed: Hindsight Cloud
86
+ (`https://api.hindsight.vectorize.io`).
87
+
88
+ ### Wire cluster to it
89
+
90
+ ```bash
91
+ # in the cluster backend .env
92
+ MEMORY_BACKEND=hindsight
93
+ HINDSIGHT_URL=http://localhost:8888
94
+ HINDSIGHT_TENANT=cluster
95
+ ```
96
+
97
+ With this set, `/api/memory/retain` and `/api/memory/recall` transparently route
98
+ through Hindsight — same tools, smarter memory. Without it, the SQLite fallback
99
+ runs (zero external services, fine for a single-process self-host).
100
+
101
+ ### Direct Hindsight usage (agents)
102
+
103
+ ```bash
104
+ pip install hindsight-client
105
+ ```
106
+
107
+ ```python
108
+ from hindsight_client import Hindsight
109
+
110
+ memory = Hindsight(base_url="http://localhost:8888")
111
+
112
+ memory.retain(bank_id="0xUSER", items=[
113
+ {"content": "User sold half the PONS position after the +20% run"},
114
+ ])
115
+
116
+ results = memory.recall(bank_id="0xUSER", query="PONS position history")
117
+ ```
118
+
119
+ ### MCP
120
+
121
+ Hindsight ships its own MCP server — run it alongside cluster's for native memory
122
+ tools in any MCP runtime:
123
+
124
+ ```json
125
+ { "mcpServers": { "hindsight": {
126
+ "command": "npx", "args": ["-y", "@vectorize-io/hindsight-mcp"],
127
+ "env": { "HINDSIGHT_BASE_URL": "http://localhost:8888" }
128
+ }}}
129
+ ```
130
+
131
+ ## Choosing
132
+
133
+ | Need | Use |
134
+ |---|---|
135
+ | Quick facts, single-process self-host, zero deps | Built-in (SQLite) |
136
+ | Agent should *learn* (observations, mental models), production, multi-agent | Hindsight |
package/skills/research/SKILL.md ADDED
@@ -0,0 +1,116 @@
1
+ ---
2
+ name: research
3
+ description: Market research and analysis workflows for cluster agents. Use when the user wants a commissioned research report (Scout), literature/source sifting (Sifter), writing and synthesis (Quill), dataset-to-signal analysis (Prism), market census and ranking (Census), or financial data integration via OpenBB (equities fundamentals, historical prices, econ data). Covers the research agent roster, report structure, the OpenBB Python integration for institutional-grade data, and how research findings persist to cluster memory.
4
+ allowed-tools: Read, Write, Edit, Bash(curl:*), Bash(pip:*), Bash(python:*)
5
+ license: MIT
6
+ metadata:
7
+ author: clusteragent
8
+ version: "1.0.0"
9
+ ---
10
+
11
+ # Cluster Research
12
+
13
+ Four research agents, one data platform. Research findings persist to cluster
14
+ memory so reports compound — session N cites session N−1.
15
+
16
+ ## The Research Roster
17
+
18
+ | Agent | Ticker | Craft |
19
+ |---|---|---|
20
+ | **Scout** (SCT) | Deep research | Commissioned reports: thesis, evidence, risk, verdict |
21
+ | **Sifter** (SFT) | Source sifting | Evidence-grade filtering: primary sources, cross-checking, bias flags |
22
+ | **Quill** (QLL) | Writing | Briefs, memos, summaries — synthesis of stored findings |
23
+ | **Census** (CNS) | Market census | Count, segment, rank any market (e.g. "all RWA chains by TVL") |
24
+
25
+ **Prism** (PRSM, Analysis) breaks any dataset into signals — pairs with Census for
26
+ market structure work.
27
+
28
+ ## The Report Format (Scout)
29
+
30
+ ```
31
+ # <Question as title>
32
+ **Verdict:** <one sentence, up front>
33
+ **Confidence:** high | medium | low — and WHY
34
+
35
+ ## Findings
36
+ - fact 1 (source, date)
37
+ - fact 2 (source, date)
38
+ …
39
+
40
+ ## Counter-evidence
41
+ - what would falsify this thesis
42
+
43
+ ## Sources
44
+ - [1] …
45
+ ```
46
+
47
+ Rules: verdict first, every fact carries a source and date, counter-evidence is
48
+ mandatory, no unsourced claims. After delivery, persist the conclusion:
49
+
50
+ ```bash
51
+ curl -X POST "https://HOST/api/memory/retain" \
52
+ -H "Content-Type: application/json" \
53
+ -d '{"bank_id":"0xUSER","content":"Scout 2026-09: NVDA momentum positive — supply constraints ease Q4, consensus at $240. Confidence: medium.","tags":["research","NVDA"],"session_token":"…"}'
54
+ ```
55
+
56
+ ## Market Data Workflows (cluster API)
57
+
58
+ ```bash
59
+ curl "https://HOST/api/market/quotes?symbols=NVDA,AMD,MU" # price + 1mo closes
60
+ curl "https://HOST/api/market/news?limit=12" # headlines
61
+ curl "https://HOST/api/market/sectors" # sector heat
62
+ curl "https://HOST/api/market/movers?limit=10" # flow of the day
63
+ ```
64
+
65
+ Use these for market *state*; use OpenBB below for fundamentals, options and
66
+ macro. Cite which system each number came from.
67
+
68
+ ## OpenBB — institutional data platform
69
+
70
+ [OpenBB](https://github.com/OpenBB-finance/OpenBB) is the open-source "connect
71
+ once, consume everywhere" data platform: 100s of providers, one Python interface,
72
+ plus an MCP server for AI agents.
73
+
74
+ ```bash
75
+ pip install openbb
76
+ ```
77
+
78
+ ```python
79
+ from openbb import obb
80
+
81
+ # fundamentals & history (the research layer cluster doesn't ship)
82
+ df = obb.equity.price.historical("NVDA").to_dataframe()
83
+ fund = obb.equity.fundamental.income("NVDA").to_dataframe()
84
+ est = obb.equity.estimate.consensus("NVDA").to_dataframe()
85
+ ```
86
+
87
+ ### OpenBB MCP (agents)
88
+
89
+ OpenBB exposes an MCP server — combine with cluster's for fundamentals + execution
90
+ in one agent:
91
+
92
+ ```json
93
+ { "mcpServers": { "openbb": {
94
+ "command": "python", "args": ["-m", "openbb_mcp"],
95
+ "env": { "OPENBB_PAT": "…" }
96
+ }}}
97
+ ```
98
+
99
+ ### Division of labor
100
+
101
+ | Question type | Source |
102
+ |---|---|
103
+ | "What's NVDA doing right now?" | cluster `/api/market/quotes` |
104
+ | "Is NVDA overvalued?" | OpenBB fundamentals + your analysis |
105
+ | "What happened at the last NVDA earnings?" | OpenBB + web research (Sifter verifies) |
106
+ | "What's in the payout basket?" | cluster `/api/index/payout-basket` |
107
+
108
+ ## Persistence Loop
109
+
110
+ 1. Recall before researching: `memory_recall(bank_id, "NVDA prior findings")`
111
+ 2. Research (Scout/Sifter) — cite sources
112
+ 3. Deliver (Quill formats)
113
+ 4. Retain the conclusion + confidence + date — the next session starts smarter
114
+
115
+ That loop is the whole point: an agent that re-researches from scratch every time
116
+ is a search engine, not an analyst.
package/skills/trading/SKILL.md ADDED
@@ -0,0 +1,137 @@
1
+ ---
2
+ name: trading
3
+ description: Trade tokenized stocks and crypto on Robinhood Chain (4663) through the cluster API. Use when the user wants live quotes for tokenized stocks (NVDA, SPY, TSLA, 192 instruments) or crypto (PONS, WETH, USDG, CLIPPY, KARMA), gainers/losers and sector heat, swap quotes and execution, on-chain wallet balances, chart data, or gas and route status. Covers the full swap lifecycle — quote, route selection, calldata building, signing in the user's own wallet, and receipt parsing to prove what actually arrived.
4
+ allowed-tools: Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Bash(curl:*), Bash(python:*)
5
+ license: MIT
6
+ metadata:
7
+ author: clusteragent
8
+ version: "1.0.0"
9
+ ---
10
+
11
+ # Trading on Robinhood Chain
12
+
13
+ Tokenized stocks (192 instruments — NVDA is the deepest pool) and native crypto,
14
+ quoted through the cluster API and executed **non-custodially**: the API quotes and
15
+ builds calldata, the user's wallet signs and broadcasts. Cluster never touches a
16
+ private key.
17
+
18
+ ## Chain Reference
19
+
20
+ | Contract | Address |
21
+ |----------|---------|
22
+ | Chain | Robinhood Chain, id **4663** |
23
+ | SwapRouter02 | `0xcaf681a66d020601342297493863e78c959e5cb2` |
24
+ | QuoterV2 | `0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7` |
25
+ | WETH | `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73` |
26
+ | USDG | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` |
27
+ | Explorer | https://robinhoodchain.blockscout.com |
28
+
29
+ Fee tiers in use: **100 / 500 / 3000 / 10000** (0.01% / 0.05% / 0.3% / 1%).
30
+
31
+ ## Known Crypto Tokens
32
+
33
+ Verified addresses (from the cluster registry — on-chain checked):
34
+
35
+ ```
36
+ PONS 0x39dBED3a2bd333467115dE45665cC57F813C4571 (pool 0x10cc…26ba, WETH/500 → USDG/3000)
37
+ WETH 0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
38
+ USDG 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168
39
+ CLIPPY 0x85856f025bf13b8fd2aae2f6da458318744f1e18
40
+ KARMA 0xb47f4702deb124cb4eb6286be83c9d84277c6239
41
+ FINCH 0x879f29204a5ff842c66f0f65e0f2e422073acce7 (launchpad factory — see note)
42
+ SWOGE 0xdb87393727b666c43f5aecb03d8b419ba54d9b03 (launchpad factory — see note)
43
+ RHAGENT 0x894fac757250f8e02180e1856957274d84ac4ba3 (launchpad factory — see note)
44
+ ```
45
+
46
+ > **Factory caveat** — tokens marked *launchpad factory* have pools on a separate
47
+ > Uniswap V3 factory. SwapRouter02 (canonical factory) cannot route them: QuoterV2
48
+ > reverts. For those, either use the pons launchpad UI or the V4 Universal Router
49
+ > (`0x8876789976decbfcbbbe364623c63652db8c0904`) with Permit2. Always quote first —
50
+ > a `no route` response means the pool is not on the canonical factory.
51
+
52
+ ## Step 1 — Quote
53
+
54
+ ```bash
55
+ curl "https://HOST/api/trade/quote?token=0xNVDA&side=buy&amount=10000000000000000&via=WETH"
56
+ ```
57
+
58
+ ```json
59
+ { "ok": true, "path": "0x0bd7…300001f4d060…", "label": "WETH/500",
60
+ "amountOut": "111528000000000000", "decimals": 18, "side": "buy" }
61
+ ```
62
+
63
+ - `amount` is **wei of the input token** (buy: ETH; sell: the token)
64
+ - Route candidates are tried in order: hopped WETH→USDG→token, then direct
65
+ WETH→token across fee tiers. First pool with a quote wins.
66
+ - Route labels decode as `WETH/500` = WETH→token through the 0.05% pool.
67
+
68
+ ## Step 2 — Build Calldata
69
+
70
+ **Buy (ETH in, token out)** — router pays the first WETH hop from `msg.value`.
71
+ Do NOT wrap first (reverts with STF):
72
+
73
+ ```
74
+ multicall([
75
+ exactInput({ path, recipient: user, amountIn, amountOutMinimum }),
76
+ refundETH()
77
+ ]) → to: ROUTER, value: amountIn
78
+ ```
79
+
80
+ **Sell (token in, ETH out)** — two transactions:
81
+
82
+ 1. `approve(ROUTER, amount)` on the token (check `allowance` first — if it already
83
+ covers `amount`, skip)
84
+ 2. `multicall([ exactInput({ path, recipient: ROUTER, amountIn, amountOutMinimum }),
85
+ unwrapWETH9(minOut, user) ])` → value 0
86
+
87
+ `amountOutMinimum = quote × (10000 − slippageBps) / 10000`. Cluster default: 2%
88
+ (200 bps) — equity and thin-crypto pools move.
89
+
90
+ ## Step 3 — Sign & Broadcast (user's wallet)
91
+
92
+ wagmi:
93
+
94
+ ```ts
95
+ const hash = await sendTransactionAsync({ to: ROUTER, data, value, chainId: 4663 })
96
+ ```
97
+
98
+ ethers:
99
+
100
+ ```ts
101
+ const tx = await signer.sendTransaction({ to: ROUTER, data, value })
102
+ ```
103
+
104
+ ## Step 4 — Receipt Proof (a quote is a prediction; a receipt is proof)
105
+
106
+ Poll `eth_getTransactionReceipt` every ~4s until present. Then verify what
107
+ **actually** arrived:
108
+
109
+ - **Buy** — sum `Transfer(from, user, value)` logs emitted by the bought token
110
+ (topic0 = `0xddf252ad…b3ef`, topic2 = user address). Report the sum.
111
+ - **Sell** — ETH balance delta = `balanceAfter − balanceBefore + gasBurned`.
112
+
113
+ Report "actually received" next to the quoted amount. If they diverge materially,
114
+ the route moved — that is the user's real fill.
115
+
116
+ ## Market Data
117
+
118
+ ```bash
119
+ curl "https://HOST/api/market/quotes?symbols=NVDA,SPY,PONS" # batch + daily closes
120
+ curl "https://HOST/api/market/movers?limit=10" # gainers/losers/sectors
121
+ curl "https://HOST/api/market/chart/NVDA?tf=1mo" # series + candles
122
+ curl "https://HOST/api/trade/status" # gas, ETH price, router
123
+ curl "https://HOST/api/trade/wallet/0xADDRESS" # on-chain balances
124
+ ```
125
+
126
+ ## Safety Rules
127
+
128
+ 1. **Always quote first.** Never build a swap from a stale or assumed price.
129
+ 2. **Never exceed the user's stated amount.** `MAX` means the wallet's full ETH
130
+ balance minus gas headroom, confirmed with the user.
131
+ 3. **Default slippage 2%.** Raise only with the user's explicit ask; the pool may
132
+ revert at `amountOutMinimum`.
133
+ 4. **Show the route.** Users see `WETH/500 → USDG/3000` style labels before signing.
134
+ 5. **Sell requires approval.** Check `allowance(user, ROUTER) ≥ amount` before
135
+ building the swap tx; if not, the approval tx comes first, separately.
136
+ 6. **`no route` is an answer.** It means the pool is on the launchpad factory — do
137
+ not retry forever, tell the user.