> For the complete documentation index, see [llms.txt](https://docs.noelclaw.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.noelclaw.fun/getting-started/readme.md). # Introduction ## The runtime layer for AI. **Your AI remembers, keeps working, and survives every session.** Most AI assistants disappear when the conversation ends. Noelclaw gives them persistent state - memory that accumulates, agents that keep running, vaults that version knowledge, and workflows that continue after you close the chat. Works in **Cursor, Windsurf, Claude Desktop, ChatGPT, Zed, Hermes, Bankr, Aeon**, and anywhere [MCP](https://modelcontextprotocol.io) runs. * Website: [noelclaw.com](https://noelclaw.fun) * App: [app.noelclaw.com](https://app.noelclaw.com) * npm: [@noelclaw/mcp](https://www.npmjs.com/package/@noelclaw/mcp) * Version: `3.43.1` *** ## The three pillars ### Memory - what your AI remembers Semantic, versioned, deduplicated. Vault gives you git-style versioning and knowledge-graph links. Memory gives you semantic search with 90-day time-decay and same-session deduplication. Together they form a two-tier persistent state your AI can read from and write to. ### Agents - what runs in the background Named, persistent agents that survive across sessions. Spawn one with a goal, recall it weeks later, audit every state change via the ledger. Each agent can hold its own Base wallet address for on-chain identity. ### Workflows - what executes on a schedule Packets, automations, monitors, and deep research. Anything that runs after you close the chat - daily research that lands in your vault, DCA orders that fire weekly, multi-agent research swarms that complete async. *** ## Quick Install **Requirement:** Node.js >= 18 - check with `node --version`, download from [nodejs.org](https://nodejs.org) if needed. ### One-command setup (auto-detects all MCP clients) ```bash npx -y -p @noelclaw/mcp@3.43.1 noelclaw install ``` Detects Claude Desktop, Cursor, Windsurf, VS Code, Zed, and configures each automatically. Then restart your client. ### Claude Code ```bash claude mcp add noelclaw -s user -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp ``` ### Claude Desktop Edit your config file: * **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json` * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "noelclaw": { "command": "npx", "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"] } } } ``` Restart Claude Desktop after saving. ### Hermes ```bash hermes mcp add noelclaw -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp ``` No build step. No config required. Runs on first use. *** ## 121 Tools > **Noel Shell:** The webapp chat supports native tool calling. Shell tools let the chat spawn agents, save to vault, search memory, create automations, estimate + execute swaps, list agents, and check wallet balances — all from natural conversation. See [Noel Shell](/agents-and-workflows/noel-shell.md). Grouped by pillar — counts match the live tool registry exactly. Full catalog: [All 121 Tools](/reference/mcp-server.md). | Pillar | Category | Tools | What it does | | ------------- | --------------- | :---: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Memory** | Vault | 15 | Versioned notes: save, read, search, history, diff, export, credentials, tags, links, knowledge graph | | **Memory** | Semantic Memory | 10 | Semantic search, cross-session recall, extract, consolidate, insight, publish/delete with confirm | | **Memory** | Chronicle | 4 | Append-only audit trail — add, list, search, activity stats | | **Agents** | Agents | 12 | Persistent named agents: spawn, recall, update, identity, ledger, schedule/pause/resume, runs, hire, list | | **Agents** | Playbooks | 3 | Browse and run curated playbooks with an audit ledger | | **Workflows** | Automations | 6 | DCA, price alerts, conditional buy/sell, dry-run, pause/delete, execution history | | **Workflows** | Monitors | 3 | Scheduled research monitors: schedule, list, cancel | | **Workflows** | Packets (Flows) | 4 | Create, run, list, and share reusable workflow packets | | **Workflows** | Research | 3 | `deep_research` (keyless evidence packs), compare two reports, walk a research chain | | **Execution** | Base DeFi | 12 | `base_mcp_*`: balances with impostor detection, send, 0x Permit2 swaps, Morpho/Moonwell yields, basenames — see [Base](/trading-and-defi/base.md) | | **Execution** | Robinhood Chain | 14 | `rh_*`: 22 tokenized stocks + any RH-chain crypto, V2/V3/V4 best-fill routing, risk screens, DCA/TP/SL orders, stock bridge — see [Robinhood Chain](/trading-and-defi/robinhood.md) | | **Execution** | Stocks (SEC) | 3 | Fundamentals (XBRL), insider trades (Form 4), material events (8-K) — see [Stocks & SEC Data](/trading-and-defi/stocks-sec.md) | | **Execution** | Market Data | 6 | Live prices, token data, market overview, OHLC history, market thesis | | **Execution** | Token Scanner | 3 | Score, safety-check, and compare tokens on Base | | **Execution** | Web Research | 2 | Live web search + scrape any URL (proxied, keyless) | | **Execution** | GitHub | 8 | Repos, PRs, issues, files, commits, code search (read-only) | | **Execution** | Code Audit | 1 | Static Solidity security scan with review rubric | | **Execution** | Insight | 3 | `ask_noel`, trade planning, DeFi yields | | **Execution** | MiroShark | 3 | Multi-agent market simulation | | **Execution** | Wallet | 3 | Wallet address, live balance with USD pricing, EIP-191 message signing | | **Runtime** | OS | 3 | `noel_status` dashboard, `noel_diagnostics` health check, Noel Shell chat bridge | *** ## What's New ### v3.43.1 - x402 API Market, Robinhood Chain Trading, 121 Tools * **x402 API Market** — sell any HTTPS API per call, buy with USDC on Base via the x402 protocol (HTTP 402 challenge → pay → retry with `PAYMENT-SIGNATURE`). No account or API key needed for buyers. Payments are replay-protected at both the request-id and tx-hash level. See [x402 API Market](/trading-and-defi/x402-api-market.md). * **Robinhood Chain rail (`rh_*`)** — 22 tokenized stocks (added NFLX, SPY, QQQ, GME) plus trending chain tokens, arbitrary crypto by ticker or contract address, V2/V3/V4 best-fill routing, receipt-backed swap confirmations, safety scans (`rh_analyze`, `rh_safety_check`), DCA/TP-SL order engine. * **Investor triad from SEC primary sources, all keyless** — `stock_fundamentals` (XBRL financials), `stock_insider` (Form 4), `stock_events` (8-K decoded), plus `rh_stock_bridge` (tokenized vs real price + pool depth). * **Client-first refactor** — tools return evidence and structure; your model does the reasoning. `deep_research` works with zero API keys (`mode: "sources"`). * **Cleaner metadata** — tool count corrected to 121 everywhere, emoji removed from all tool and package descriptions. ### v3.32.7 - Local Memory, OpenAI BYOK, Critical Install Fix * **Local memory** — run memory tools on a free, self-hosted [supermemory](https://github.com/supermemoryai/supermemory) server on your own machine. Zero cost, private, no Noelclaw account or Convex proxy needed once enabled. Run `noelclaw setup` to switch. *(Beta - code-reviewed and unit-verified, live-server testing pending.)* * **OpenAI BYOK** — OpenAI joins Bankr/Anthropic/Grok as a direct LLM provider. `OPENAI_BASE_URL` lets you route to any self-hosted OpenAI-compatible gateway instead (LiteLLM, vLLM, Ollama, OpenRouter, your own VPS). * **`noelclaw setup`** — new guided CLI wizard for picking an LLM provider and/or enabling local memory in one flow. * **Critical fix** — `noelclaw install` was writing a broken MCP server entry (`npx -y @noelclaw/mcp@latest`, ambiguous bin resolution) into every detected client config, so every fresh auto-install was non-functional. Fixed to the unambiguous, version-pinned form. ### v3.32.5 - Chronicle Search, execute\_swap, Live Wallet Pricing, Diagnostics * **`execute_swap`** — execute token swaps on Base mainnet from Noel Shell. Enforces estimate → confirm → execute flow. Routes via 0x Permit2. Returns tx hash + Basescan link. Hard-blocked without `confirmed=true`. * **`chronicle_search`** — keyword search across runtime events by title and detail. Find when your agent last researched any topic without scrolling the full log. * **`chronicle_stats`** — runtime activity analytics: event breakdown by type, daily heatmap, busiest days, avg events/day over a configurable window (default 30 days, max 90). * **`get_wallet_balance`** — live ETH + USDC balance from Base mainnet with real-time USD pricing from CoinGecko. No API key required. * **`wallet_sign_message`** — EIP-191 personal\_sign to prove wallet ownership off-chain without sending a transaction. * **`noel_diagnostics`** — pre-flight health check: pings Convex, Firecrawl, Supermemory; lists configured API keys; warns on missing LLM key or Firecrawl key with actionable hints. * **Base Builder Code** — all x402 payment flows now include `bc_7diuqbqo` as `builderCode`. Transactions are attributed to Noelclaw in the Base Dashboard. ### v3.31.0 - Noel Shell, Multi-Provider Chat, Security Hardening * **Noel Shell** - native tool calling from the webapp chat. Shell tools: `spawn_agent`, `save_to_vault`, `search_memory`, `create_automation`, `estimate_swap`, `list_agents`, `get_wallet_balance`. The chat can now act, not just answer. See [Noel Shell docs](/agents-and-workflows/noel-shell.md). * **7 Agents** - Noel (crypto), CoinGecko (crypto data), Sage (analysis), Forge (developer), Quill (creative), Spectre (trading), Atlas (general). Each agent has its own persona and tool access. * **Multi-provider chat** - provider cascade: Bankr → OpenAI → Anthropic → Groq → OpenRouter → Custom → Local fallback. No single provider dependency. * **ConnectMcpModal** - onboarding flow for connecting the MCP server to your IDE directly from the webapp. * **Security hardening** - 8 security boundaries enforced + vulnerability fixes: `getDecryptedPKByUserId` → internalAction, `createWallet` → internalAction, `getPrivateKey` returns address only (never raw key). Auth is Privy + API key only (OTP removed Jul 2026). * **Theme refresh** - Claude-style warm palette, Inter font, neural-network knowledge-graph visual. ### v3.23.1 - Polish * **Memory dedup** - `memory_add` deduplicates identical content via SHA-256 hash with in-process LRU cache + recent-memories lookup. `force: true` overrides. * **Agent race-safe** - concurrent `agent_update` calls on the same agent serialize through a per-name async mutex. No more silent write loss. * **Automation dry-run + error categories** - `run_automation dryRun: true` simulates without broadcasting. Failed runs show category badges (`INSUFFICIENT_BALANCE`, `QUOTE_FAILED`, `TX_REVERTED`, etc.) with one-line fix suggestions. * **MCP Resources pagination** - vault entries past the 50th are now visible to clients via cursor pagination. MIME types derive from `contentType` (markdown/json/code/text). ### v3.22.0 - UX * **HTTP cache + 429 backoff** - every external API call (CoinGecko, DexScreener, GeckoTerminal) flows through a 45s LRU + exponential backoff that honors `Retry-After`. Agent loops can't trip rate limits anymore. * **MEV-protect RPC opt-in** - `NOELCLAW_BROADCAST_RPC=` routes signed transactions through a private relay. Reads stay on the fast Base RPC. * **Tool count drift fixed** - banner, login, and `noelclaw doctor` all derive counts from the actual registered tools. No more 104/110/36/100+ mismatch. * **Humanizer model pin** - `NOELCLAW_HUMANIZER_MODEL` lets you lock the model used by `humanize_text` and `write_content` for consistent voice. ### v3.21.0 - Safety * **Slippage + price-impact guards** - `swap_tokens` and `base_mcp_swap` refuse execution when price impact exceeds `maxPriceImpactPct` (default 3%). Default slippage cap 1%. Configurable per call. * **Silent supermemory sync fixed** - retries 3× exponential, logs to chronicle on permanent failure. No more ghost memories that exist in one tier but not the other. * **SWARM\_TOOLS zombie removed** - dead dispatch handler cleaned up. Multi-agent research is built into `deep_research` now (`depth: "standard" | "deep"`). ### v3.20.0 - Grounding & streaming * **`audit_contract` grounded** - 13-pattern static Solidity scan runs before the LLM, mandatory disclaimer appended, no more "secure"/"safe" claims. * **`github_search_code` helpful error** - clear setup instructions and a link to `https://github.com/settings/tokens` when `GITHUB_TOKEN` is missing. * **`memory_search` time-decay** - 90-day half-life weighting + promotion hints when 4+ memories cluster on a topic. * **Pyth oracle in `fetchVerifiedPrice`** - cross-source price verification against CoinGecko + DexScreener + Pyth with disagreement detection. * **`deep_research` streaming progress** - MCP `notifications/progress` for long-running multi-agent research. * **`noelclaw doctor`** - 5-second CLI health check with ✓/⚠/✗ status and inline fix hints. *** ## Docs * [Getting Started](/getting-started/getting-started.md) * [Install on Claude](/install-by-client/claude-install.md) * [Install on Cursor / Windsurf](/install-by-client/cursor-install.md) * [Install on Hermes](/install-by-client/hermes-openclaw.md) * [Semantic Memory Guide](/memory-and-knowledge/memory.md) * [Chronicle (Audit Trail)](/memory-and-knowledge/chronicle.md) * [Packets (Flows)](/agents-and-workflows/packets.md) * [Full MCP Tool Reference](/reference/mcp-server.md) * [MiroShark Simulation](/agents-and-workflows/miroshark.md) * [Wallet & DeFi](/trading-and-defi/wallet-defi.md) * [Environment Variables](/reference/env-vars.md) * [Architecture](/reference/architecture.md) * [Noel Shell](/agents-and-workflows/noel-shell.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.noelclaw.fun/getting-started/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.