shoal-cognition

Installable CLI for the public Shoal Cognition graph.

npx -y shoal-cognition@latest setup
npx -y shoal-cognition@latest setup --client all
npx -y shoal-cognition@latest install-codex
shoal-cognition meta
shoal-cognition search "stablecoins"
shoal-cognition retrieve "dashboards agents mcp"
shoal-cognition node x402-default-rail
shoal-cognition neighbors x402-default-rail
shoal-cognition pull
shoal-cognition mcp

Set SHOAL_COGNITION_URL to override the hosted endpoint.

Local MCP

The launch path is the local read-only MCP exposed by the CLI:

{
  "mcpServers": {
    "shoal-cognition": {
      "command": "npx",
      "args": ["-y", "shoal-cognition@latest", "mcp"]
    }
  }
}

setup installs the Codex MCP entry by default by updating ~/.codex/config.toml. Use setup --client all to install Codex and print Claude/Cursor MCP config blocks. Use setup --client claude,cursor to print those config blocks without writing Codex config.

Setup primes the local cache at ~/.cache/shoal-cognition/graph.json when the hosted graph is reachable. Run shoal-cognition pull to refresh it. The local MCP will use the hosted service when reachable and fall back to the cache for graph retrieval, search, node lookup, neighbors, and snapshot. retrieve uses hybrid BM25 + local text-vector + graph-context ranking. It returns a confidence object and suppresses low-signal embedding/vector noise instead of always returning a top-k list. Inline media artifacts are returned as media_assets on their parent nodes unless the query explicitly asks for images, media, or artifacts.

Query limits are consistent across the CLI, local MCP, and hosted service:

• search: 1-50 results
• retrieve: 1-20 results

Defaults:

• REST/service endpoint: https://cognition.shoal.xyz
• Hosted MCP endpoint: https://cognition.shoal.xyz/mcp

Set SHOAL_COGNITION_MCP_URL to override the hosted MCP endpoint printed by setup.